Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/hooks/scope-guard.sh:
- Around line 19-24: The TEAM_FILE path is hardcoded to a specific swarm run and
team and must be made dynamic; modify scope-guard.sh to build TEAM_FILE from
environment variables (e.g., SWARM_RUN_DIR or SWARM_RUN_ID and TEAM_ID) or by
resolving a runtime TMPDIR/swarm-local* pattern instead of the fixed
"/tmp/swarm-local-20260315-232322-26058/team-3/.swarm/current-team.txt"; update
the TEAM_FILE assignment in the script (referencing the TEAM_FILE variable and
scope-guard.sh) to use those env vars or a safe glob fallback, validate the
resolved path exists before using it, and preserve the existing behavior of
exiting 0 when no team file is found.
- Around line 99-107: The hardcoded cross-team requests path in scope-guard.sh
should be made dynamic like the TEAM_FILE fix: replace the literal
"/tmp/.../team-3/.swarm/cross-team-requests.md" with the appropriate variable or
computed value (e.g. use $TEAM_FILE or construct from the same base variable
used for TEAM_FILE/$SWARM_TMP/$TEAM) so the notification writes to the correct
team's .swarm/cross-team-requests.md; update the echo lines that reference that
path to use the chosen variable (refer to FILE, TEAM and TEAM_FILE in the
script).

In @.claude/settings.json:
- Around line 4-5: The PostToolUse and Stop hook commands in
.claude/settings.json currently hardcode the swarm run path; update the hook
"command" strings for the PostToolUse entry referencing no-todos.sh and the Stop
entry referencing final-build-check.sh to use the $worktree variable (e.g.,
$worktree/.claude/hooks/no-todos.sh and
$worktree/.claude/hooks/final-build-check.sh) instead of the literal /tmp/...
path so the hooks are portable and consistent with the PreToolUse usage.

In `@CLAUDE.md`:
- Around line 108-111: The README references
/workspace/.swarm/cross-team-requests.md but scope-guard.sh uses a different
hardcoded path; update the documentation to match the path actually used by
scope-guard.sh (or vice versa after you fix the hardcoded path in
scope-guard.sh) so both refer to the same file; search for scope-guard.sh and
the cross-team-requests filename and make the paths consistent in CLAUDE.md and
the scope-guard.sh implementation.

In `@gateway/run.py`:
- Around line 189-191: The early TCP site is started on _early_port but never
cleaned up before the full dashboard binds the same port, causing an "address
already in use" when HermesWebAPI.start(port=_dashboard_port) is scheduled; fix
by ensuring the early runner is properly stopped before starting the full API —
call and await _early_runner.cleanup() (or otherwise stop the TCPSite) before
you schedule/create the HermesWebAPI.start task, or restructure the handoff so
the same underlying runner/site is reused; ensure any create_task() that invokes
HermesWebAPI.start is executed only after the cleanup completes and wrap the
transition in a try/finally so _early_runner.cleanup() always runs on handoff.

In `@output/team-2-done.md`:
- Around line 6-8: Update the port-resolution summary to state that
`gateway/run.py` resolves `_dashboard_port` (and `_early_port`) once at import
time and reuses that value, rather than re-resolving it via `global` inside
`start_gateway()` or `GatewayRunner`; specifically edit the sentence referencing
re-resolution to remove the claim about runtime re-resolution and mention the
single import-time resolution of `_dashboard_port` and `_early_port` in
`gateway/run.py`.

In `@tests/test_port_env_var.py`:
- Around line 131-140: The test currently checks source text for "8080" which is
brittle; change test_web_api_host_port_from_env to patch os.environ
{"PORT":"8888"} and assert at runtime that HermesWebAPI.start is invoked with
the env-derived port (or that the instance uses that port) by spying/mocking the
call path: import gateway.web_api.HermesWebAPI, patch/monkeypatch
HermesWebAPI.start or its internal server-launch method to capture the port
argument, then call the code path that starts the server and assert the captured
port equals 8888; reference HermesWebAPI and its start (or the specific internal
method used to bind/listen) to locate where to attach the spy.
- Around line 24-29: The top-level manipulation of sys.modules via _STUBS =
["dotenv", "yaml"] and the loop that inserts MagicMock instances causes global
test pollution; change this to scope the stubs per-test using a fixture or
context-managed patch.dict from unittest.mock (or pytest's monkeypatch) to
temporarily inject mocks for "dotenv" and "yaml" and restore sys.modules after
each test; locate the current top-level _STUBS, the loop that writes to
sys.modules, and replace it with a fixture (or wrap individual tests) that uses
patch.dict(sys.modules, {...}) or monkeypatch.setitem to set MagicMock objects
for those module names so the stubbing is reverted after the test.

In `@tests/test_telegram_polling_conflict.py`:
- Around line 29-31: The current module-level loop writing to sys.modules with
MagicMock should be removed and replaced by a fixture that applies patch.dict to
scope the stubs; create a pytest.fixture (e.g., stub_optional_deps) that uses
unittest.mock.patch.dict(sys.modules, {...}) or pytest's monkeypatch.setitem for
each of the module names ("dotenv","yaml","telegram","telegram.ext") to insert
MagicMock instances, yield control, and let the patch be undone after the test
scope so the global sys.modules is not mutated across tests; update tests to
accept and use that fixture instead of relying on the module-level mutation.
- Around line 210-223: Replace the current assertions-only tests with ones that
actually exercise the routing path: monkeypatch or mock
TelegramPlatform._handle_polling_conflict, instantiate a TelegramPlatform (or
get the instance used in polling), then invoke the polling-error routing
method/path that calls _looks_like_polling_conflict (i.e., the method that
receives polling exceptions and routes them to _handle_polling_conflict); assert
that for an exception whose text causes
TelegramPlatform._looks_like_polling_conflict to return True the mocked
_handle_polling_conflict was called, and for a non-conflict exception it was not
called.

In `@tests/test_tirith_optional_install.py`:
- Around line 31-35: The test currently mutates sys.modules at top-level by
inserting MagicMock entries for "dotenv", "yaml", "requests", and
"requests.exceptions", which is process-global and can break other tests; change
this to scope the stubs using unittest.mock.patch.dict (or a pytest fixture that
yields and restores) so the replacements for sys.modules are applied only during
the test run and restored afterwards—wrap the sys.modules modifications in a
patch.dict context manager or a fixture that sets sys.modules entries for those
keys and removes/restores them in teardown; look for the top-level loop that
writes to sys.modules and replace it with a scoped patch using patch.dict or a
fixture to ensure isolation.
- Around line 270-305: Both tests only inspect source or import the module
without exercising the startup path that calls tirith_security.ensure_installed;
update them to actually execute the startup logic so regressions are caught. For
test_gateway_startup_wraps_tirith_in_try_except, reload or import gateway.run in
a context where you patch tools.tirith_security.ensure_installed with a callable
(or MagicMock) and then invoke the startup entry point that runs the install
logic (e.g., call run.main() or importlib.reload(run) if the call happens at
import time) and assert the patched ensure_installed was invoked; for
test_tirith_import_error_does_not_crash_gateway, patch
sys.modules["tools.tirith_security"] to raise ImportError on import and then
reload/import gateway.run (or call the startup function) to ensure no
ImportError is propagated, failing the test if an exception escapes.
- Around line 37-41: _purge_tirith_module currently removes any module whose
name contains "tirith", which can delete unrelated modules (including this
test). Update the filter in _purge_tirith_module so it only targets the tirith
package namespace, e.g. keep modules whose names are exactly
"tools.tirith_security" or start with "tools.tirith_security." (use name ==
"tools.tirith_security" or name.startswith("tools.tirith_security.")) and delete
only those entries from sys.modules; leave other modules intact.
- Line 223: The current assertion uses "or result is None" which makes it
non-binding; change it to explicitly assert the module reset and that the retry
path produced a result: replace "assert mod._resolved_path is not
mod._INSTALL_FAILED or result is None" with two explicit checks such as "assert
mod._resolved_path is None" (or the specific reset sentinel used by the code)
and "assert result is not None" (or an assertion that the retry
flag/counter/logging was triggered) so the reset state and retry outcome are
both verified; reference mod._resolved_path, mod._INSTALL_FAILED, and result
when making the replacement.

---

Nitpick comments:
In @.claude/hooks/final-build-check.sh:
- Around line 13-23: The current fragile grep checks should be replaced with a
precise JSON check using jq to detect scripts.build and scripts.typecheck;
update the if-conditions that set BUILD_CMD so they first test for jq (command
-v jq >/dev/null 2>&1) and then use jq -e '.scripts.build' package.json
>/dev/null 2>&1 to set BUILD_CMD="bun run build" or "npm run build", and
similarly use jq -e '.scripts.typecheck' to set BUILD_CMD="npm run typecheck";
keep a fallback to the existing grep checks only when jq is not available, and
ensure BUILD_CMD assignments remain unchanged.
- Around line 8-9: The script defines an unused INPUT variable by capturing
stdin into INPUT (INPUT=$(cat)) even though the Stop hook doesn't use
tool_input; remove that unused assignment to clean up the script—either delete
the INPUT=$(cat) line entirely or, if you still need to consume stdin for
side-effect, replace it with a no-op consumption (e.g., cat to /dev/null) so the
INPUT variable and its assignment are removed; locate the INPUT assignment in
the final-build-check.sh hook and remove or replace it accordingly.

In @.claude/hooks/no-todos.sh:
- Around line 25-33: The grep pattern for MATCHES uses a case-insensitive 'stub'
which causes false positives; update the grep invocation to use a word-boundary
version of that pattern (e.g., '\bstub\b') and enable extended/Perl regex so \b
is supported (add the -E or -P flag to the grep options), leaving the other
patterns unchanged; locate the MATCHES assignment and replace the '-e 'stub''
entry with the word-boundary variant and add -E (or -P) to the grep flags so
only the standalone word "stub" is matched.

In @.claude/hooks/scope-guard.sh:
- Around line 33-37: The case pattern in the scope guard (the branch matching
NORM_FILE) is too permissive—patterns like *.md, *.json, *.yaml, etc. match
files at any directory depth; restrict these to root-level files by matching
paths that contain no slash. Update the case block that references NORM_FILE and
replace glob patterns such as *.md, *.json, *.yaml, *.yml, *.toml, and
*.env.example with anchored no-slash patterns (for example use [^/]*.md,
[^/]*.json, [^/]*.yaml, [^/]*.yml, [^/]*.toml, [^/]*.env.example) so only files
in the repository root are allowed, while keeping existing directory whitelists
like .swarm/*, output/*, and tasks/* intact.

In `@output/test-results.json`:
- Line 1: This file contains execution-local metadata (the "attempt" field in
test-results.json) and should not be committed; remove output/test-results.json
from the repo (delete the committed file and commit that deletion), add the
filename or its containing output directory to .gitignore so future runs don’t
reintroduce it, and instead emit this per-run JSON as a CI artifact or store it
outside version control (or produce a stable summary file without run-specific
fields) so repeated test runs do not churn the repository.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@gateway/run.py`:
- Around line 185-193: Replace the direct int(...) import-time assignment for
_dashboard_port with a small validated parser: create a helper (e.g.,
parse_port_env) that reads PORT and DASHBOARD_PORT, attempts to parse ints
safely, checks that the resulting value is within 1–65535, and returns the first
valid port or the fallback 3001; use that helper to set _dashboard_port and then
set _early_port = _dashboard_port, and ensure invalid or non-numeric env values
do not raise on import (log or warn instead and use the fallback).