docs(agents): backend-agents durable-turn architecture row (H25)

[btipling]

Closes #819. Refs #794 (umbrella), #818 (H24 blocker, cleared), #811 (D17, shipped).

What

Implements backend-agents H25 — the final row of the #794 umbrella. Adds a backend-agents architecture statement to AGENTS.md capturing the durable-turn ownership model in timeless terms. Docs-only; no application code, no test gate.

The new bullet sits at the top of the existing "Vercel Workflows (backend-agents)" subsection, ahead of the ops/wiring bullets, and states:

• The Workflow run owns the turn. A durable turn is owned by the Workflow run started at POST /api/turns, independent of any attached viewport — it survives tab close / refresh / logout. A viewport attaches to a live run (hydrate from Blob + GET /api/turns/:runId/stream); unmount/switch/New/Clear/logout is detach only, never a cancel. Cancel is the explicit POST /api/turns/:runId/cancel.
• Tools are steps. One 'use step' = one model round or one tool execution or one persist — never a mega-step, never wrap runAgentStream in a single step.
• /api/agent truth (post-D17). /api/agent is the legacy tests/JSON path; production turns use /api/turns. Stated as the current truth (D17 shipped in backend-agents D17: host runPrompt → POST /api/turns cutover #811), not a pending cutover.

Why

AGENTS.md already had the Workflows infra row (§ "Infrastructure already configured") and the ops subsection (enablement, smoke, caps), but no durable-turn architecture statement: nothing said the Workflow run owns the turn independent of any attached viewport, nothing documented the tools-as-steps granularity, and nothing tied it to the survive-tab-close/refresh product goal. This row closes that gap.

DoD

• AGENTS.md gains a backend-agents architecture row (a tight extension of the existing "Vercel Workflows (backend-agents)" material) stating: the Workflow run owns the turn (client-independent, survives tab close/refresh); one 'use step' = one model round OR one tool execution OR one persist (never a mega-step); and /api/agent is the legacy tests/JSON path with production on /api/turns (post-D17 current truth, not a pending cutover).
• Wording matches shipped behavior and the existing AGENTS.md rows (Feature divide line ~421, Working rules line ~431, Workflows infra row) — no contradiction, no duplication that drifts. The cancel route (POST /api/turns/:runId/cancel) matches G22 (PR feat(turns): server cancel seam for durable runs (G22 #816) #927); the durable stream/attach route matches H24 (backend-agents H24: docs/session-model.md + docs/agent-stream.md durable/attach wire #818 / PR docs: H24 durable-turn reserved-meta table + durable/attach wire (#818) #928).
• Docs-only (no test gate). No application code.
• Timeless — no "phase H25" / "see backend-agents H25: AGENTS.md backend-agents architecture row #819" narration.

Gates

Docs-only (AGENTS.md, *.md) → no test gates per the repo scope table. No typecheck/vitest/build run (nothing to compile). Diff is a single 10-line bullet addition.

Notes

• This is the 25th and final row of umbrella plan: backend-agents RESTART — client-independent turns (umbrella, ≥20 small issues + handoff) #794. Once this merges, every row of the backend-agents restart is done and the umbrella itself can be closed as complete.
• Branch: plan/h25-agents-md-architecture-row, off up-to-date main.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
invincible	Ignored		Sep 3, 2026 5:48am UTC

[btipling]

Adversarial review — PR #930

Verdict: PASS WITH NOTES
Repo: btipling/invincible
Scope: main ← plan/h25-agents-md-architecture-row · 1 file · docs-only (H25 / #819)
Lenses run: L7 L8 (skip: L1–L6 L9 — no application/UI/CI code; L2/L4 — N/A)
AGENTS.md read: yes (diff + surrounding Workflows subsection + Map of modules toolExecuteStep line; cross-check merged docs/feature-divide.md H23)

Findings

Sev	Lens	Finding	Break scenario	Refutation attempt	Confidence
Minor	L8	New architecture bullet says one 'use step' = “one tool execution”. Same file’s Map of modules already documents toolExecuteStep as one step per model round’s toolCalls. Merged H23 docs/feature-divide.md already uses toolExecuteStep (one model round's toolCalls / waves). DoD promised no contradiction / no drift.	An agent following the new top-of-Workflows architecture row 1:1 creates one 'use step' per tool call, fights wave/maxRetries=0 batch semantics, and diverges from feature-divide + the Map row two sections later.	Defender: plan #819 DoD reused the shorthand; ownership/attach/cancel//api/agent parts are correct. Fails: AGENTS.md is the agent north star — introducing a looser grain above the precise Map row is exactly the drift H23 already fixed elsewhere.	high

What checked clean

• Workflow run owns the turn; attach = Blob hydrate + GET …/stream; unmount/switch/New/Clear/logout = detach only; cancel = POST …/cancel — matches G22 / feature-divide Stop row.
• /api/agent legacy tests/JSON; production /api/turns — post-D17 current truth, not a pending cutover.
• Timeless (no H25 / #819 archaeology). Placement under “Vercel Workflows (backend-agents)” is appropriate.
• Mega-step / runAgentStream ban matches architecture antonym table.

Residual risk

No worker-Blob-writer sentence here (lives in feature-divide) — fine for this AGENTS architecture row; not a gap for H25 DoD.

Merge guidance

• PASS WITH NOTES: fix the step-grain wording (or explicitly accept the Minor). No Blockers/Majors. Docs-only.

What was not attacked

Live attach after logout; Production Workflows Observability.

Suggested fix punch list

File / area	Expected behavior	Acceptance criteria
AGENTS.md Workflows architecture bullet	Align with Map of modules + docs/feature-divide.md: one 'use step' = one model round or one toolExecuteStep (one model round’s toolCalls / waves) or one persist — never mega-step / never wrap runAgentStream.	No “one tool execution” reading; matches feature-divide H23; ownership/attach/cancel//api/agent sentences unchanged; timeless.

[btipling]

Adversarial re-review — PR #930 @ 9f00b3e

Verdict: clean enough (prior Minor closed)
Scope: Fixer round-1 docs wording only

Claim checklist

Claim	Result
Step grain = toolExecuteStep (one round’s toolCalls / waves)	PASS — matches Map of modules + merged docs/feature-divide.md
Ownership / attach / detach≠cancel / /api/agent legacy retained; timeless	PASS

No new findings.

Merge guidance

Safe to merge from this attack, subject to Bjorn’s call. Not merging from Reviewer.