fix(daemon): stop --dev-src-dir errors from suggesting paths that don't exist

[github-actions]

Anyone who mistyped --dev-src-dir on gaia daemon start-agent was told to retype the same typo with hub/agents/<id>/python stapled on the end — a path that had never existed. Point it at another agent's source directory and the "fix" was to nest that directory inside itself, when the real mistake was naming the wrong agent. Now the error only names a concrete path when that path is actually on disk, calls out a wrong-agent path as exactly that, and otherwise just states the shape it expects.

Closes #3852

Test plan

• python -m pytest tests/unit/test_daemon_dev_anchor_spec.py -q passes
• python util/lint.py --all passes
• From a checkout, gaia daemon start-agent email --mode dev --dev-src-dir /tmp/not-a-checkout → message states the expected hub/agents/email/python shape and suggests checking for a typo, with no invented path
• --dev-src-dir <checkout>/hub/agents/chat/python → message says it's the chat agent's source directory and offers gaia daemon start-agent chat
• --dev-src-dir <checkout> (a real checkout root) → still names the exact <checkout>/hub/agents/email/python path to pass instead

🔍 Technical details

Root cause — resolve_caller_dev_src_dir in src/gaia/daemon/sidecars/spec.py built its remedy with agent_dev_src_dir(resolved, agent_id), an unconditional <input>/hub/agents/<id>/python join with no existence check, and hardcoded "not the checkout root" as the diagnosis for every non-matching shape.

Change — the message is now built by _dev_src_dir_shape_error(), which branches three ways:

1. _dev_src_dir_agent_id() (new) matches hub/agents/<any-id>/python with the agent slot wildcarded → report the wrong-agent error, naming the other agent and gaia daemon start-agent <other>; the sibling hub/agents/<requested>/python path is named only when is_dir().
2. The joined path exists → unchanged "you passed the checkout root" wording and the concrete corrected path (the genuine fix(daemon): --dev-src-dir rejects a repo root and never says what shape it wants #2742 case).
3. Otherwise → state the expected hub/agents/<id>/python shape and suggest checking for a typo. No fabricated path.

Verified — all four cases exercised against a temp tree; output for (a) checkout root, (b) unrelated dir, (c) another agent's source dir, (d) a directory that is not a checkout of this repo:

(a) --dev-src-dir must point at the hub/agents/email/python directory inside a checkout, not
    the checkout root. Got '/tmp/demo/gaia'; pass '/tmp/demo/gaia/hub/agents/email/python' instead.
(b) --dev-src-dir must be an absolute path ending in hub/agents/email/python — the agent's source
    directory inside a checkout. Got '/tmp/demo/some/unrelated/dir', which is neither that shape nor
    a checkout containing it. Check it for a typo, or pass the hub/agents/email/python directory of
    the checkout you want to run from.
(c) --dev-src-dir points at the 'chat' agent's source directory, but the agent requested is 'email'.
    Got '/tmp/demo/gaia/hub/agents/chat/python'; pass '/tmp/demo/gaia/hub/agents/email/python'
    instead, or start the other agent with `gaia daemon start-agent chat`.
(d) …same shape-only wording as (b).

Tests — tests/unit/test_daemon_dev_anchor_spec.py: the repo-root test now creates the real hub/agents/email/python so it keeps covering the genuine checkout-root case under the existence gate; ..._rejects_unrelated_shape gained positive remedy-text assertions plus a check that the fabricated joined path is absent; two new tests cover the other-agent case with and without an existing sibling.

python util/lint.py --all — black/isort/pylint/flake8/bandit pass. Full tests/unit/ run: 11928 passed; the 17 failures / 62 errors are pre-existing in this container (missing optional deps like fitz, and the uninstall-command suite's HOME assumptions) and reproduce identically on main with the change stashed.

[github-actions]

Verdict: Approve with suggestions

The fix is correct and well-scoped. _dev_src_dir_shape_error correctly branches across all three error cases — wrong-agent path, checkout root (when corrected path exists), and everything else — and the four new/updated tests exercise each branch, including the sibling-existence gate. No correctness, security, or architecture issues.

🟢 Nit — issue number in docstrings (one pattern, four files): Four docstrings reference #3852 inline (production code + three tests). Per the project style guide, issue numbers belong in PR descriptions and commit messages, not in docstrings — they rot as the code evolves.

🔍 Technical details

The four occurrences:

• spec.py — _dev_src_dir_shape_error docstring: "(issue #3852)"
• test_daemon_dev_anchor_spec.py — test_resolve_caller_dev_src_dir_rejects_unrelated_shape docstring: "issue #3852: …"
• test_daemon_dev_anchor_spec.py — test_resolve_caller_dev_src_dir_names_other_agent_source_dir docstring: "issue #3852: …"

The fourth test (_other_agent_names_existing_sibling) doesn't reference the issue — no change needed there.

Suggested rewrites:

• spec.py: drop the parenthetical; the prose before it already states the behaviour.
• Test docstrings: keep the behavioural description, drop the issue token (e.g. "a path that isn't a checkout root must not be 'corrected' into a path that doesn't exist — state the expected shape instead").

Everything else — the three-branch logic, the existence gate on sibling.is_dir(), the assertion that no fabricated path appears in the unrelated-shape message — looks right.

[itomek]

A bad --dev-src-dir now gets an error that points somewhere real. Before, any path that wasn't the expected shape got "pass '/hub/agents//python' instead" — a path blindly joined onto whatever was typed, so a typo became a longer typo and pointing at another agent's source tree suggested nesting it inside itself.

The corrected path is named only when it exists on disk; pointing at a different agent's dev-src dir is now reported as the wrong-agent error it is, with gaia daemon start-agent <that-agent> as the alternative. Four tests cover it, including the sibling-exists and sibling-missing branches.

Note on CI

This PR's checks had only ever run CodeQL — a branch pushed with GITHUB_TOKEN does not trigger the other workflows. Updated the branch from main to fire them; unit tests and lint pass on the current code. An earlier self-hosted Windows job failure was the runner losing contact with the server, not this change — it passed on rerun.