Sub-agent truncation guard with embedded partial output

[seamus-brady]

Summary

PR 1 of the sub-agent-resilience plan. Lifts the cog-loop truncation guard pattern (PR #165) into the framework's react loop so specialist agents (writer, researcher, coder, etc.) recover from max_tokens hits the same way the cog loop already does.

When an agent's LLM returns stop_reason=MaxTokens with no tool calls, the framework now retries once with a scope-down nudge (without burning a turn). On the second hit it ships a deterministic admission that embeds the agent's accumulated partial work, so the orchestrator and operator can pick up what was produced even though the synthesis was capped.

Also includes the docs/roadmap/planned/sub-agent-resilience.md planning doc which covers all five fixes; this PR implements Fixes 1 + 2.

What changed

• src/agent/framework.gleam — truncation_retried: Bool field on ReactStats. Branch in do_react detects the failure mode, retries with nudge or ships admission. New helpers build_truncation_admission (pure, public for tests) and collect_assistant_text (extracts the agent's partial work across all turns of the failing react loop).
• test/agent/framework_truncation_guard_test.gleam — 10 new tests: 6 pure on the admission shape, 4 end-to-end driving the framework with mock providers.
• test/agent/framework_test.gleam — updated agent_success_surfaces_truncation_test to match the new contract (admission shipped instead of raw truncated text).
• docs/roadmap/planned/sub-agent-resilience.md — full plan covering Fixes 1-5 (this PR is Fixes 1 + 2; PRs 2 + 3 to follow).

Design deviation from the plan

The plan called for writing the agent's partial work to a separate artifact via the existing artifacts subsystem. This PR instead embeds the partial output in the admission text (with size cap and head/tail elision when over 4KB). Reasons:

1. Keeps the framework decoupled from artifact infrastructure — no new AgentSpec fields, no threading Subject(LibrarianMessage) through start_agent. The 15+ AgentSpec(...) construction sites stay unchanged.
2. The orchestrator's LLM sees the admission as a tool-result and can decide whether to call store_result on the partial work itself — natural Springdrift pattern.
3. Operator can read the partial work directly in the chat without retrieving an artifact.

If future evidence shows embedding isn't enough (e.g. partial work routinely exceeds 4KB and operators want full persistence), a follow-up PR can add framework-side artifact writing on top of this.

Test plan

• gleam build clean, no warnings
• gleam test — 2059 passed (10 new), no failures
• Pure tests prove admission contract: [truncation_guard:<agent>] prefix, agent + model + tokens embedded, partial verbatim when short, elided when long, empty-partial fallback, recovery suggestions present
• End-to-end retry-success test: provider returns MaxTokens then clean text. Agent returns AgentSuccess with the recovered text, NOT the truncated one and NOT the admission.
• End-to-end second-hit admission test: provider returns MaxTokens twice. Agent returns AgentSuccess whose result starts with [truncation_guard:writer] and embeds the partial work.
• truncated: True flag still surfaces on the admission so orchestrators that check the flag still know the cycle was capped.
• max_turns=1 retry test: the truncation retry does NOT burn a turn — agent with max_turns=1 still produces output on the recovery turn after one MaxTokens hit.
• Operator: rebuild + restart agent, dispatch a synthesis task that previously truncated, confirm either retry succeeds or [truncation_guard:writer] admission shows up cleanly in the chat instead of half a sentence.

What's next

Per the planning doc:

• PR 2 — Fix 3 (referenced_artifacts parameter on agent_* tool calls so children inherit prior structural work) + Fix 4 (checkpoint tool + skill discipline updates for writer/researcher).
• PR 3 — Fix 5 (codify Nemo's emergent strategies as orchestration skills + Strategy Registry seeding so every fresh instance has the floor strategies at boot).

🤖 Generated with Claude Code