test: make tests/ mirror the source tree; drop issue numbers from filenames

`scripts/run_tests.sh tests/<dir>/` is how a change gets its regression
coverage run, so a test filed under the wrong directory is a test nobody
runs when that code changes. Two kinds of drift had accumulated.

Parallel directories for one source package, folded into the mirror:
  tests/acp        -> tests/acp_adapter   (its __init__/conftest move with it)
  tests/cli        -> tests/hermes_cli    (prompt_toolkit fixture merged into
                                           hermes_cli/conftest.py)
  tests/run_agent  -> tests/agent         (backoff fixture becomes
                                           agent/conftest.py)
  tests/relay      -> tests/gateway/relay
  tests/state      -> tests/hermes_state

246 loose files at tests/ root, routed by the package they import/patch:
hermes_cli, hermes_state, agent, gateway, tools, plugins, tui_gateway, cron.
Installer and desktop-update script tests go to tests/scripts/{install,
desktop_update}/. 43 tests of root-level modules (batch_runner, utils,
hermes_constants, packaging) stay at the root.

Filenames drop their issue numbers (95 files: test_89315_x.py -> test_x.py);
the number stays in the module docstring where it has context.

Collisions: test_cli_skin_integration.py existed in both tests/ and tests/cli
with different subsets — merged into one (10 tests, all kept);
run_agent/test_pre_compress_memory_context.py -> agent/..._handoff.py;
tests/test_account_usage.py -> agent/test_account_usage_fetch.py;
tests/test_web_server.py -> hermes_cli/test_web_server_ws_ping.py.
Deleted: test_minisweagent_path.py (empty since PR #2804),
test_model_picker_scroll.py (tested a private copy of the logic, imported
nothing), test_process_loop_event_loop_warning.py (asserted asyncio behaviour,
imported nothing from Hermes).

Repo-root path arithmetic (Path(__file__).parents[N], dirname chains) is
bumped for the 202 files that changed depth and verified by evaluating every
such expression against the new location. classify_changes' desktop-updater
lane prefix, tests-os.yml's ignore glob and every in-tree path comment follow
the moves. tests/test_tests_tree_layout.py keeps the tree from drifting back.

.github/workflows/tests-os.yml

@@ -31,7 +31,7 @@ on:
       desktop_updater:
         description: >-
           Run the Windows desktop-update hand-off integration tests
-          (tests/test_desktop_update_windows_*.py). These spawn the real
+          (tests/scripts/desktop_update/test_desktop_update_windows_*.py). These spawn the real
           scripts/desktop-update/windows.ps1 and poll its loopback server, so
           they carry process-timing noise a shared runner amplifies; the
           caller gates them on the classifier's desktop_updater lane so a PR
@@ -156,7 +156,7 @@ jobs:
           # an unbound-variable error, hence the ``${arr[@]+...}`` idiom.)
           EXTRA_ARGS=()
           if [ "${{ inputs.desktop_updater }}" != "true" ]; then
-            echo "desktop_updater lane off: skipping tests/test_desktop_update_windows_*.py"
+            echo "desktop_updater lane off: skipping tests/scripts/desktop_update/test_desktop_update_windows_*.py"
             EXTRA_ARGS+=(--ignore-glob='*test_desktop_update_windows_*.py')
           fi
 

AGENTS.md

@@ -330,7 +330,12 @@ scripts/run_tests.sh -v --tb=long                       # pytest flags pass thro
   `HERMES_TEST_FILE_RETRIES=0` disables). Pass-on-retry is green but printed under `⚠ FLAKY`
   with both outputs — a bug to fix, not noise. Timing tests must not assume a quiet runner:
   wall-clock bounds ≥ 2s, event-based sync, no `assert not _wait_until(...)` races.
-- **Placement:** `scripts/ci/classify_changes.py` picks jobs by changed files. A Python test
+- **Placement mirrors the source tree.** A test lives in `tests/<top-level source dir>/` (`tests/hermes_cli/`,
+  `tests/agent/`, `tests/hermes_state/`, `tests/gateway/relay/`, ...); installer/updater script tests
+  under `tests/scripts/{install,desktop_update}/`. Only tests of root-level modules (`batch_runner`,
+  `utils`, `hermes_constants`, packaging) sit directly in `tests/`. No issue numbers in filenames —
+  cite the issue in the module docstring (`test_89315_x.py` → `test_x.py`, "Regression for #89315").
+- **Placement (CI lanes):** `scripts/ci/classify_changes.py` picks jobs by changed files. A Python test
   asserting about `package.json`, `package-lock.json`, `tsconfig.json`, or `.ts/.tsx/.js/
   .mjs/.cjs` sources will not run on a JS-only PR (green on PR, red on `main` where the
   classifier fails open). Such tests belong in the vitest suite, not `tests/*.py`.

agent/activity_tracking.py

@@ -49,7 +49,7 @@ class ActivityTrackingMixin:
         kanban heartbeat when this is a dispatcher-spawned worker, and to the durable SessionDB activity
         projection. ``provenance`` names special writers (compression); ``force_persist`` bypasses the
         SessionDB rate limit. Module-level lock helper, not ``self._liveness_activity_lock()``: doubles bind
-        only ``_touch_activity`` (tests/run_agent/test_session_activity_persist.py).
+        only ``_touch_activity`` (tests/agent/test_session_activity_persist.py).
 
         Bridge is rate-limited (60s) and best-effort — it never raises into the agent loop. See #31752.
         See #72016, #72039.

agent/agent_runtime_helpers.py

@@ -1735,7 +1735,7 @@ def create_openai_client(agent, client_kwargs: dict, *, reason: str, shared: boo
             return client
     # TCP keepalives so dead provider connections are detected (~60s) instead of hanging in
     # CLOSE-WAIT. Injected into the local copy only, so each client gets its own httpx.Client;
-    # pinned by tests/run_agent/test_create_openai_client_reuse.py and
+    # pinned by tests/agent/test_create_openai_client_reuse.py and
     # test_sequential_chats_live.py. What IS shared across those per-client wrappers is the
     # connection pool: ``build_keepalive_http_client`` mounts a process-shared ``HTTPTransport``
     # behind a per-client view whose ``close()`` is a no-op for the pool, so a closed wrapper
@@ -2320,7 +2320,7 @@ def repair_tool_call(agent, tool_name: str) -> str | None:
     # character so the rest of the repair pipeline (lowercase / snake_case / fuzzy match) can resolve the
     # cleaned name to a real tool. Crucially we DO NOT split on whitespace: legitimate inputs like "write
     # file" must keep flowing through ``_norm`` -> ``write_file`` (covered by test_space_to_underscore in
-    # tests/run_agent/test_repair_tool_call_name.py). See #33007.
+    # tests/agent/test_repair_tool_call_name.py). See #33007.
     for _xml_sep in ('"', "'", "<", ">"):
         _idx = tool_name.find(_xml_sep)
         if _idx > 0:

cli.py

@@ -2147,7 +2147,7 @@ def _terminal_may_leak_cpr() -> bool:
 
     Delayed CPR replies (``ESC[<row>;<col>R`` / visible ``^[[<row>;<col>R``) leak into the status line and
     can freeze input when the reply is slow (#13870 on SSH/slow PTYs). The same race hits local POSIX TTYs
-    under heavy subagent / status-line load — see ``tests/cli/test_cpr_local_leak.py``.
+    under heavy subagent / status-line load — see ``tests/hermes_cli/test_cpr_local_leak.py``.
     """
     return os.environ.get("PROMPT_TOOLKIT_NO_CPR", "") == "1" or sys.platform != "win32"
 

hermes_cli/cli_info_mixin.py

@@ -459,7 +459,7 @@ class CLIInfoMixin:
         Dispatched from the input loop BEFORE slash routing and before anything is queued for the
         agent, so a bang command never becomes a turn: nothing touches ``conversation_history``,
         zero tokens, role alternation / prompt caching untouched by construction
-        (tests/cli/test_bang_shell_mode.py). Returns False when the text is not a bang command or
+        (tests/hermes_cli/test_bang_shell_mode.py). Returns False when the text is not a bang command or
         bang mode is disabled for this context (gateway/cron), so the caller routes normally.
         """
         from cli import _rich_text_from_ansi

hermes_cli/default_soul.py

@@ -49,7 +49,7 @@ _LEGACY_TEMPLATE_SOULS = (
         "investigations."
     ),
     # ASCII-dashed variant seeded by scripts/install.ps1 (must stay pure ASCII, see
-    # tests/test_install_ps1_ascii_only.py); upgrading converges Windows installs on the em-dash text.
+    # tests/scripts/install/test_install_ps1_ascii_only.py); upgrading converges Windows installs on the em-dash text.
     DEFAULT_SOUL_MD.replace("\u2014", "--"),
 )
 

hermes_state_portability.py

@@ -534,7 +534,7 @@ class SessionPortabilityMixin:
         / ``last_activity_description`` / ``last_activity_provenance``) because they are part of the durable
         row, but import deliberately RESETS them to NULL. This asymmetry is intentional and covered by
         regression
-        (tests/gateway/test_watchdog_review_76354.py::test_s4_export_includes_activity_import_resets_it).
+        (tests/gateway/test_watchdog_review.py::test_s4_export_includes_activity_import_resets_it).
         """
         if not isinstance(sessions, list):
             raise ValueError("sessions must be a list")

scripts/ci/classify_changes.py

@@ -131,7 +131,7 @@ _INSTALLER_FILES = {"scripts/install.ps1", "scripts/install.cmd"}
 # Windows desktop-update hand-off (scripts/desktop-update/windows.ps1 + the
 # Electron side that launches it) and the pytest files that spawn it.
 _DESKTOP_UPDATER_PATHS = ("scripts/desktop-update/",)
-_DESKTOP_UPDATER_TEST_PREFIX = "tests/test_desktop_update_"
+_DESKTOP_UPDATER_TEST_PREFIX = "tests/scripts/desktop_update/"
 _DESKTOP_UPDATER_FILES = {
     "apps/desktop/electron/updater-process.ts",
     "apps/desktop/electron/managed-ssh-update.ts",

scripts/desktop-update/posix.sh

@@ -629,7 +629,7 @@ tcc_pick_update_invoke() { # sets UPDATE_INVOKE; safety net past a failed heal
 # ── self-tests: no update, touch nothing ────────────────────────────────────
 if [ "$SELF_TEST_TCC_HEAL" -eq 1 ]; then
   # Runs the REAL heal + invoke selection against --install-root and reports;
-  # tests/test_desktop_update_tcc_heal.py drives the state matrix through it.
+  # tests/scripts/desktop_update/test_desktop_update_tcc_heal.py drives the state matrix through it.
   trap - EXIT
   tcc_anchor_heal "$INSTALL_ROOT/venv/bin" || true
   tcc_pick_update_invoke "$INSTALL_ROOT/venv/bin"

scripts/run_tests.sh

@@ -17,7 +17,7 @@
 #   scripts/run_tests.sh                            # full suite
 #   scripts/run_tests.sh -j 4                       # cap parallelism
 #   scripts/run_tests.sh tests/agent/               # discover only here
-#   scripts/run_tests.sh tests/agent/ tests/acp/    # multiple roots
+#   scripts/run_tests.sh tests/agent/ tests/acp_adapter/    # multiple roots
 #   scripts/run_tests.sh tests/foo.py               # single file
 #   scripts/run_tests.sh tests/foo.py -q            # path + bare pytest flag
 #   scripts/run_tests.sh tests/foo.py -v --tb=long  # bare flags "just work"

scripts/run_tests_parallel.py

@@ -508,8 +508,8 @@ def _parse_pytest_summary(output: str) -> dict[str, int]:
 
 def _format_file(file: Path, repo_root: Path) -> str:
     """Render a test-file path for display: strip the repo-root prefix
-    when possible so output reads ``tests/acp/test_auth.py`` instead of
-    ``/home/runner/work/hermes-agent/hermes-agent/tests/acp/test_auth.py``.
+    when possible so output reads ``tests/acp_adapter/test_auth.py`` instead of
+    ``/home/runner/work/hermes-agent/hermes-agent/tests/acp_adapter/test_auth.py``.
 
     Falls back to the absolute path for anything outside the repo root.
     """

tests/acp_adapter/conftest.py

@@ -1,4 +1,4 @@
-"""Shared fixtures for tests/acp.
+"""Shared fixtures for tests/acp_adapter.
 
 Keeps the ACP server tests offline: ``HermesACPAgent._build_model_state``
 calls ``hermes_cli.inventory.build_models_payload``, which (without this

tests/acp_adapter/test_approval_isolation.py

@@ -23,7 +23,7 @@ from tools import approval_context
 def _isolate_approval_state(monkeypatch):
     """Keep these security regression tests hermetic.
 
-    Earlier tests (e.g. tests/acp/test_permissions.py) lazily load the
+    Earlier tests (e.g. tests/acp_adapter/test_permissions.py) lazily load the
     developer's real ``~/.hermes/config.yaml`` command allowlist into
     ``tools.approval._permanent_approved``. If that allowlist contains a
     pattern like "recursive delete", ``rm -rf …`` is auto-approved before

tests/agent/conftest.py

@@ -1,4 +1,4 @@
-"""Fast-path fixtures shared across tests/run_agent/.
+"""Fast-path fixtures shared across tests/agent/.
 
 Many tests in this directory exercise the retry/backoff paths in the
 agent loop. Production code uses ``jittered_backoff(base_delay=5.0)``

tests/agent/repro_image_shrink_brick.py

@@ -16,11 +16,11 @@ brought under the cap and that the helper reports success.
 
 Run directly to see a human-readable report:
 
-    python tests/run_agent/repro_48013_image_shrink_brick.py
+    python tests/agent/repro_image_shrink_brick.py
 
 Or as a pytest smoke test (skipped automatically when Pillow is absent):
 
-    scripts/run_tests.sh tests/run_agent/repro_48013_image_shrink_brick.py
+    scripts/run_tests.sh tests/agent/repro_image_shrink_brick.py
 """
 
 from __future__ import annotations

tests/agent/test_auxiliary_user_default_headers.py

@@ -1,6 +1,6 @@
 """Tests for user-configured ``model.default_headers`` in the auxiliary client.
 
-Companion to ``tests/run_agent/test_provider_attribution_headers.py`` (which
+Companion to ``tests/agent/test_provider_attribution_headers.py`` (which
 covers the main agent client). The main agent turn and the auxiliary client
 (title generation, context compression, vision routing) build separate OpenAI
 clients, so a ``custom`` endpoint behind a gateway/WAF that rejects the OpenAI

tests/agent/test_background_review_list_shapes.py

@@ -43,7 +43,7 @@ import sys
 import types
 
 
-REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 
 def _isolate_hermes_home():

tests/agent/test_bitwarden_secrets.py

@@ -24,7 +24,7 @@ import pytest
 
 
 # Make the worktree importable without depending on the installed wheel.
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
 if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 

tests/agent/test_command_secret_source.py

@@ -27,7 +27,7 @@ from pathlib import Path
 
 import pytest
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
 if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 

tests/agent/test_compression_lock_defer.py

@@ -35,7 +35,7 @@ LOCK_HOLDER = "pid=4242:tid=1:agent=deadbeef:nonce=abcd1234"
 
 
 # ---------------------------------------------------------------------------
-# Helpers (mirrors tests/run_agent/test_413_compression.py)
+# Helpers (mirrors tests/agent/test_413_compression.py)
 # ---------------------------------------------------------------------------