Correct the Repo Tools manifest-failure and scope claims

[selfcontained]

Nightly docs audit — deep-dive on the docs-pane Repo Tools section (next_focus from the previous run), plus its agent-facing restatement in plugins/dispatch/skills/repo-tools/SKILL.md.

The diff since the last audited SHA (60fdf6d1) was #983 (the previous run's own docs PR), #984 (mermaid split), #985 (type import) and #987 (palette tests) — nothing docs-relevant, so no pivot away from next_focus.

Verified clean

Checked as sets in both directions, no changes needed:

• The built-in tools list vs AGENT_TOOLS (63 entries) — exact match in both directions, with the only extras being the four job_* and two dispatch_review_submit/add_feedback entries the intro explicitly labels as job/reviewer-only.
• toolsRoot = worktreeRoot ?? repoRoot, matching "the worktree root for worktree agents, otherwise the repo root".
• No timeout on repo tool commands (runCommand only arms one when timeoutMs is passed) vs the 15s hard timeout on lifecycle hooks.
• Param → flag rules: string appends --flag value when non-empty, boolean appends --flag only on true, omitted/null/false/"" append nothing; name/type/flag required, description not.
• Manifest re-read per MCP request (stateless transport); the mtime cache covers hooks only.
• DISPATCH_AGENT_ID in the env for both tools and hooks; the stop hook firing from both stopAgent and executeArchive; failures logged and never blocking.
• Brain tools available to agents and jobs but not persona reviewers.

Fixed

Malformed manifest blast radius. Both docs-pane and SKILL.md said a typo makes "every repo_ tool disappear". parseRepoTool throws inside rawTools.map, so loadRepoTools rejects (verified with a two-entry manifest where only the second is bad — the good one is lost too). That rejection propagates through createDispatchMcpServer → handleMcpRequest with no catch, and the route has already called reply.hijack(). The real symptom is the whole MCP server failing for that session, built-ins included — which is also the difference between "why did my repo tools vanish" and "why is Dispatch's MCP server down".

Scope typos silently un-restrict. parseRepoToolScope drops unrecognized entries and returns undefined when nothing survives, which the filter reads as "no scope" — so a misspelled scope re-exposes a job-only tool to every agent. Documented on both surfaces.

SKILL.md advertised a dead scope. The field table listed reviewer as a usable value. routes/mcp.ts only ever sets toolScope to "job" or "agent" (persona reviewers get "agent"), so a tool scoped to reviewer alone is exposed to no one. The table now lists agent/job, with a note for manifests that still carry the old value.

docs/03-api-spec.md. Said only agent-scoped MCP loads repo tools, "in the agent's working directory". The job-scoped route loads them too (that's what the scope array selects between), and both resolve the checkout root from agent.cwd rather than using it directly.

Deferred

• No new ambient tip: .dispatch/tools.json already has one (repo-tools, since 0.11.12) pointing at this section, and a second tip for the stop hook on the same config file didn't clear the bar.
• Next run: docs-pane Worktrees section against apps/server/src/shared/git/ + archive.ts, including the backlog item about git branch -D destroying unpushed commits on archive.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KzXr7HNouFonD29oEpgwPr