docs(examples): four agent-graph topologies — collaborates, best-of-n, watchdog-steer, shot-loop

[drewstone]

Four runnable example topologies under examples/graphs/, each ≤25 LOC of plain data on shipped runGraph primitives, each with an offline test asserting the decisive LEDGER facts (proven non-vacuous: every assertion flips to FAIL under a targeted topology break).

• collaborates-review-loop — the peer-collaboration pattern expressible today: implementer's settle-trace critique routed to the reviewer WORKER as an authorized ledgered steer (analyzes … [delivered] -> collab:s1), verdict back to the driver, re-brief loop. Header states plainly that a direct worker↔worker channel is not a first-class edge; this is the mediated, fully-observable form.
• best-of-n — two candidate coders under one root, winner decided by the deliverable; ledger shows exactly two delivered spawns.
• watchdog-steer — online trace detectors raise mid-run findings; the corrective steer lands before settle as a ledgered delegates leg. (Deviation, stated in the header: RunGraphOptions lacks a watchWorkers passthrough, so the example wires the same shipped watchTrace panel at the leaf seam — the passthrough is the natural follow-up.)
• shot-loop — the VB multishot/AgentDriver loop as a 2-node cyclic graph: reviewer↔coder, maxTraversals as the shot budget, verify-analyst edge, deliverable gates on the verdict.

All run offline: 0 network connects under strace -f -e trace=connect with a scrubbed env. Suite 2343 passed; typecheck (examples tsconfig) + biome clean; zero src/ changes.

README documents two ledger semantics discovered during the adversarial audit: steers consume their edge's future spawn budget (cap is spawn-time-only), and workerId is destination on delegates/steer/routed rows but source on driver-destined finding rows.

[tangletools]

✅ Auto-approved drewstone PR — ddf723ab

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-08-03T05:28:12Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	4 (1 low, 3 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	155.5s (2 bridge agents)
Total	155.5s

💰 Value — sound-with-nits

Four runnable, offline runGraph topology examples (+ a non-vacuous ledger-asserting test) that demonstrate the graph algebra shipped 3 commits ago — squarely in the codebase's established example grain; two weak nits only.

• What it does: Adds examples/graphs/ with four ≤25-LOC plain-data topologies over the shipped runGraph primitive (landed in #704 / eca9c24): collaborates-review-loop (mediated peer review via analyzes lens routes), best-of-n (breadth = two delegates edges + maxLiveWorkers:2), watchdog-steer (online trace detector → mid-run ledgered steer), and shot-loop (reviewer↔coder cyclic graph with maxTraversals:3 a
• Goals it achieves: The runGraph graph algebra shipped with zero examples. This PR (1) makes the four canonical topologies the API was designed for copy-pasteable and runnable at $0, (2) documents two non-obvious ledger semantics discovered during authoring (steers consume their edge's future spawn budget since the cap is spawn-time-only; workerId is destination on delegates/steer/routed rows but source on driver
• Assessment: Good change, built in the grain of the codebase. Every other example dir (driver-loop/scripted-worker.ts, supervisor-loop/shared.ts, delegate/shared.ts) ships its own offline seam file importing only from the published package — so examples/graphs/shared.ts carrying its own scriptedBrain/leafSeam is the established pattern, not a reinvention. The examples correctly reuse shipped primitives
• Better / existing approach: No materially better architecture — the plain-data-over-shipped-primitives design with per-dir offline seams is the codebase's deliberate grain and the right call for a docs/examples PR landing immediately after the feature PR. The one candidate improvement is scriptedBrain triplication (searched: canonical at tests/kernel/scripted-brain.ts:14, a second local copy already existed at `src/impro
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: opencode: opencode error

🎯 Usefulness — sound-with-nits

Four offline, test-backed example topologies are the first end-user surface for the real, exported runGraph API layer; they fit the codebase grain, run green, and honestly document the one current API gap.

• Integration: Clean and reachable. Every imported symbol (runGraph, AgentGraph, RunGraphOptions, GraphResult, promptHandle, createPushTraceSource, watchTrace, defaultToolDetectors, AnalystRegistry, MakeWorkerAgent, ToolLoopChat, TraceSource) is defined and re-exported on the published @tangle-network/agent-runtime/kernel subpath (src/runtime/supervise/graph.ts:104,165,201,402; `src/r
• Fit with existing patterns: Fits; does not compete. Before this PR there were ZERO examples of the graph layer — grep runGraph|AgentGraph over examples/ returns only these new files. The existing loop examples (examples/driver-loop, examples/supervisor-loop, examples/supervise) drive the lower-level supervise()/runAgentRounds substrates; runGraph is an explicitly higher-level data-topology layer over `supervi
• Real-world viability: Sound for an examples PR. Three of four (collaborates, best-of-n, shot-loop) use only the public API with no workarounds — a real user can copy them directly onto a real backend by swapping makeWorkerAgent for backend. watchdog-steer is the honest exception (see finding). All run offline; ledger assertions are specific (exact edge ids, traversal ordinals, outcomes, workerIds) and the test ties
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Cruft: console debug added examples/graphs/shared.ts

• console.log(\n${tag} — result: ${res.result.kind} (runId: ${res.runId}))

💰 Value Audit

🟡 scriptedBrain now triplicated; PR's copy is a strict subset [maintenance] ``

scriptedBrain exists at tests/kernel/scripted-brain.ts:14 (canonical, with seen/usage/costUsd), src/improvement/driver-loop-generator.test.ts:39 (pre-existing local copy), and now examples/graphs/shared.ts:42 (subset, no seen/usage/costUsd). Forced by layering — examples import only from the published package, which exports no test helper — and the duplication pre-dates this PR. If ToolLoopChat's turn shape changes, three sites drift. Follow-up worth considering: promote a minimal scri

🟡 watchdog example reaches past RunGraphOptions to wire the watchdog [better-architecture] ``

examples/graphs/watchdog-steer.ts:54-67 wires watchTrace directly over the leaf trace source because RunGraphOptions (src/runtime/supervise/graph.ts:165-199) does not forward watchWorkers, which supervise() does accept (src/runtime/supervise/supervise.ts:748). The deviation is documented honestly in-file (watchdog-steer.ts:12-16) and the corrective steer still flows over the real delegates edge, so the example has standalone value. Cleaner sequence would be to add the `watchWorke

🎯 Usefulness Audit

🟡 watchdog-steer teaches a leaf-seam-only wiring that a real-backend user cannot copy [ergonomics] ``

RunGraphOptions (src/runtime/supervise/graph.ts:165-199) has no watchWorkers field, while supervise() accepts it (src/runtime/supervise/supervise.ts:748) and runs the same watchTrace+defaultToolDetectors panel internally. So this example wires watchTrace via the leaf seam's onTraceSource hook (examples/graphs/watchdog-steer.ts:54-67) and hands the signal to the scripted driver brain — a path only available when the caller supplies makeWorkerAgent. A user running a real backend:

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260803T053139Z}