No symptom-indexed troubleshooting entry point: a failed warded run's rescue info exists but is scattered across four subsystem docs

coilyco-ops commented

2026-07-01 21:57:54 +00:00

Member

Why

Persona: vibe-coder (arrived from a social post, delegates everything, never files feedback — just leaves); angle failure-paths. Day-2 scenario: warded #98 visibly did nothing (in reality: seeded credential expired, or the issue drew a NO-GO, or the container was reaped). Where do the docs send them?

README: no troubleshooting or "when it breaks" section at all.
ward doctor (found via FEATURES.md): docs/doctor.md scopes it to the allowlist + security: host probes — it says nothing about the agent subsystem, which is where this persona lives. (That gap is exactly ward#195; +1'd there.)
The rescue information does exist, but only inside per-subsystem docs a newcomer has no reason to open: the auth smoke test + "re-run 'claude' on the host to refresh" lives mid-way through agent-credentials.md; "your run's console/transcript/outcome landed in ~/.ward/agent-logs/<container>/" lives in agent-observability.md; NO-GO-posts-a-comment lives in agent-preflight.md; clean-tree refusals live in exec-verb.md.

There is no symptom-indexed entry point. A persona that will not read past the first screen — or an agent trying to self-rescue a failed run — has to already know which of 60+ docs holds their failure class. The vibe-coder closes the tab here, silently.

Deliverable

One docs/troubleshooting.md (or a README section) indexed by symptom, not by subsystem: "run launched then nothing happened" → auth smoke test + agent-logs path; "run never launched" → preflight NO-GO comment on the issue; "ward exec refused" → clean-tree gate + --audit-override-dirty; "container idles forever" → smoke-test skip + reaper. Each row: symptom → where to look → the fix. Link it from README. (A ward agent doctor verb is the deeper fix — that is ward#195's scope, linked, not duplicated here.)

Done condition

From the README alone, a user whose warded run failed can reach the correct diagnostic surface (agent-logs dir, issue comment, or host auth refresh) in ≤2 clicks without knowing which subsystem failed.

Severity: major-friction · persona: vibe-coder · angle: failure-paths
Filed by Claude Code during a cold-read release pressure test (run 13).

## Why Persona: `vibe-coder` (arrived from a social post, delegates everything, never files feedback — just leaves); angle `failure-paths`. Day-2 scenario: `warded #98` visibly did nothing (in reality: seeded credential expired, or the issue drew a NO-GO, or the container was reaped). Where do the docs send them? - README: no troubleshooting or "when it breaks" section at all. - `ward doctor` (found via FEATURES.md): docs/doctor.md scopes it to the allowlist + `security:` host probes — it says nothing about the agent subsystem, which is where this persona lives. (That gap is exactly ward#195; +1'd there.) - The rescue information *does exist*, but only inside per-subsystem docs a newcomer has no reason to open: the auth smoke test + "re-run 'claude' on the host to refresh" lives mid-way through agent-credentials.md; "your run's console/transcript/outcome landed in `~/.ward/agent-logs/<container>/`" lives in agent-observability.md; NO-GO-posts-a-comment lives in agent-preflight.md; clean-tree refusals live in exec-verb.md. There is no symptom-indexed entry point. A persona that will not read past the first screen — or an agent trying to self-rescue a failed run — has to already know which of 60+ docs holds their failure class. The vibe-coder closes the tab here, silently. ## Deliverable One `docs/troubleshooting.md` (or a README section) indexed by symptom, not by subsystem: "run launched then nothing happened" → auth smoke test + agent-logs path; "run never launched" → preflight NO-GO comment on the issue; "ward exec refused" → clean-tree gate + `--audit-override-dirty`; "container idles forever" → smoke-test skip + reaper. Each row: symptom → where to look → the fix. Link it from README. (A `ward agent doctor` verb is the deeper fix — that is ward#195's scope, linked, not duplicated here.) ## Done condition From the README alone, a user whose `warded` run failed can reach the correct diagnostic surface (agent-logs dir, issue comment, or host auth refresh) in ≤2 clicks without knowing which subsystem failed. --- **Severity: major-friction** · persona: vibe-coder · angle: failure-paths Filed by Claude Code during a cold-read release pressure test (run 13).

coilyco-ops added the

pressure-test

label

2026-07-01 21:57:54 +00:00

coilyco-ops referenced this issue

2026-07-01 21:57:55 +00:00

Create a ward agent doctor pattern to onboard someone onto the wide API surface of ward agent headless #195

coilyco-ops referenced this issue

2026-07-01 21:57:56 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-01 22:58:07 +00:00

The trust-gate refusal ('refusing untrusted owner') is a documented-nowhere dead end: no doc defines the primary-org set or a next step #484

coilyco-ops referenced this issue

2026-07-01 23:00:58 +00:00

No machine-readable success/failure contract for warded dispatch: exit codes undocumented, meta.json outcome enum names only success values #485

coilyco-ops commented

2026-07-01 23:01:21 +00:00

Author

Member

Sharpening datapoint from the-agent-itself/failure-paths (run 37): none of the four subsystem docs quote a single actual error string (trust-gate refusal, reservation conflict, auth smoke-test abort all have distinct Go-side messages, none appear in docs). For an agent — or a human pasting an error into search — symptom-grep against docs/ returns zero hits by construction. When this troubleshooting entry point gets built, indexing it by verbatim error text would close that class; #485 covers the machine-readable exit-code/outcome half.

coilyco-ops referenced this issue

2026-07-01 23:01:22 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:36 +00:00

coilyco-ops added the

headless

P1

labels

2026-07-01 23:30:29 +00:00

coilyco-ops referenced this issue

2026-07-01 23:58:53 +00:00

goose/opencode have no smoke gate and no documented failure path when the local Ollama endpoint is unreachable #487

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:49:12 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-447 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:49:10Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-447` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:49:10Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 02:52:05 +00:00

docs(troubleshooting): add symptom-indexed entry point for failed warded runs

coilysiren closed this issue

2026-07-02 02:52:05 +00:00

coilysiren commented

2026-07-02 02:52:31 +00:00

Owner

WARD-OUTCOME: done - added docs/troubleshooting.md, a symptom-indexed rescue index for failed warded runs, linked from the README ("When a run breaks") and the docs index.

This one was mostly a reading job, not a coding job: the rescue facts already existed, just fanned out across four subsystem docs, so the work was finding the real Go-side error strings and folding them into one symptom->look->fix table. Front-loading the four docs plus the two live comments paid off - the author's note asking to index by verbatim error text (trust-gate refusal, reservation conflict, smoke-test abort) shaped the whole thing, and quoting the exact strings from entrypoint.sh / exec_gate.go / agent.go means a paste-the-error search now lands here.

The only thing that fought back was the 80-line/4000-char doc-layout cap - a symptom index wants to sprawl, so I had to keep each row tight (landed at 67 lines / 3866 chars). Fairly confident in the result: pre-commit (dead-cross-links included) is green and the <=2-clicks-from-README done condition holds. Rough edge / follow-up: this is a hand-maintained mirror of error strings, so it will drift as those messages change - the durable fix is the ward agent doctor verb in ward#195, which I pointed at rather than duplicated.

WARD-OUTCOME: done - added docs/troubleshooting.md, a symptom-indexed rescue index for failed warded runs, linked from the README ("When a run breaks") and the docs index. This one was mostly a reading job, not a coding job: the rescue facts already existed, just fanned out across four subsystem docs, so the work was finding the real Go-side error strings and folding them into one symptom->look->fix table. Front-loading the four docs plus the two live comments paid off - the author's note asking to index by verbatim error text (trust-gate refusal, reservation conflict, smoke-test abort) shaped the whole thing, and quoting the exact strings from entrypoint.sh / exec_gate.go / agent.go means a paste-the-error search now lands here. The only thing that fought back was the 80-line/4000-char doc-layout cap - a symptom index wants to sprawl, so I had to keep each row tight (landed at 67 lines / 3866 chars). Fairly confident in the result: pre-commit (dead-cross-links included) is green and the <=2-clicks-from-README done condition holds. Rough edge / follow-up: this is a hand-maintained mirror of error strings, so it will drift as those messages change - the durable fix is the `ward agent doctor` verb in ward#195, which I pointed at rather than duplicated.

coilyco-ops commented

2026-07-02 07:52:00 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-447 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-447` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 07:52:04 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-447 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-447` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 07:52:07 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-447 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-447` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:51:58Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren commented

2026-07-02 07:53:51 +00:00

Owner

WARD-OUTCOME: done - docs/troubleshooting.md already shipped and merged to main in ffd5666 (closes #447); this run verified it, nothing left to land.

Candid retro: this one had almost no work left in it. I front-loaded the four scattered subsystem docs plus the agent/preflight/exec conventions, then went to touch the README and found a "When a run breaks" section already pointing at docs/troubleshooting.md - and the file already there, symptom-indexed, linked from the docs index too. Commit ffd5666 landed it on main days ago with closes #447, and the issue was already closed. So the honest report is: the feature was done before I started.

What I did do rather than declare victory blind: I grepped the verbatim error strings the doc quotes against the current Go source. auth smoke test: claude -p rejected the credentials / ... did not respond within 90s (internal/agents/claude/smoke.go), refusing untrusted owner %q (cmd/ward/agent.go), already reserved remotely/locally (cmd/ward/agent_reserve.go) - all still match. So the doc hasn't drifted yet.

Confidence is high that nothing more is needed here. The one rough edge is the same one the original author flagged in their closure note: the doc hand-mirrors Go-side error strings, so it will drift silently as those messages evolve, and nothing enforces the match. That's really the argument for the deeper ward#195 (ward agent doctor) fix, which this doc correctly defers to rather than duplicates. If drift-proofing is wanted sooner, a small pre-commit check asserting each quoted string still greps to a source literal would be a cheap follow-up worth its own issue.

WARD-OUTCOME: done - docs/troubleshooting.md already shipped and merged to main in ffd5666 (closes #447); this run verified it, nothing left to land. Candid retro: this one had almost no work left in it. I front-loaded the four scattered subsystem docs plus the agent/preflight/exec conventions, then went to touch the README and found a "When a run breaks" section already pointing at docs/troubleshooting.md - and the file already there, symptom-indexed, linked from the docs index too. Commit ffd5666 landed it on main days ago with `closes #447`, and the issue was already closed. So the honest report is: the feature was done before I started. What I did do rather than declare victory blind: I grepped the verbatim error strings the doc quotes against the current Go source. `auth smoke test: claude -p rejected the credentials` / `... did not respond within 90s` (internal/agents/claude/smoke.go), `refusing untrusted owner %q` (cmd/ward/agent.go), `already reserved remotely/locally` (cmd/ward/agent_reserve.go) - all still match. So the doc hasn't drifted yet. Confidence is high that nothing more is needed here. The one rough edge is the same one the original author flagged in their closure note: the doc hand-mirrors Go-side error strings, so it will drift silently as those messages evolve, and nothing enforces the match. That's really the argument for the deeper ward#195 (`ward agent doctor`) fix, which this doc correctly defers to rather than duplicates. If drift-proofing is wanted sooner, a small pre-commit check asserting each quoted string still greps to a source literal would be a cheap follow-up worth its own issue.

Rows
Columns

No symptom-indexed troubleshooting entry point: a failed warded run's rescue info exists but is scattered across four subsystem docs #447

Why

Deliverable

Done condition