neuron/docs/NARRATED-RUNS-ENGINE-NOTES-20260713.md

Narrated runs — engine notes for Will (2026-07-13)

Source half: commit aa67f86 on feat/agent-phase1-soul (run-progress ledger, /api/run-progress/<sid> route, narration on the pause envelope, config display default). E2E-verified via the compiled test bed on Tim's clean profile.

Compiled-form-only fixes (in neuron-container-build/soul-narrated-runs-20260713.patch, applies ON TOP of soul-webfix-20260711.patch — these need porting to chat.el when the webfix itself is ported):

1. pause_turn + tool_use interleave: a pause_turn response can ALSO carry a client tool_use; resuming verbatim leaves it unpaired → Anthropic 400 "tool_use ids were found without tool_result". Fix: tool-bearing pause rounds are tool turns (dispatch + pair); verbatim resume only when the round has no client tool.
2. Agentic toolset scope: agentic_tools_all() fed EVERY connector/MCP tool (Notion, code-execution…) into the loop. Code-execution flips the API into programmatic tool calling, whose pairing protocol the single-tool manual loop does not speak — source of the dangling-pair 400s AND the bash_code_execution workspace-dodge. Fix: handle_chat_agentic declares builtins + ONE server web_search only. Connector tools return when the loop gains real multi-tool/programmatic support.
3. disable_parallel_tool_use: true on agentic requests — the loop captures only the first tool_use per round; Opus-class models parallel-call. Enforce the invariant.
4. web_search server-tool default variant → web_search_20250305 (GA). The 20260209 variant couples to code-execution ⇒ programmatic mode (see #2, and the June note: "inert unless code-execution attached").
5. Homegrown web_search removed from the tool catalog (server-side is the one tool).

Known engine debts this work surfaced (not fixed):

• Poisoned session history: a failed run persists the malformed assistant turn; every later turn in that session replays it and 400s. Needs history sanitation on load.
• Huge-history invalid-escape 400 (~346KB request) — likely the same poisoned blob.
• macOS note: replacing a binary in place invalidates its ad-hoc signature (instant silent SIGKILL, looks like exit 0). rm + cp + codesign -f -s - is the swap ritual.