docs: disambiguate the turn/loop primitive family

[drewstone]

Docs-only. Fixes six verified factual errors and adds the "which one do I call" table the turn/loop family never had. Nothing deleted, nothing renamed — every symbol an audit called dead turned out to have a live consumer.

What was wrong (each checked against ground truth, not memory)

Verified against the installed @tangle-network/sandbox@0.10.5 and @tangle-network/agent-runtime@0.79.3 .d.ts, plus this repo's own source.

#	Doc claim	Ground truth	Evidence
1	findCompletedTurn(turnId)	findCompletedTurn(turnId, { sessionId }) — sessionId is required	sandbox/dist/sandbox-tksuLdrT.d.ts:1474
2	_sessionStatus / _sessionResult poll lifecycle	Both are @internal. Public API is box.session(id).status() / .result()	sandbox-tksuLdrT.d.ts:1515,1519 (@internal tags) and :1403,247,266
3	Autonomous work = hand-rolled dispatchPrompt({detach:true}) + poll	box.driveTurn() does that pass, and agent-app already ships the wrapper driveSandboxTurn	SDK sandbox-tksuLdrT.d.ts:1501; wrapper src/sandbox/index.ts:2177 → :2201 box.driveTurn(...)
4	Browser gateway is "streamPrompt + lastEventId replay"	Two different mechanisms. Browser = box.mintScopedToken() + SessionGatewayClient (WebSocket). streamPrompt + lastEventId = server-side SSE reconnect; a browser never calls it	sandbox-tksuLdrT.d.ts:697,1513; dist/session-gateway/index.d.ts:262,334
5	"⚠️ turn-loop is a contribute-down candidate to agent-runtime"	Already contributed down. src/runtime/loop.ts:28-31 is export { runToolLoop as runAppToolLoop, streamToolLoop as streamAppToolLoop } — agent-app holds zero loop logic	src/runtime/loop.ts
6	Eval row prescribed three different primitives across two files, attributing none	Owners now named on every primitive	AGENTS.md eval row vs README eval row

Grep note: streamPrompt was never attributed to agent-runtime anywhere in this repo — that specific claim was wrong, and the real defect is attribution-by-adjacency (the transport table sat directly above "agent-runtime stays durability-free"). Fixed by labelling owners, not by deleting a sentence that didn't exist.

README peer table (checked against package.json)

• @tangle-network/agent-integrations was >=0.32.0; actual is >=0.44.0.
• Four declared peers were undocumented: sandbox >=0.9.7, agent-interface >=0.15.0, agent-knowledge >=1.7.0, agent-profile-materialize >=0.6.0.
• "Required by" column corrected by import graph: /tangle does not import agent-integrations (structural only) and /knowledge-loop does not import agent-runtime.
• Flagged the real manifest gap: driveSandboxTurn calls box.driveTurn, added in sandbox 0.10.5, above the declared >=0.9.7 floor. A consumer on 0.9.7–0.10.4 satisfies the peer and gets a runtime TypeError. Documented as "pin ≥ 0.10.5 yourself"; not bumped here — a peer bump forces lockfile churn across every consuming app and deserves its own PR with deploy verification.

What's new

### Turn execution primitives — which one, when in AGENTS.md, next to the transport section: 15 rows across @tangle-network/sandbox / agent-runtime / agent-app, each with owner, what it does, and a one-line USE WHEN — box.streamPrompt, box.driveTurn, mintScopedToken+SessionGatewayClient, streamSandboxPrompt, runSandboxPrompt, driveSandboxTurn, createBufferedTurnTap, pumpBufferedTurn, createSandboxChatProducer, createChatTurnRoutes, runDetachedTurn, runAppToolLoop/streamAppToolLoop, runToolLoop/streamToolLoop, handleChatTurn, runLoop.

The runLoop name collision, called out explicitly — it is four-way, not three:

1. runLoop — agent-runtime/loops. Multi-round, multi-candidate kernel: a driver plans N tasks per round, they run in N sandbox boxes, outputs fold through decide. Not a turn loop. Not on the package root.
2. runToolLoop / streamToolLoop — agent-runtime root. The in-turn tool loop.
3. runAppToolLoop / streamAppToolLoop — agent-app /runtime. Pure aliases of (2).
4. routerToolLoop — a third tool loop, on the same /loops subpath as (1) (router-client-Ak2IGuXq.d.ts:177, a positional-arg function unrelated to runToolLoop(opts)).

The doc gives a reading test: rounds/candidates/driver → (1); tool calls folded into one turn → (2)/(3)/(4).

CLAUDE.md is a symlink to AGENTS.md, so one edit covers both.

Deliberately NOT done

• No deletions. An audit claimed runSandboxPrompt was dead; it is on gtm-agent's live cron path (cron.ts:312 → gtm sandbox/index.ts:3198 → agent-app). The original fleet grep missed it because ripgrep skips dot-directories by default and every product keeps server code in src/lib/.server/.
• No rename of agent-runtime's runLoop. A hard rename breaks three external repos at import. The additive-alias path is a separate agent-runtime PR.
• No rename of runAppToolLoop / streamAppToolLoop. Four products import the current names; two others already call streamToolLoop directly. Both resolve to one function, so neither spelling is a bug — the doc now says so instead of leaving it to be "fixed" opportunistically.

Verification

• pnpm typecheck — clean (tsc --noEmit, no output).
• pnpm test — 193 files passed, 3143 tests passed, 0 failed, 0 skipped (74.7s). First run showed 139 failures from an unbuilt better-sqlite3 native binding plus 2 files needing dist/; both are worktree setup, fixed by pnpm rebuild better-sqlite3 + pnpm build, not by any change here.
• pnpm docs:gen re-run, then agent-docs --check → docs are fresh. Generation produced no diff, which is expected: agent-docs derives from source types, and this PR touches only prose.
• git merge-tree --write-tree origin/main HEAD → merges clean.

[tangletools]

✅ Auto-approved drewstone PR — 293d06b8

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-24T21:42:47Z}

[tangletools]

✅ No Blockers — 293d06b8

Review health 100/100 · Reviewer score 89/100 · Confidence 70/100 · 2 findings (2 low)

glm: Correctness 89 · Security 89 · Testing 89 · Architecture 89

Reviewer score is advisory once the run is complete and the verdict has no blockers.

Full multi-shot audit completed 2/2 planned shots over 3 changed files. Global verifier still owns final merge decision.

🟡 LOW Two peer-package collision claims unverifiable in this repo — AGENTS.md

The 'runLoop name collision' section asserts runLoopRunnerCli is 'the only runLoop-ish name on the root entry' of @tangle-network/agent-runtime, and that routerToolLoop ships on its /loops subpath. These are advisory disambiguation, not load-bearing, and could not be verified against agent-runtime source in this repo. If either symbol name/entry is wrong, future readers chasing the collision note would be mildly misled. Verify against agent-runtime at next substrate sync; no blocker for this doc PR.

🟡 LOW /knowledge-loop peer attribution omits transitive agent-runtime need — README.md

The table lists /knowledge-loop only under @tangle-network/agent-knowledge (>=1.7.0), but src/knowledge-loop/index.ts:38 states 'agent-knowledge and agent-runtime are PEER dependencies' and consumes the runtime turn driver via the ../runtime barrel (line 138). A consumer installing only agent-knowledge would hit a missing-peer error on /runtime. Not blocking: the README points to docs/CODEMAP.md as the always-current reference and the driver arrives indirectly through /runtime, but the row could note the transitive requirement for completeness.

---

_{tangletools · 2026-07-24T21:46:38Z · trace}

[tangletools]

✅ Approved — 2 non-blocking findings — 293d06b8

Full multi-shot audit completed 2/2 planned shots over 3 changed files. Global verifier still owns final merge decision.

Full immutable report for this review: trace

Summary comment for this run: full summary

---

_{tangletools · 2026-07-24T21:46:38Z · immutable trace}