[Epic]: Harness backend and CLI live-review fixes (rewind, workspace, shutdown, step cap, CLI hints)

[dennisonbertram]

Work type

Epic

Problem and outcome

A live review on 2026-09-05 drove harnessd and harnesscli end to end (fake provider with scripted tool calls, plus real OpenRouter runs) through long multi-step scenarios: tool loops, multi-turn conversations, restart persistence, budget limits, cancel/steer, approvals, plan mode, sandbox escapes, 20-way concurrency, session rewind, and headless CLI blocking. The core loop, sandbox, approvals, plan mode, cancellation and concurrency are correct. Eight defects were reproduced:

1. Session rewind truncates the wrong messages (step unit mismatch) and the live daemon keeps serving the untruncated in-memory history.
2. Rewind's external-modification guard refuses any point older than the latest agent edit of the same file (false positive), forcing force, which also disables the real check.
3. harnesscli --workspace and the TUI workspace_path are silently dropped by the server; tools always run in the daemon's HARNESS_WORKSPACE.
4. harnessd SIGTERM drains HTTP for 10 s, never cancels in-flight runs, and orphans running tool children.
5. A headless CLI run blocked on AskUserQuestion tells the user to run harnesscli continue, which returns 409 run_not_completed.
6. After a daemon restart GET /v1/runs/{id} works but /events and /summary return 404.
7. harnessd silently caps every run at 8 steps and reports the run as failed; product direction is that the harness has no run cap by default.
8. cmd/acceptance-api-sse fails on macOS (symlinked temp dir vs canonical-path check) and the nightly test-regression job is red on the zero-coverage gate.

Outcome: every item above is fixed at its owning seam with a permanent regression test, the live scenario suite that found them passes, and operator docs describe the real defaults. Affected users: everyone using rewind, the CLI/TUI from a non-daemon directory, headless automation, and long-running agent tasks.

Non-goals

• No new API surface beyond honoring the already-sent workspace_path field.
• No redesign of rewind snapshots (crash-safety is [B1] Crash-safe rewind: journal originals before applying workspace restore #1349) or of shutdown store-ordering ([D1] Safe shutdown ordering: handler ctx cancellation → quiescence → Close #1356); this epic only adds run cancellation and child-process cleanup to shutdown.
• No change to permission semantics, plan-mode flow, or approval broker.
• Prompt-token cost of the 67-tool schema (~13k tokens per turn observed) is out of scope; track separately.
• Documentation audit results are tracked in a separate child once the audit lands.

Current architecture and evidence

Entry points: cmd/harnessd/main.go (lifecycle, shutdown at ~1184), cmd/harnessd/config_reload.go:46 (MaxSteps 0→8), internal/server/http_runs.go (handlePostRun decodes harness.RunRequest; /events and /summary call runner.Subscribe / runner.GetRunSummary only), internal/server/http_conversations.go (/messages reads runner.ConversationMessagesSnapshot; /rewind), internal/harness/conversation_store_sqlite.go (RestoreRewindPoint ~682-750, expected_hash update ~630-640), internal/harness/runner_step_engine.go:1352 (RewindPoint{Step: step} uses the run-local step), cmd/harnesscli/main.go (runCreateRequest.WorkspacePath, reportRunBlocked), cmd/harnesscli/tui/api.go:72 (workspace_path), internal/harness/types.go:444 (RunRequest, no workspace field).
Evidence: scenario scripts and outputs from the review session; key observations reproduced deterministically with HARNESS_PROVIDER=fake scripted tool calls.
Existing sources of truth: docs/runbooks/session-rewind.md, docs/runbooks/golden-path-deployment.md (claims max_steps default 30), docs/ux-paths.md (claims --workspace is forwarded).
Known related debt: #1303 (rewind: mirror resurrects messages), #559 (per-request workspace override proposal), #1356 (shutdown ordering), #823 (CLI exit codes), #796 (older coverage-gate red).

Cross-surface impact map

Config/env/defaults: max_steps daemon default 8 → 0 (unlimited); HARNESS_MAX_STEPS/config still honored; TUI config.go MaxSteps 8.
APIs/CLI/tools/wire formats: RunRequest.workspace_path becomes a real field (validated absolute existing dir); /events and /summary gain a durable fallback; CLI blocked message changes; no other shape changes.
Persistence/schema/migrations: none; rewind truncation predicate and expected_hash maintenance change semantics only.
Concurrency/lifecycle/recovery: shutdown cancels active runs with a bounded wait and kills tool process groups; rewind invalidates the in-memory conversation mirror.
Security/auth/privacy/permissions: workspace_path must be validated like extra_dirs (absolute, exists); sandbox confinement then keys off the per-run root.
TUI/web/macOS/other clients: TUI already sends workspace_path; TUI rewind result display (#1303) unaffected.
Provider/model/tool catalog: none.
Deployment/observability/operations: shutdown logs cancelled-run count; runbooks updated.
Compatibility/versioning: existing rewind points keep working; a run that previously died at step 8 now continues.
Tests/evals/fixtures: one regression test per child; scripts/test-regression.sh green; fake-provider live scenarios re-run.
Documentation/training: golden-path, session-rewind, harnesscli runbooks, ux-paths.

Shippable child issues

• bug(rewind): message truncation uses run-local step against the conversation-wide index and the live history mirror is never invalidated #1370 — rewind truncation keyed on a conversation-wide boundary and live mirror invalidated; test: multi-run rewind keeps pre-point messages before and after restart
• bug(rewind): external-modification guard refuses points older than the latest agent edit (stale expected_hash) #1371 — rewind guard accepts older points after agent-only edits, still refuses external edits; test: older point restorable without force
• bug(server): workspace_path sent by harnesscli --workspace and the TUI is silently ignored; tools run in the daemon workspace #1372 — workspace_path honored via the per-run tool registry and validated like extra_dirs; test: CLI from another cwd writes there, sandbox confined to it
• bug(harnessd): SIGTERM never cancels in-flight runs and orphans tool child processes #1373 — SIGTERM cancels in-flight runs and kills tool children; depends on nothing, coordinate with [D1] Safe shutdown ordering: handler ctx cancellation → quiescence → Close #1356; test: no orphan after shutdown
• bug(harnesscli): blocked-run hint suggests 'continue', which returns 409 for a run waiting on user input #1374 — CLI blocked-run hint names a working command and harnesscli input submits answers; test: printed command resumes the run
• bug(server): /v1/runs/{id}/events and /summary return 404 for persisted runs after daemon restart #1375 — /events and /summary fall back to the durable store; test: 200 after restart
• bug(harnessd): implicit max_steps=8 default fails runs after eight tool calls; harness must have no default run cap #1376 — no implicit max_steps default in daemon or TUI; docs say 0 = unlimited; test: 9-step run completes
• test: acceptance-api-sse fails on macOS (symlinked temp dir) and nightly test-regression is red on the zero-coverage gate #1377 — macOS acceptance-api-sse test canonicalizes its temp dir; nightly zero-coverage gate green
• docs: runbooks, README, and design catalogs contradict the code (MCP runbook, resume story, bind default, event catalog, dead links) #1379 — runbooks, README, CLAUDE.md, design catalogs corrected (MCP runbook, resume story, bind default, event catalog regenerated, dead links); merges after bug(server): workspace_path sent by harnesscli --workspace and the TUI is silently ignored; tools run in the daemon workspace #1372, bug(harnesscli): blocked-run hint suggests 'continue', which returns 409 for a run waiting on user input #1374, bug(harnessd): implicit max_steps=8 default fails runs after eight tool calls; harness must have no default run cap #1376
• docs(website): reference pages omit routes, fields, events, tools, providers and env vars; resume and bind-default claims wrong #1380 — website reference pages regenerated from code (routes, run fields, events, tools, providers, env vars) plus the service.go addr help string; merges after bug(server): workspace_path sent by harnesscli --workspace and the TUI is silently ignored; tools run in the daemon workspace #1372, bug(harnesscli): blocked-run hint suggests 'continue', which returns 409 for a run waiting on user input #1374, bug(harnessd): implicit max_steps=8 default fails runs after eight tool calls; harness must have no default run cap #1376
• docs: missing and stale folder indexes, dead absolute links, and historical notes mixed with operator docs #1381 — folder indexes, dead absolute links, archive-candidate list for owner decision

Dependency graph

Independent, can proceed in parallel: C1 rewind truncation, C2 rewind guard, C3 workspace_path, C4 shutdown, C5 CLI hint, C6 events/summary fallback, C7 step cap, C8 macOS test + coverage gate.
Convergence: C1 and C2 both touch conversation_store_sqlite.go (different functions; rebase second on first). C3 and C4 both touch runner lifecycle (different functions). Docs child depends on C3 and C7 landing so docs describe the final behavior.

Integration contracts

• RunRequest remains backward compatible; new field optional.
• Rewind: after POST /rewind to point P, GET /messages and the next run's context contain exactly the messages recorded before P's tool call; file restore unchanged.
• Shutdown: no run remains running in the store after exit; no child process of a tool survives daemon exit.
• Step cap: max_steps 0 means unlimited everywhere (daemon, TUI, docs); explicit caps keep current semantics.
• Every child adds a test in the package that owns the seam; live proof via the fake-provider scenario for that behavior.

Rollout sequence

All children are independent behavioral fixes with no migrations; merge in any order, rebuild with scripts/install.sh, restart the daemon. Backout is a revert of the individual PR. Final integration proof: re-run the review's live scenario suite against a rebuilt daemon.

Risks and observability

• Removing the step cap → runaway runs; mitigation: max_cost_usd and explicit max_steps remain; signal: run duration/step count in summary.
• workspace_path widens filesystem reach → validated like extra_dirs, confined by the sandbox; signal: workspace.provisioned event carries the path.
• Shutdown cancellation could drop an in-flight turn → bounded wait before cancel; signal: shutdown log line with counts; [D1] Safe shutdown ordering: handler ctx cancellation → quiescence → Close #1356 covers store ordering.
• Rewind changes → regression tests over multi-run conversations; signal: messages_truncated matches expected counts.

Definition of done

• All child contracts satisfied with regression tests that were red first
• Live fake-provider scenario suite green against a rebuilt daemon (rewind, workspace, shutdown, CLI blocked, restart, no cap)
• scripts/test-regression.sh green including the coverage gate — pending next nightly on CI; locally only internal/acceptance/ptyrunner fails (environment-specific, passes on CI)
• Runbooks and README state the real defaults and flags
• Engineering log updated

Epic acknowledgement

• I will not close this epic directly from an implementation PR; every code slice will close its own contract-complete child issue.

[dennisonbertram]

Documentation audit (2026-09-05, read-only, subagent) — evidence for the docs children

go-code documentation staleness audit (2026-09-05, read-only)

Source of truth: working tree at a0d15211. Every finding was verified with rg/test -e against the code; file:line citations are to the current tree. No repo files were modified.

Summary

Metric	Count
Operator-facing files reviewed line-by-line	101 (README, AGENTS, CLAUDE; 26 docs/runbooks; 13 docs/design; 4 docs/context; 3 docs/operations; docs/INDEX + 9 folder INDEX files; 50 website/docs pages)
Historical directories sampled for dead references only	docs/investigations (193), docs/testing (22), docs/implementation (40), docs/plans (385), docs/logs (5), docs/research (25)
Files with at least one verified issue	52
High-severity findings (would send an operator to a failing command/API call)	14
Medium (wrong default/description)	34
Low (dead link, omission, stale path)	~45

Verdict. The docs are not uniformly "wildly" out of date. The website (website/docs, 18.5k lines) and most runbooks are accurate on routes, tool names, env vars, and defaults; the forks verified several hundred individual claims that matched code. The rot is concentrated in six recurring themes, and most of the high-severity items are the same two defects repeated across files:

1. The resume story is wrong everywhere it appears. README, exit-codes.md, harnesscli.md, http-api-guide.md, and the CLI's own stderr hint (cmd/harnesscli/main.go:247) tell operators to harnesscli continue <id> a blocked or cancelled run. continue requires status == completed (internal/harness/runner.go:2217) and returns 409 run_not_completed (internal/server/http_runs.go:817). The working API for a waiting_for_user run is POST /v1/runs/{id}/input (http_runs.go:355); a cancelled run cannot be continued at all. This is a code bug as much as a docs bug.
2. --workspace is documented as effective but is dropped. cmd/harnesscli/main.go:91,208 sends workspace_path; RunRequest (internal/harness/types.go) has no such field. distribution.md:242 makes it an acceptance-checklist step that cannot pass. Only website/docs/cli/harnesscli.md:105 gets this right.
3. HARNESS_ADDR default changed to 127.0.0.1:8080 (issue [Bug]: harnessd listens on all interfaces unauthenticated, and /mcp bypasses auth entirely #1328, internal/config/config.go:254) and was not propagated. Seven files still say :8080; tool-usability-testing.md:47 even shows a wildcard bind that bind_guard.go:29-43 now refuses.
4. docs/runbooks/mcp.md describes an MCP HTTP server that is not mounted. /mcp is served by internal/harnessmcp (25 tools, POST-only); the doc's "10 tools incl. subscribe_run", GET /mcp SSE, and 400-on-name-collision sections describe internal/mcpserver, which harnessd only uses for --mcp stdio.
5. Catalog pages were not regenerated. docs/design/event-catalog.md lists 23 of 81 events and says only two events are terminal (IsTerminalEvent includes run.cancelled, events.go:478); website/docs/reference/events-catalog.md misses 12; tools-catalog.md misses 7 tools; provider lists miss 5 providers.
6. Dead links and abandoned indexes. README and docs/runbooks/INDEX.md link three runbooks that do not exist; docs/testing/INDEX.md lists 1 of 22 files; docs/investigations and docs/implementation have no index despite AGENTS.md:56 requiring one.

Five worst offenders

1. docs/runbooks/mcp.md — 3 high (unmounted server, wrong tool list, SSE that 405s) + wrong tool-name format at line 67 ({server}__{tool} vs code mcp_{server}_{tool}, deferred/mcp.go:109).
2. website/docs/reference/exit-codes.md — 2 high (both resume paths wrong) + stale tool name and line refs.
3. docs/design/event-catalog.md — 1 high (terminal-event rule omits run.cancelled; a client following it hangs on cancelled runs), 57 events undocumented, wrong ask_user_question payload name.
4. docs/runbooks/subagent-debugging.md — 1 high (tells you to grep run.completed for max_steps_reached; it is emitted on run.failed, runner.go:4655-4671) + 3 medium.
5. docs/runbooks/golden-path-deployment.md — wrong bind default, non-existent profiles_dir config key, non-existent tools.allow config.toml key, and the max_steps=30 claim that is actually the full profile's value (daemon default is 8, cmd/harnessd/config_reload.go:44-47).

Findings by file

Severity: high = misleads an operator into a failing command/API call; medium = wrong default or description; low = cosmetic, omission, dead link.

README.md

doc:line	stale claim	code says	sev
README.md:52	go-code continue <run-id> "..." as the general way to continue a run	continue POSTs /v1/runs/{id}/continue (cmd/harnesscli/runctl.go:337+), which requires the run to be completed (runner.go:2217; 409 at http_runs.go:817). Blocked (waiting_for_user) runs need POST /v1/runs/{id}/input (http_runs.go:355); main.go:247 prints the wrong hint	high
README.md:166	"Run requests support ... workspace, sandbox, approval ... fields"	RunRequest has workspace_type/extra_dirs/permissions, no workspace/sandbox/approval; the CLI's --workspace is sent as workspace_path and ignored (main.go:91,208)	medium
README.md:189	docs/runbooks/tui-visual-testing.md	file does not exist	low
README.md:190	docs/runbooks/symphony-issue-authoring.md	file does not exist	low

Verified OK: Homebrew Formula/, scripts/install.sh --add-to-path, all go-code subcommands (scripts/go-code.sh:9-20, cmd/harnesscli/auth.go:190-230), harnesscli service * (service.go:101-109), provider key env vars (catalog/providers/*.json api_key_env), kimi-code login → harnesscli auth kimi ... (auth.go:157-165), all 13 listed routes, repo map dirs, distribution anchor (distribution.md:50), module go-agent-harness (go.mod:1).

AGENTS.md

No stale references. All 24 doc paths and scripts/init.sh, bootstrap-worktree.sh, verify-and-merge.sh exist; .codex-worktrees/ matches init.sh:6. Low: line 9 points at docs/plans/active-plan.md, which stacks several "Current status" paragraphs (latest #1285, last commit 2026-08-11) so the actual current state is ambiguous.

CLAUDE.md

doc:line	stale claim	code says	sev
CLAUDE.md:78	"15 POC tests in http_script_workflows_test.go and *_advanced_test.go"	14 + 6 = 20 func Test	low

Everything else verified (rewind routes/force, /rewind ... confirm at tui/model.go:2391, single catalog builder tools_default.go:251 + registry.go:278, /v1/hooks http_hooks.go:16, hooks trust|revoke|list hooks.go:22-26, plugins.md "Config-driven hooks" at :365, /dashboard/ctrl+d keys.go:104, .harness/plan.md plan_mode.go:243, tokencache/SetTokenSource/models_from (catalog/models.json:554)/X-Kimi-Client-* (kimi.go:115), TestRunSmoke, run-bench-smoke.sh fake provider, harness-acp, 22 tests in comprehensive_test.go, /keys i → /v1/providers/{name}/import-subscription (tui/api.go:989, http_catalog.go:160), harnessd flags --profile/--mcp/--mcp-workspace (main.go:257-265)).

docs/runbooks (26 files; 13 with issues)

mcp.md

doc:line	stale claim	code says	sev
mcp.md:86-88	"internal/mcpserver provides an HTTP MCP server handler for POST /mcp and GET /mcp (SSE) ... mounted by harnessd"	/mcp is harnessmcp.NewHTTPHandler (cmd/harnessd/runtime_container.go:348-352); mcpserver.NewServer has no external callers; harnessd uses only mcpserver.NewStdioServer for --mcp (runtime_container.go:74)	high
mcp.md:95-108	"Tools exposed (10 total)" incl. subscribe_run	/mcp serves the 25 harnessmcp tools (internal/harnessmcp/tools.go); subscribe_run exists only in unmounted internal/mcpserver/mcpserver.go:434	high
mcp.md:188-201	"SSE streaming (GET /mcp) ... work out of the box"	harnessmcp/httptransport.go:29-31 returns 405 for anything but POST	high
mcp.md:61	per-run server name collision → "rejected with 400"	Collision detected inside the already-running run (runner.go:1996-2004 → scoped_mcp.go:286-289); POST /v1/runs has already returned 202	medium
mcp.md:67	tool name is {server}__{tool} (double underscore)	deferred/mcp.go:109: "mcp_" + server + "_" + name	medium
mcp.md:212	internal/mcpserver/ = "MCP HTTP server (broker, poller, SSE, 10 tools)"	only live use is stdio for harnessd --mcp; contradicts the doc's own :178-179	medium
mcp.md:69	internal/harness/tools/mcp.go and MCPRegistry	file does not exist; MCPRegistry is at tools/types.go:208	low

subagent-debugging.md

doc:line	stale claim	code says	sev
:233-242	max_steps exceeded → run.completed with "reason": "max_steps_reached", ChildResult.status "partial"	Emitted as run.failed + RunStatusFailed (runner.go:4655-4671); grepping run.completed finds nothing	high
:130	"partial" = child hit max_steps	same; max_steps yields run.failed	medium
:89	agent called ask_user_question	tool is AskUserQuestion (tools/ask_user_question.go:12)	medium
:24-40	subagent JSON example	omits branch_name, base_ref, total_tokens, cost_usd (internal/subagents/manager.go:80-85)	low

golden-path-deployment.md

doc:line	stale claim	code says	sev
:48, :70	server listens on :8080 by default	127.0.0.1:8080 (config.go:254); non-loopback bind without auth refused (bind_guard.go:30-42)	medium
:247-249	profile mutations "require profiles_dir config"	no profiles_dir TOML key exists; dir comes from HARNESS_PROFILES_DIR/~/.harness/profiles (cmd/harnessd/main.go:323,445)	medium
:262	set tools.allow in project config.toml	workspace config has no tools key (workspace_config.go:18-37); [tools] allow is a profile TOML key	medium
:59	max_steps default 30	30 comes from --profile full (full.toml, applied at main.go:1416); daemon default is 8 (config_reload.go:44-47) — doc does not say so	low

distribution.md
| :242 | checklist: server "receives that project as workspace_path" | RunRequest has no workspace_path; step cannot pass | high |
| :75 | --addr falls back to :8080 | 127.0.0.1:8080 (service.go:392-397, config.go:254); flag help at service.go:410 also stale | low |

observational-memory.md
| :114 | "Postgres adapter ... planned but not enabled in v1" | internal/observationalmemory/store_postgres.go:13 exists; wired at cmd/harnessd/main.go:1573-1574; the same doc's :10 documents HARNESS_MEMORY_DB_DRIVER=postgres | medium |
| :19 | HARNESS_MEMORY_LLM_MODEL default gpt-5-nano | default only in openai mode (main.go:527-529) | low |

profile-authoring.md
| :320-322 | "there is no false override — unset fields inherit" | explicit false is tracked (internal/profiles/profile.go:93-95); contradicts the doc's own :60-62 | medium |
| :26-27 | "four top-level sections" | schema also has extends (profile.go:23) and [runner].max_turns (profile.go:72) | low |

profile-operations.md
| :76-82 | layering: env → project → user → --profile → defaults | cascade is defaults < user < project < profile < env (internal/config/config.go:3-8, Load) | medium |

remote-cronsd.md
| :136-140 | "Execution.RunID ... intentionally empty here" (deferred to #1004) | populated: internal/cron/types.go:124, scheduler.go:741; doc's own :80 says so | medium |

terminal-bench-periodic-suite.md
| :13-17 | "Included Tasks" = 3 | 21 task dirs; script runs whole dir (run-terminal-bench.sh:6) | medium |
| :28 | HARNESS_BENCH_MODEL default gpt-5-nano | gpt-5-mini; TERMINAL_BENCH_MODEL overrides, undocumented (run-terminal-bench.sh:11) | medium |
| :29 | HARNESS_BENCH_MAX_STEPS default 12 | 100 (benchmarks/terminal_bench/agent.py:33) | medium |
| :25-31 | overrides list | omits TERMINAL_BENCH_*, HARNESS_BENCH_TARGET_ARCH, BENCH_MIN_ACCURACY, --skip-build/--preflight-only/--build-base-only | low |
| :50 | uploads .tmp/terminal-bench/ | uploads latest + latest/report.md (.github/workflows/terminal-bench-periodic.yml:75,84) | low |

tool-usability-testing.md
| :47 | HARNESS_ADDR=:9090 ./harnessd & | wildcard bind refused without API-key store or HARNESS_AUTH_DISABLED=true (bind_guard.go:29-43) | medium |
| :182,201,244,269 | source internal/harness/tools/cron.go | file is internal/harness/tools/deferred/cron.go | low |
| :317 | suggested git_commit tool | no such tool in catalog | low |

harnesscli-live-testing.md
| :17-31 | "CLI currently accepts" list | omits -workspace, -plan-mode, -resume (main.go:143-200) | low |
| :90 | run API in internal/server/http.go | http_runs.go:98-99 | low |

benchmark-smoke.md — :218 "7 custom Go coding tasks" vs 21 dirs (low).

INDEX.md
| :15, :16, :27 | symphony.md, symphony-issue-authoring.md, tui-visual-testing.md | none exist | low |
| whole | — | golden-path-deployment.md, tool-usability-testing.md not listed | low |

Clean (verified, no findings): acceptance-inventory, acp, codex-subscription-auth, deployment, documentation-maintenance, issue-driven-development, issue-triage, native-gui-acceptance, ownership-copy-semantics, provider-model-impact-mapping, session-rewind, testing, worktree-flow.

docs/design, docs/context, docs/operations (22 files; 7 with issues)

event-catalog.md
| :7 | "Only two events signal stream termination" | IsTerminalEvent also returns true for run.cancelled (events.go:477-479) | high |
| :3 | "All events emitted by the harness runner" | 23 documented vs 81 in AllEventTypes() (events.go:392); missing run.cancelled, run.queued, run.cost_limit_reached, run.step.*, tool.approval_*, plan.approval_*, tool.call.blocked, tool.output.delta, assistant.thinking.delta, auto_compact.*, callback.*, context.window.*, steering.received, todos.updated, spawn_agent.*, workspace.*, tool_hook.*, provider.resolved (57) | medium |
| :12 | "Run Lifecycle (5 events)" | 9 run.* events | medium |
| :18, :48 | run.waiting_for_user payload "tool": "ask_user_question" | AskUserQuestionToolName = "AskUserQuestion" (tools/ask_user_question.go:12; set at runner_step_engine.go:1173,1189) | medium |

system-prompt-architecture.md :74 "prompt_extensions.skills[] (reserved, ignored)" — skills are resolved and injected (internal/systemprompt/engine.go:46-60; prompt.resolved emits applied_skills, runner.go:1917) — medium.

tool-roadmap.md :36 "add tools in internal/harness/tools/ (core)" — core tools live in tools/core/ — low.

observational-memory-architecture.md :37 path internal/harness/tools/observational_memory.go — actual tools/core/observational_memory.go — low. :95 "Remote coordinator transport is not implemented yet" — accurate.

native-macos-app.md :29, :66 scripts/live-harnessd.sh — only macapp/scripts/live-harnessd.sh exists — low. :153 Runner.resolveProvider at runner.go:2099 — now runner.go:3152 — low.

plugins.md :163, :210 plugins/tool-logger/ example + import — directory does not exist (only plugins/conclusion-watcher/); fine as tutorial if labelled — low. All harnesscli plugin/hooks subcommands, /v1/hooks, hook schema, config keys verified correct.

docs/INDEX.md :1-13 — omits implementation/, investigations/ (193 files), process/, ux-paths/ — low.

Clean: installable-plugin-bundles, go-relay-architecture, codex-inspired-design-plan (correctly flags GET /v1/plugins as missing), codex-app-reference (third-party notes), design-notes, ux-requirements, docs/context/, docs/operations/.

website/docs (50 files; 19 with issues; 0 dead links)

reference/exit-codes.md
| :29 | exit 6 run.cancelled "resumable via harnesscli continue" | continue requires completed (runner.go:2217); 409 run_not_completed (http_runs.go:817) | high |
| :77 | blocked run: "resume with harnesscli continue" | run is waiting_for_user; needs POST /v1/runs/{id}/input (http_runs.go:854-883); CLI hint at main.go:247 also wrong | high |
| :58 | invoked ask_user_question | AskUserQuestion | low |
| :146 | RunStatusWaitingForUser at types.go:337-338 | now types.go:401-402 | low |

cli/harnesscli.md :55 exit 6 "resumable via harnesscli continue" — same 409 — high. :60-78 omits -plan-mode, -resume — low. No sections for steer, viz, acp, plugin, mcp, hooks, service, auth kimi|codex — low. (:105 correctly states -workspace is dropped by the server.)

reference/cli-flags.md
| :80 | -workspace "Workspace directory for this run" | sent as workspace_path, not in RunRequest, ignored | high |
| :39 | HARNESS_ADDR default :8080 | 127.0.0.1:8080 | medium |
| :31 | harnessd flags at main.go:170-178 | main.go:257-265 | low |
| :64-90, :204-222, :228-243, :304-310 | omits -plan-mode/-resume; auth kimi|codex; go-code --resume; six CRONSD_* vars | see main.go:155,157, auth.go:136-180, go-code.sh:10, cmd/cronsd/main.go | low |

server/http-api-guide.md :371-380 POST /v1/runs/{id}/continue with no precondition — must be completed else 409 — medium. :437 ask_user_question — AskUserQuestion — low.

reference/http-routes.md :9, :430 :8080 — medium. :285-330 RunRequest schema omits attachments, plan_mode, plan_file, extra_dirs, denied_tools, fork_depth, rules — low. Registered routes absent from the inventory: /v1/tools, /v1/hooks, /v1/config/reload, /v1/model-settings*, /v1/tasks, /v1/jobs/{id}/kill|output, /v1/callbacks/, /v1/cron/runs, /v1/cron/jobs/{id}/executions, /v1/conversations/{id}/events|rewind-points|rewind|undo, /v1/runs/{id}/replay, /v1/providers/{name}/import-subscription, /v1/relay/* (6), /viz — low.

reference/environment-variables.md :28 HARNESS_ADDR ":8080" — medium. Omits HARNESS_RETRY_MAX_ATTEMPTS, HARNESS_RETRY_MAX_TOTAL_SEC (internal/provider/retry.go:41-46), HARNESS_LISTEN_FD, HARNESS_EXIT_WITH_PARENT — low.

reference/tools-catalog.md — missing list_models, deploy, goals, cron_update, cron_history, message_subagent, notify_parent (all Name: in tools/deferred/) — medium.

reference/events-catalog.md — missing callback.dispatching|failed|retry_wait|started, conversation.continued, plan.approval_required|granted|denied, profile.efficiency_suggestion, steering.received, todos.updated, usage.delta — medium.

reference/providers-and-models-reference.md — provider table omits cerebras, codex-subscription, kimi-subscription, lmstudio, ollama (catalog/models.json) — medium. :287-289 OpenRouter as the only live discovery — OpenAI/Anthropic also have 5-min TTL discovery (provider/openai/discovery.go:24, anthropic/discovery.go:24) — medium.

reference/troubleshooting.md :202 internal/harness/tools/mcp.go — actual tools/deferred/mcp.go:109 — low.

server/harnessd.md :266 :8080 — medium; :39 sample log — low.
server/script-workflows-api.md :312 GET/POST /v1/script-workflow-runs/{id} — no POST on bare id (http_script_workflows.go:194-223) — low.
server/expose-as-mcp-server.md :36 version = "1.0" — "0.1.0" (mcpserver/options.go:15) — low; :152 limit query param — ignored (http_runs.go:174-184) — low.
cli/go-code-wrapper.md — omits go-code --resume — low.

concepts/configuration.md :44, :165, :322 addr = ":8080" / "bare port" — 127.0.0.1:8080 (#1328) — medium.
tutorials/claude-desktop-mcp.md :11, :169 "five tools" — harness-mcp registers 25 (internal/harnessmcp/tools.go:33-332) — medium. :180-181 "cost_usd always empty" — fixed in #1314 (harness_client.go:232-251); messages still empty — medium.
integrations/mcp-consume.md :201 list_mcp_resources "not yet implemented in clientManagerRegistry" — implemented (cmd/harnessd/mcp_setup.go:68-90, internal/mcp/mcp.go:231); only per-run servers return empty (scoped_mcp.go:161-163) — medium.
getting-started/what-is-go-code.md :33 and concepts/providers-and-models.md :267 "10 providers" — 15 in catalog/models.json — low.
concepts/runs-and-conversations.md :52 never names POST /v1/runs/{id}/input as the resume route; only /continue documented — low.

Clean: glossary, authentication, tui, and the other 28 concept/tutorial/integration/workflow/operations pages (all routes, methods, events, tools, env vars, and stated defaults verified).

Sampled historical directories

doc:line	stale claim	code says	sev
docs/investigations/codex-subagent-issue-361-smoke-…md:6-14, issue-361-subagent-…md:8-25, codex-subagent-issue-361-profile-…md:8-11	absolute links to /Users/dennisonbertram/Develop/go-agent-harness/...	machine-specific; targets issue-361-grooming.md, issue-362-grooming.md, plans/issue-362-plan.md do not exist anywhere	low
docs/logs/engineering-log.md:3594-3597	links into /Users/dennisonbertram/.codex/worktrees/a321/...	dead absolute worktree paths	low
docs/plans/INDEX.md	links .context/harness-reliability/tracker.md	does not exist	low
docs/testing/INDEX.md, docs/research/INDEX.md, docs/plans/INDEX.md	—	21/22, 19/25, 50/385 files unlisted	low
docs/investigations, docs/implementation	AGENTS.md:56 "maintain folder indexes"	no INDEX.md in either (193 / 40 files)	low
docs/context/known-issues.md	"Known Issues"	single entry, marked Resolved 2026-06-26; carries no current issues	low

40 of 193 investigation files still reference the pre-rename go-agent-harness path; docs/testing holds 22 dated smoke transcripts from March 2026.

Entirely obsolete: candidates for deletion or archiving

• docs/runbooks/mcp.md lines 86-108, 188-201, 212 (the internal/mcpserver HTTP/SSE sections) — describe code that is never mounted. Rest of the file is current.
• docs/design/design-notes.md — 14-line empty template, untouched since 2026-03-04.
• docs/design/ux-requirements.md — only bootstrap requirement UX-000 (folder layout).
• docs/context/command-intent.md — session-scoped note for a one-off Hermes issue-filing task.
• docs/context/known-issues.md — one resolved historical entry.
• docs/design/codex-app-reference.md — notes on a third-party app build from 2026-07-27; keep only if macapp work still cites it.
• docs/operations/nightly-tasks.md, agent-completion-template.md — last touched 2026-03-04/06, predate the issue-form process in AGENTS.md/CLAUDE.md.
• docs/investigations/ (193 files, 2026-03-08 → 04-29), docs/testing/ (22 dated transcripts), docs/implementation/ (40 per-issue notes), and the ~300 per-issue docs/plans/*-plan.md / *-impact-map.md — historical records with no index; archive under a dated subtree rather than leaving them beside operator docs.
• docs/runbooks/tool-usability-testing.md Parts 2-3 — March 2026 cron_create iteration log with stale source paths; belongs with the docs/testing/usability-* logs.

Implemented but undocumented

Routes (registered, mentioned nowhere in README/docs/website): /v1/relay/placements, /v1/relay/contracts, /v1/relay/policy/check, /v1/relay/policy/filter, /v1/relay/operator/workers, /v1/relay/capabilities/{worker} (internal/server/http.go:408-413). Thinly documented (one page each, not in the route reference): /v1/model-settings, /v1/model-settings/providers[/...] (http_model_settings.go:62-66), /v1/callbacks/{id} (http.go:352), /viz (http.go:431-434). Also missing from the route reference page: /v1/tools, /v1/hooks, /v1/config/reload, /v1/tasks, /v1/jobs/{id}/kill|output, /v1/cron/runs, /v1/cron/jobs/{id}/executions, /v1/conversations/{id}/events|rewind-points|rewind|undo, /v1/runs/{id}/replay, /v1/providers/{name}/import-subscription (each is documented in at least one runbook/CLAUDE.md, just not the reference).

CLI subcommands: harnesscli acp (cmd/harnesscli/acp.go:25; docs only describe the separate harness-acp binary), harnesscli viz (one mention). harnesscli.md has no sections for steer, plugin, mcp login|logout|status, hooks, service, auth kimi|codex. Flags -plan-mode, -resume missing from every flag table; go-code --resume <id> (scripts/go-code.sh:10) missing from wrapper docs. Binary cmd/acceptance-api-sse is mentioned nowhere.

Env vars read by harnessd with no doc mention: HARNESS_EXIT_WITH_PARENT, HARNESS_MODEL_STORE_PATH, HARNESS_PROVIDER_CATALOG_DIR, HARNESS_RETRY_MAX_ATTEMPTS, HARNESS_RETRY_MAX_TOTAL_SEC, HARNESS_COLOR_PROFILE, HARNESS_ENABLE_CALLBACKS (cmd/harnessd/main.go:551, default true), HARNESS_LISTEN_FD; TERMINAL_BENCH_MODEL and six CRONSD_* vars.

Tools with no doc mention: compact_summary (core), deploy, message_subagent, notify_parent (deferred); list_models, goals, cron_update, cron_history missing from the website tools catalog.

Events missing from both catalogs: callback.* (4), conversation.continued, plan.approval_* (3), profile.efficiency_suggestion, steering.received, todos.updated, usage.delta; design catalog additionally misses 45 more (see event-catalog.md finding).

Config keys with no doc mention: none found beyond profiles_dir/tools.allow being documented but not existing (golden-path-deployment.md).

Code defects surfaced by the audit (not docs)

1. cmd/harnesscli/main.go:91,208 sends workspace_path, which the server never reads — --workspace is a no-op.
2. cmd/harnesscli/main.go:247 and exitcodes.go:23 tell blocked/cancelled runs to use harnesscli continue, which 409s for both; there is no CLI command that posts to /v1/runs/{id}/input.
3. cmd/harnesscli/service.go:410 flag help says the default addr is :8080; config default is 127.0.0.1:8080.