feat(supervise): analyst-as-node — tool-equipped analysts as pinned, budgeted, traced workers; watchWorkers on runGraph

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.124.0
+
+### The analyst can be a tool-equipped agent, and graphs watch their workers
+
+An `analyzes` edge may now name a graph NODE as its analyst (`analyst: '<node-id>'`).
+On each matching settle, `runGraph` spawns that node's pinned profile as a real WORKER through the same spawn machinery every worker uses (`Scope.spawn` + the `makeWorkerAgent` seam): its task is the edge's registry directive plus the settled worker's tool-trace evidence, its spend reserves from the graph's one conserved budget, its node is journaled and traced like any worker, and its settle OUTPUT is the findings — published and routed per `to` exactly like registry-analyst findings, with the same ledger rows and canonicalization.
+Oracle doctrine holds structurally: an analyst node with a delegates edge pointing at it is refused, the driver cannot spawn it (`spawn_agent` still rejects non-worker nodes), an id living in both the registry and the nodes is refused as ambiguous, and an analyzes edge OVER an analyst node is refused because it would silently never fire.
+
+- `AnalyzeOnSettleRoute` gains `agent?: AgentProfile` — the coordination-layer form of the node analyst, usable by direct `supervise()` callers; lens routes still require the `analysts` registry, agent routes do not.
+- `WorkerSpawnContext` gains `analyst?: string`, the runtime-authored marker a node-pinning `makeWorkerAgent` reads to admit an analyst run it would refuse as a driver-authored spawn.
+- An analyst run's settlement never enters the settled-worker ledger or the finalizer and never re-fires the analyst hook, so an analyst cannot cascade onto itself; a refused analyst spawn publishes `{ analystSpawnRefused }` and a failed run `{ analystRunFailed }` as findings — observable, never silent.
+
+`RunGraphOptions` gains `watchWorkers` (mirroring `SuperviseOptions.watchWorkers`): the online detector panel now runs under `runGraph` with no leaf-seam wiring, raising `finding` events on the coordination bus the moment a live worker loops or error-storms.
+`examples/graphs/watchdog-steer.ts` now uses the passthrough, and the new `examples/graphs/analyst-agent-review.ts` shows a tool-equipped reviewer node analyzing an implementer.
+The kernel entry additionally exports the `WorkerWatchOptions` type.
+
+Known limit: durable-run resume does not yet compose with analyst-node graphs — an analyst spawned by a prior process settles as an ordinary worker on resume (documented at the in-flight map in `coordination.ts`).
+
 ## 0.123.0
 
 ### Current shared contracts and honest CLI accounting

docs/api/index.md

@@ -8403,7 +8403,7 @@ work: it returns the committed result on `prior` (see `SpawnOpts.key`).
 
 ###### agent
 
-[`Agent`](runtime.md#agent-1)\<`unknown`, `C`\> \| (() => [`Agent`](runtime.md#agent-1)\<`unknown`, `C`\>)
+[`Agent`](runtime.md#agent-2)\<`unknown`, `C`\> \| (() => [`Agent`](runtime.md#agent-2)\<`unknown`, `C`\>)
 
 ###### task
 
@@ -8608,7 +8608,7 @@ live `RootHandle` (the Q2 substrate the chat/pi-viz client later consumes).
 
 ###### root
 
-[`Agent`](runtime.md#agent-1)\<`Task`, `Out`\>
+[`Agent`](runtime.md#agent-2)\<`Task`, `Out`\>
 
 ###### task
 

docs/api/mcp.md

@@ -4103,8 +4103,11 @@ Analyst lenses run AUTOMATICALLY when a worker settles `done` (the analyst-on-se
  [AnalyzeOnSettleRoute](runtime.md#analyzeonsettleroute) generalizes the DESTINATION: findings can be delivered to a
  named live WORKER (wrapped in the route's directive, through the same authorized steer
  machinery a driver steer uses) instead of being hardwired to the spawning driver, and `over`
- restricts which settled workers feed the lens. Omit/empty = no auto-analysis (default; the
- driver can still run lenses on demand via `run_analyst`). Requires `analysts`.
+ restricts which settled workers feed the lens. A route carrying `agent` generalizes the
+ ANALYST itself: a tool-equipped agent spawned as a worker whose settle output is the
+ findings (see [AnalyzeOnSettleRoute.agent](runtime.md#agent)). Omit/empty = no auto-analysis (default;
+ the driver can still run lenses on demand via `run_analyst`). Lens routes require
+ `analysts`; agent routes do not.
 
 ##### maxLiveWorkers?
 
@@ -4133,7 +4136,7 @@ Max wall-clock ms a single `await_event` call may block waiting on a live worker
 
 ##### watchWorkers?
 
-> `readonly` `optional` **watchWorkers?**: [`WorkerWatchOptions`](#workerwatchoptions)
+> `readonly` `optional` **watchWorkers?**: [`WorkerWatchOptions`](runtime.md#workerwatchoptions)
 
 OPT-IN: run the ONLINE detector panel over each spawned worker's live tool trace and raise a
 `finding` on the bus the moment a detector fires — so the driver learns "this worker is
@@ -4165,27 +4168,6 @@ Omit/empty = fresh ledger (every run that is not a resume).
 
 ***
 
-### WorkerWatchOptions
-
-Online-detector wiring for spawned workers (`CoordinationToolsOptions.watchWorkers`).
-
-#### Properties
-
-##### detectors?
-
-> `readonly` `optional` **detectors?**: readonly `StreamingDetector`[]
-
-Detector panel; omit for the default stuck-loop + error-streak pair.
-
-##### maxFindingsPerWorker?
-
-> `readonly` `optional` **maxFindingsPerWorker?**: `number`
-
-Raise at most this many findings per worker, so one pathological worker cannot flood the
- driver's inbox with the same signal every span. Default 3; `<= 0` = unlimited.
-
-***
-
 ### CoordinationTools
 
 The supervisor-side toolbox returned by [createCoordinationTools](#createcoordinationtools): the MCP tool
@@ -7861,3 +7843,9 @@ Re-exports [MakeWorkerAgent](runtime.md#makeworkeragent)
 ### WorkerSpawnContext
 
 Re-exports [WorkerSpawnContext](runtime.md#workerspawncontext)
+
+***
+
+### WorkerWatchOptions
+
+Re-exports [WorkerWatchOptions](runtime.md#workerwatchoptions)

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.123.1` and `@tangle-network/agent-eval@0.142.2` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
+> **GENERATED** from `@tangle-network/agent-runtime@0.124.0` and `@tangle-network/agent-eval@0.142.2` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
 
 ## 1. agent-runtime — own public surface
 
@@ -510,7 +510,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 166 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 716 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 717 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -985,6 +985,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 716 exports.
 | `WorkerSteerRequest` | interface | One durable down-leg request appended to a worker's inbox file. |
 | `WorkerToolTraceArtifact` | interface | Bytes stored under `WorkerTraceEvidence.traceRef`. |
 | `WorkerTraceSeamCarrier` | interface | What the two readers below need off an `ExecutorContext` — its seam bag, and nothing else. |
+| `WorkerWatchOptions` | interface | Online-detector wiring for spawned workers (`CoordinationToolsOptions.watchWorkers`). |
 | `WorktreeCommandResult` | interface | Outcome of one verification command run in the worktree (test or typecheck). |
 | `WorktreeHarnessResult` | interface | The canonical result of one worktree-harness run, projected by each port to its own shape. |
 | `WorktreeProfileMaterializationReceipt` | interface | Proof of the profile inputs delivered before the worker process started. |