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

coilyco-ops commented

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

Member

Why

Persona the-agent-itself / angle failure-paths. Task attempted from docs alone: "you dispatched warded owner/repo#N (detached by design) — now determine programmatically whether it worked, and if not, why." That is precisely the job ward's own director role performs, so the public contract should exist. Audit of every documented affordance:

Dispatch exit code — no agent-subsystem doc mentions exit codes at all (grep for exit/status across agent.md, agent-flags.md, agent-preflight.md, agent-subcommands.md, agent-observability.md, container-reap.md: zero contract statements). The project demonstrably knows how to publish this — docs/ci-watch.md documents 0/1/2/3 = passed/failed/timed-out/no-run — so its absence on the flagship surface reads as an oversight, not a policy.
Pre-flight NO-GO — "a NO-GO comments and launches nothing" (agent-preflight.md via agent-engineer.md): whether that dispatch exits 0 or non-zero is unstated, so a script cannot distinguish "declined to launch" from "launched".
Refusals — trust-gate and reservation-conflict refusals have error strings in Go, none quoted in any doc (companion comment on #447).
After the fact — agent-observability.md documents meta.json's outcome as inferred from console markers and names exactly two values (pushed-to-main, ward-salvage). The failure vocabulary is unstated: what outcome does a NO-GO, a crash, an auth smoke-test abort (ward#222), or an externally-stopped run produce? An agent cannot branch on an enum whose failure half is undocumented.

Net: a harness cannot supervise warded runs from the public docs — it must reverse-engineer exit codes and console markers, which is the exact context cost this angle measures.

Deliverable

Publish the machine-readable contract in one place (agent-flags.md or agent-observability.md): dispatch exit codes per refusal class (launched / NO-GO / untrusted owner / reservation conflict / launch failure), and the complete meta.json outcome enum including all failure values, drift-tested against the code the way the roster page is.

Done condition

An agent author can write if exit == X / switch outcome handling for every dispatch ending documented above, with values taken from docs, and a drift test keeps the doc honest.

Severity: major-friction · persona: the-agent-itself · angle: failure-paths
Filed by Claude Code during a cold-read release pressure test (run 37).

## Why Persona `the-agent-itself` / angle `failure-paths`. Task attempted from docs alone: "you dispatched `warded owner/repo#N` (detached by design) — now determine programmatically whether it worked, and if not, why." That is precisely the job ward's own director role performs, so the public contract should exist. Audit of every documented affordance: 1. **Dispatch exit code** — no agent-subsystem doc mentions exit codes at all (grep for exit/status across `agent.md`, `agent-flags.md`, `agent-preflight.md`, `agent-subcommands.md`, `agent-observability.md`, `container-reap.md`: zero contract statements). The project demonstrably knows how to publish this — `docs/ci-watch.md` documents `0/1/2/3 = passed/failed/timed-out/no-run` — so its absence on the flagship surface reads as an oversight, not a policy. 2. **Pre-flight NO-GO** — "a NO-GO comments and launches nothing" (`agent-preflight.md` via `agent-engineer.md`): whether that dispatch exits 0 or non-zero is unstated, so a script cannot distinguish "declined to launch" from "launched". 3. **Refusals** — trust-gate and reservation-conflict refusals have error strings in Go, none quoted in any doc (companion comment on #447). 4. **After the fact** — `agent-observability.md` documents `meta.json`'s `outcome` as inferred from console markers and names exactly two values (`pushed-to-main`, `ward-salvage`). The failure vocabulary is unstated: what outcome does a NO-GO, a crash, an auth smoke-test abort (ward#222), or an externally-stopped run produce? An agent cannot branch on an enum whose failure half is undocumented. Net: a harness cannot supervise warded runs from the public docs — it must reverse-engineer exit codes and console markers, which is the exact context cost this angle measures. ## Deliverable Publish the machine-readable contract in one place (`agent-flags.md` or `agent-observability.md`): dispatch exit codes per refusal class (launched / NO-GO / untrusted owner / reservation conflict / launch failure), and the complete `meta.json` `outcome` enum including all failure values, drift-tested against the code the way the roster page is. ## Done condition An agent author can write `if exit == X` / `switch outcome` handling for every dispatch ending documented above, with values taken from docs, and a drift test keeps the doc honest. --- **Severity: major-friction** · persona: the-agent-itself · angle: failure-paths Filed by Claude Code during a cold-read release pressure test (run 37).

coilyco-ops added the

pressure-test

label

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

coilyco-ops referenced this issue

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

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

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:21 +00:00

coilyco-ops added the

P1

headless

labels

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

coilyco-ops referenced this issue

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

headless pre-flight runs the agent unsandboxed on the host - weak models execute the task on real local checkouts #162

coilyco-ops commented

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

Author

Member

DECISION - define AND implement the full machine-readable contract in one PR: documented dispatch exit codes (launched / refused / error - note the host pre-flight and its NO-GO are being REMOVED per #162, so NO-GO reporting is an in-container/meta.json concern), meta.json outcome enum covering failure values, one doc page in ci-watch's 0/1/2/3 style. Kai reviews the enum at PR review. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

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 referenced this issue

2026-07-02 00:20:45 +00:00

In-container adversarial-review quorum gate before PR opens #134

coilyco-ops referenced this issue

2026-07-02 00:21:47 +00:00

explicitly bless ward agent doing "triage" style exits (eg. post a comment, or break into sub issues, or fan out into milestone) #144

coilyco-ops commented

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

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-485 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:49:03Z). 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-485` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:49:03Z). 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 03:08:10 +00:00

feat(agent): machine-readable dispatch exit-code + outcome contract

coilysiren closed this issue

2026-07-02 03:08:10 +00:00

coilysiren referenced this issue from a commit

2026-07-02 03:09:38 +00:00

docs(agent): frame dispatch codes as launched/refused/error, note ward#162

coilysiren commented

2026-07-02 03:10:19 +00:00

Owner

WARD-OUTCOME: done - dispatch exit-code contract (0/1/2/3/4/5, distinct per refusal class) + full meta.json outcome enum, drift-tested, in docs/agent-dispatch-contract.md; landed on main.

Retrospective: the shape was clearer than the issue implied. The real gap wasn't just missing docs - the refusals genuinely were indistinguishable (everything exited a generic 1, NO-GO/WRONG-REPO exited 0), so this had to be an implementation change, not a doc pass. Making the trust gate and reservation conflict carry Coded exit codes was clean because cli-guard's exitcode.Coded plumbing and main.go's errors.As routing were already there; I just gave the refusals codes. The one thing that fought back was the doc-size cap: agent-observability.md sat at 3998/4000 chars and FEATURES.md at 3999/4000, both effectively full, so I split the contract into its own page and had to abandon a FEATURES entry entirely (it's in the docs index instead).

The referenced docs/ci-watch.md doesn't exist in this clone - that was a cold-read artifact - so I anchored the exit-code style on the real shared exitcode contract instead.

Two honest caveats. First, I read the live thread last, and only then hit Kai's DECISION note that the host pre-flight and its NO-GO are being removed per #162; I'd already implemented NO-GO/WRONG-REPO as dispatch codes 4/5. They're accurate for the current code, and I added a forward-note that they move to a meta.json concern once #162 lands - but if the enum should drop 4/5 pre-emptively, that's a quick follow-up. Second, the enum still wants your review at the values level. Confidence is high on the mechanics (build/vet/tests/pre-commit all green, drift test guards both enums); medium on whether the NO-GO framing matches where #162 is headed.

WARD-OUTCOME: done - dispatch exit-code contract (0/1/2/3/4/5, distinct per refusal class) + full meta.json outcome enum, drift-tested, in docs/agent-dispatch-contract.md; landed on main. Retrospective: the shape was clearer than the issue implied. The real gap wasn't just missing docs - the refusals genuinely were indistinguishable (everything exited a generic 1, NO-GO/WRONG-REPO exited 0), so this had to be an implementation change, not a doc pass. Making the trust gate and reservation conflict carry Coded exit codes was clean because cli-guard's exitcode.Coded plumbing and main.go's errors.As routing were already there; I just gave the refusals codes. The one thing that fought back was the doc-size cap: agent-observability.md sat at 3998/4000 chars and FEATURES.md at 3999/4000, both effectively full, so I split the contract into its own page and had to abandon a FEATURES entry entirely (it's in the docs index instead). The referenced docs/ci-watch.md doesn't exist in this clone - that was a cold-read artifact - so I anchored the exit-code style on the real shared exitcode contract instead. Two honest caveats. First, I read the live thread last, and only then hit Kai's DECISION note that the host pre-flight and its NO-GO are being removed per #162; I'd already implemented NO-GO/WRONG-REPO as dispatch codes 4/5. They're accurate for the current code, and I added a forward-note that they move to a meta.json concern once #162 lands - but if the enum should drop 4/5 pre-emptively, that's a quick follow-up. Second, the enum still wants your review at the values level. Confidence is high on the mechanics (build/vet/tests/pre-commit all green, drift test guards both enums); medium on whether the NO-GO framing matches where #162 is headed.

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

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

Why

Deliverable

Done condition