docs(agents,goal-loop): codify debugging invariants and prompt_async reliability

[andybons]

Structural follow-up to today's incidents: capture the diagnostic rules that require judgment (the mechanical counterparts are landing separately as observability primitives — /health build identity, turn.end outcome records, per-message transcript degradation).

AGENTS.md — new "Debugging invariants" section:

• Cleansing marshals hide poison — clean journal + misbehaving resident session means the defect lives between ingest and persist; the LoadSession round-trip is the discriminating test
• Error text names the rejection, not the cause — identify which layer actually served the rejected credential/config before acting on an error message's advice
• Verify binary identity before blaming staleness — go version -m shows the embedded vcs.revision

docs/goal-loop.md — new "Operational reliability" subsection:

• goals retry and fail with journaled reasons; plain prompt_async dies silently on mid-stream errors (signature: reasoning-only final assistant message) — prefer goals for multi-step work, and treat that signature as failure when polling

🤖 Generated with Claude Code

https://claude.ai/code/session_013B9pwUYhT4o8se9skmS5PP

[claude]

Claude finished @andybons's task in 1m 7s —— View job

---

Review: docs(agents,goal-loop) — debugging invariants

Docs-only PR. I verified every code symbol and behavioral claim against the tree.

• Read the diff (AGENTS.md +26, docs/goal-loop.md +14)
• Verified all referenced symbols exist
• Checked behavioral claims against the engine/message code
• Checked consistency with existing docs

Accuracy check — all references resolve

Claim	Verified
ToolCall.safeArguments normalizes	✅ message/message.go:212
ProviderData.MarshalJSON drops empty entries	✅ message/message.go:363 (treats zero-length entry as absent, :331)
engine.LoadSession round-trip	✅ engine/store.go:233
engine/tool_call_poison_test.go	✅ exists
fix commit title	✅ f310412 on this branch
goal.stalled / goal.cleared records + retry semantics	✅ engine/store.go:34-36, engine/goal.go state machine, promptTurnWithRetry
goals retried, prompt_async not	✅ matches docs/goal-loop.md:61-71 and the PursueGoal write-up

The three AGENTS.md invariants (cleansing marshals hide poison, error text names the rejection not the cause, verify binary identity) are each grounded in a real, traceable incident, and the code-side facts they cite are correct.

One optional observation (non-blocking)

The new docs/goal-loop.md section describes the silent-death signature as "a final assistant message containing reasoning parts only — no text, no tool_call." Note this is a distinct signature from the truncated-tool-call incident codified in message/message.go:73-104 (which leaves a tool_call part present but with invalid Arguments — an unclean-in-memory case, not a reasoning-only final message). Both are real prompt_async failure modes; a reader might assume they're the same. If you want, a half-sentence distinguishing "reasoning-only tail" (stream died before content) from "truncated tool_call" (stream died mid-input_json_delta) would make the two mechanisms unmistakable. Purely editorial — not a correctness issue.

Verdict: accurate, well-grounded, and consistent with the codebase. LGTM.
· docs/debugging-invariants