feat(supervise): first-class continuity on graph edges — fresh | resume | steer, all ledgered

CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased
+## 0.127.0
+
+### Continuity is a first-class axis of delegates traversals
+
+Fresh respawns, session RESUMES, and live steers are now all expressible as plain data, each a ledgered fact.
+
+A `delegates` edge may declare `continuity: 'fresh' | 'resume'` — the default mode for that edge's spawn traversals (`'fresh'` is today's behavior; an edge without the field behaves byte-identically).
+With `'resume'`, every spawn after the node's first re-attaches to the node's most recent SETTLED worker: the kernel spawns a NEW live worker bound to the SAME node whose spawn context carries `resume: { ofWorker, sequence }` (`WorkerSpawnContext.resume`, typed `WorkerResumeContext`), and the executor seam (`makeWorkerAgent`) owns the actual session re-attachment — e.g. mapping `ofWorker` to a backend session id.
+The kernel keeps identity, ordering, ledger truth, and spend continuity: the resumed worker reserves from the same conserved pool, the ledger row's `workerId` is the NEW live worker, and the lineage rides the spawn context and the journal.
+Traversal caps count resumes exactly like fresh spawns.
+
+`spawn_agent` accepts a per-call `continuity` override that wins over the edge default in either direction, and resume fails closed with an actionable error at the tool:
+
+- `resume-no-prior` — an explicit resume of a node with no settled prior worker (spawn it fresh first; the DECLARED edge default instead degrades to `'fresh'` on the node's first spawn).
+- `resume-while-live` — a prior worker of the node is still live; steer is the live-worker channel, and the error says so.
+- `resume-with-key` — a semantic key makes an assignment run-once; resume explicitly runs the node again.
+
+`EdgeTraversal` and the journal `edge` event gain `continuity: 'fresh' | 'resume' | 'steer'` — spawn traversals stamp their effective mode, and every mid-run delivery into an already-live recipient (a driver steer leg, every analyzes delivery) stamps `'steer'` — zero ambiguity in the ledger about how each hop continued.
+`validateGraph` refuses nonsense continuity values and analyzes edges carrying the field (analysts are spawned by the analyst machinery; every analyst run is a fresh session over settled evidence).
+
+Threading: `SuperviseOptions` / `SupervisorAgentDeps` / `DriverAgentOptions` / `serveCoordinationMcp` / `CoordinationToolsOptions` gain `continuityByProfile?: Readonly<Record<string, ContinuityMode>>` (the per-profile-name default `runGraph` derives from delegates edges), and the kernel entry exports `ContinuityMode`, `WorkerResumeContext`, and `TraversalContinuity`.
+Known limit, stated where it lives: resume lineage is PROCESS-LOCAL (the same boundary as the analyst-run marker) — workers settled by a prior process of a durable run are not resume targets. The built-in backend seam (`workerFromBackend`) cannot re-attach sessions and FAILS LOUD on a `'resume'` spawn rather than ledgering a resume that never happened; session-resuming `makeWorkerAgent` seams are the resume consumers. Resume after a FAILED prior worker is deliberately allowed — a crashed session may still be resumable, and the executor seam decides.
+
+New example: `examples/graphs/shot-loop-resumed.ts` — the VB shot shape as data (reviewer root, coder node, `continuity: 'resume'`, `maxTraversals: 3`): shot 1 spawns `fresh`, shots 2–3 resume the prior settled session, proven offline in `tests/examples/graph-topologies.test.ts`.
 
 ### Python bridge install hints match the required Eval substrate
 

docs/api/mcp.md

@@ -4166,6 +4166,19 @@ resuming caller replays). Seeded into the question ledger verbatim — `list_que
 them, the stop policy counts the still-blocking ones, and `answer_question` can decide them.
 Omit/empty = fresh ledger (every run that is not a resume).
 
+##### continuityByProfile?
+
+> `readonly` `optional` **continuityByProfile?**: `Readonly`\<`Record`\<`string`, [`ContinuityMode`](runtime.md#continuitymode)\>\>
+
+Default continuity per PROFILE NAME (the stable node identity a graph pins). A name mapping
+to `'resume'` makes its spawns re-attach to the node's most recent settled worker whenever
+one exists — the node's FIRST spawn is effectively `'fresh'`, and a spawn while a prior
+worker of the node is still LIVE fails closed (`resume-while-live`; steer is the live-worker
+channel). The spawn tool's per-call `continuity` argument overrides the declared default in
+either direction. Omit = every spawn is `'fresh'` (status quo). Resume lineage is
+PROCESS-LOCAL (the same boundary as the analyst-run marker): workers settled by a prior
+process of a durable run are not resume targets.
+
 ***
 
 ### CoordinationTools

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.126.0` and `@tangle-network/agent-eval@0.143.0` 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.127.0` and `@tangle-network/agent-eval@0.143.0` 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` — 707 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -975,6 +975,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 707 exports.
 | `WidenLineage` | interface | A lineage the gate may widen toward — the settled child that looked promising + the findings |
 | `WidenSpec` | interface | `widen({ gate })` (G5) — the STREAMING spawn-on-completion driver. Unlike the static-fanout |
 | `WorkerProgress` | interface | The full live view of one worker, as `observe_agent` returns it mid-flight. |
+| `WorkerResumeContext` | interface | The resume lineage a `'resume'` spawn hands the executor seam |
 | `WorkerSpawnContext` | interface | Immutable task, allocation, identity attribution, and semantic key supplied while a manager's |
 | `WorkerSteerRequest` | interface | One durable down-leg request appended to a worker's inbox file. |
 | `WorkerToolTraceArtifact` | interface | Bytes stored under `WorkerTraceEvidence.traceRef`. |
@@ -992,6 +993,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 707 exports.
 | `AxisScoresOf` | type | Decompose ONE record into per-axis scores (e.g. judge dimensions). When set, it REPLACES the |
 | `BudgetReadout` | type | Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`, |
 | `CombinatorShape` | type | A combinator is just a `LoopShape`: a factory `(ShapeContext) => Agent` whose `Agent.act` |
+| `ContinuityMode` | type | How a spawn CONTINUES a node's prior work: `'fresh'` starts a brand-new session (the default, |
 | `CoordinationDeliveryEvidence` | type | Durable delivery evidence retained in commit order. An attempt without a later event carrying |
 | `CoordinationEvent` | type | Every message on the one typed pipe. UP (child→parent): question / settled / finding — queued for |
 | `CoordinationOwnerId` | type | Stable identity of the supervisor that owns one coordination stream. High-level supervision |
@@ -1053,6 +1055,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 707 exports.
 | `ToolLoopCompactionOptions` | type | Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional |
 | `ToolLoopMessageRecord` | type | Provider-neutral conversation record accepted by a tool-loop brain. |
 | `TrajectoryReportFn` | type | `trajectoryReport(...)` — the tree+cost reconstructor. Async (reads journal + optionally blobs). |
+| `TraversalContinuity` | type | How one ledgered hop CONTINUED: a spawn traversal stamps its effective spawn mode |
 | `UnknownMaterializationReason` | type | Why exact materialization evidence is unavailable for a node. |
 | `UsageEvent` | type | Normalized usage event — the single channel every executor reports through, so the |
 | `Verify` | type | `verify(spec)` — build the 2-node implement→verifier-gate combinator. |