durable.md

[**@tangle-network/agent-runtime**](README.md)

***

[@tangle-network/agent-runtime](README.md) / durable

# durable

## Classes

### FileObserverJournal

Durable, append-only third-person history for one concrete Runtime execution.
It consumes Runtime's existing hook stream and does not participate in execution
decisions. A broken observer therefore cannot change what an agent is allowed to do.

The write discipline deliberately matches `FileSpawnJournal`: serialized appends,
torn-tail recovery, short-write handling, and fsync before acknowledgement. One
execution owns one journal file; higher-level pursuit aggregation joins isolated
journals by `pursuitId` instead of making independent processes share a write head.

#### Implements

- [`ObserverJournal`](#observerjournal)

#### Constructors

##### Constructor

> **new FileObserverJournal**(`path`, `pursuitId`): [`FileObserverJournal`](#fileobserverjournal)

###### Parameters

###### path

`string`

###### pursuitId

`string`

###### Returns

[`FileObserverJournal`](#fileobserverjournal)

#### Properties

##### path

> `readonly` **path**: `string`

##### pursuitId

> `readonly` **pursuitId**: `string`

#### Methods

##### hooks()

> **hooks**(): [`RuntimeHooks`](index.md#runtimehooks)

###### Returns

[`RuntimeHooks`](index.md#runtimehooks)

###### Implementation of

[`ObserverJournal`](#observerjournal).[`hooks`](#hooks-1)

##### appendEvent()

> **appendEvent**(`event`): `Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Parameters

###### event

[`RuntimeHookEvent`](index.md#runtimehookevent)

###### Returns

`Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Implementation of

[`ObserverJournal`](#observerjournal).[`appendEvent`](#appendevent)

##### appendDecision()

> **appendDecision**(`point`): `Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Parameters

###### point

[`RuntimeDecisionPoint`](index.md#runtimedecisionpoint)

###### Returns

`Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Implementation of

[`ObserverJournal`](#observerjournal).[`appendDecision`](#appenddecision)

##### read()

> **read**(): `Promise`\<readonly [`ObserverRecord`](#observerrecord)[]\>

###### Returns

`Promise`\<readonly [`ObserverRecord`](#observerrecord)[]\>

###### Implementation of

[`ObserverJournal`](#observerjournal).[`read`](#read)

***

### RunDirectoryLockedError

The directory is held by a live process. `holder` is what that process recorded.

#### Extends

- `Error`

#### Constructors

##### Constructor

> **new RunDirectoryLockedError**(`path`, `holder`): [`RunDirectoryLockedError`](#rundirectorylockederror)

###### Parameters

###### path

`string`

###### holder

[`RunDirectoryLockHolder`](#rundirectorylockholder)

###### Returns

[`RunDirectoryLockedError`](#rundirectorylockederror)

###### Overrides

`Error.constructor`

#### Properties

##### path

> `readonly` **path**: `string`

##### holder

> `readonly` **holder**: [`RunDirectoryLockHolder`](#rundirectorylockholder)

***

### SettledRunDirectoryError

The directory already holds a settle record, so the run it records must not be re-entered.

#### Extends

- `Error`

#### Constructors

##### Constructor

> **new SettledRunDirectoryError**(`path`, `recordedRunId`, `requestedRunId`): [`SettledRunDirectoryError`](#settledrundirectoryerror)

###### Parameters

###### path

`string`

###### recordedRunId

`string`

###### requestedRunId

`string`

###### Returns

[`SettledRunDirectoryError`](#settledrundirectoryerror)

###### Overrides

`Error.constructor`

#### Properties

##### path

> `readonly` **path**: `string`

##### recordedRunId

> `readonly` **recordedRunId**: `string`

The root of the recorded run, which is its `runId`.

***

### SupervisePursuitError

A failed Runtime execution whose complete third-person projection was retained.

#### Extends

- `Error`

#### Constructors

##### Constructor

> **new SupervisePursuitError**(`cause`, `pursuit`, `observerPath`, `failurePath`): [`SupervisePursuitError`](#supervisepursuiterror)

###### Parameters

###### cause

`unknown`

###### pursuit

[`PursuitProjection`](#pursuitprojection)

###### observerPath

`string`

###### failurePath

`string`

###### Returns

[`SupervisePursuitError`](#supervisepursuiterror)

###### Overrides

`Error.constructor`

#### Properties

##### pursuit

> `readonly` **pursuit**: [`PursuitProjection`](#pursuitprojection)

##### observerPath

> `readonly` **observerPath**: `string`

##### failurePath

> `readonly` **failurePath**: `string`

`runDir/failure.json`: the record of this throw.

## Interfaces

### ChatStreamEvent

The NDJSON line protocol every product chat client already speaks.

#### Properties

##### type

> **type**: `string`

##### data?

> `optional` **data?**: `Record`\<`string`, `unknown`\>

***

### ChatTurnIdentity

Identity of a chat turn. `tenantId` is the workspace id for workspace-
 scoped products and the user id for session-scoped products.

#### Properties

##### tenantId

> **tenantId**: `string`

##### sessionId

> **sessionId**: `string`

Thread / session id.

##### userId

> **userId**: `string`

##### turnIndex

> **turnIndex**: `number`

Monotonic 0-based turn index within the session.

***

### ChatTurnProducer

The live side of a turn returned by the product's `produce` hook.

#### Type Parameters

##### TEvent

`TEvent` *extends* [`ChatStreamEvent`](#chatstreamevent) = [`ChatStreamEvent`](#chatstreamevent)

#### Properties

##### stream

> **stream**: `AsyncGenerator`\<`TEvent`, `void`, `unknown`\>

The turn's event stream. Forwarded verbatim to the caller.

#### Methods

##### finalText()

> **finalText**(): `string`

The turn's final assistant text. Read once, after `stream` drains.

###### Returns

`string`

***

### ChatTurnHooks

Product callbacks invoked while one chat turn runs.

#### Methods

##### produce()

> **produce**(): [`ChatTurnProducer`](#chatturnproducer)

Build the backend stream. The engine forwards events verbatim and
 reads `finalText()` once the stream drains.

###### Returns

[`ChatTurnProducer`](#chatturnproducer)

##### persistAssistantMessage()

> **persistAssistantMessage**(`input`): `Promise`\<`void`\>

Persist the assistant message to the product's own store. Called
 once, after drain, with the assembled (transform-applied) text.

###### Parameters

###### input

###### identity

[`ChatTurnIdentity`](#chatturnidentity)

###### finalText

`string`

###### Returns

`Promise`\<`void`\>

##### onTurnComplete()?

> `optional` **onTurnComplete**(`input`): `Promise`\<`void`\>

Optional post-processing for proposals, citations, or credit metering.
 Errors are logged without failing a turn that already streamed.

###### Parameters

###### input

###### identity

[`ChatTurnIdentity`](#chatturnidentity)

###### finalText

`string`

###### Returns

`Promise`\<`void`\>

##### onEvent()?

> `optional` **onEvent**(`event`): `void` \| `Promise`\<`void`\>

Optional per-event side channel, such as a Durable Object broadcast.
 Runs for every emitted event, including the lifecycle envelope.
 Errors are logged without breaking the chat stream.

###### Parameters

###### event

[`ChatStreamEvent`](#chatstreamevent)

###### Returns

`void` \| `Promise`\<`void`\>

##### transformFinalText()?

> `optional` **transformFinalText**(`text`): `string` \| `Promise`\<`string`\>

Optional pre-persist transform of the final text (e.g. PII
 redaction). Affects only what is persisted; the live stream is
 never altered.

###### Parameters

###### text

`string`

###### Returns

`string` \| `Promise`\<`string`\>

##### traceFlush()?

> `optional` **traceFlush**(): `Promise`\<`void`\>

Optional trace flush. Handed to `waitUntil` so the worker stays alive
 until export completes.

###### Returns

`Promise`\<`void`\>

***

### RunChatTurnInput

Inputs for one streamed product chat turn.

#### Properties

##### identity

> **identity**: [`ChatTurnIdentity`](#chatturnidentity)

##### hooks

> **hooks**: [`ChatTurnHooks`](#chatturnhooks)

##### waitUntil?

> `optional` **waitUntil?**: (`p`) => `void`

Worker liveness hook. When omitted, trace flush is awaited inline
 before the stream closes.

###### Parameters

###### p

`Promise`\<`unknown`\>

###### Returns

`void`

##### log?

> `optional` **log?**: (`message`, `meta?`) => `void`

Structured logger for swallowed hook errors. Defaults to
 `console.error` so failures surface without product wiring.

###### Parameters

###### message

`string`

###### meta?

`Record`\<`string`, `unknown`\>

###### Returns

`void`

***

### ChatTurnResult

HTTP response values returned for one chat turn.

#### Properties

##### body

> **body**: `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>

NDJSON body to return as the platform `Response` body.

##### contentType

> **contentType**: `"application/x-ndjson"`

Content type for the response.

***

### ObserverRecord

One immutable record in the observer plane. `sequence` is journal order, not
execution order; causal/runtime order remains available on the underlying event.
`previousDigest` + `digest` make deletion, reordering, or mutation detectable.

#### Properties

##### schemaVersion

> `readonly` **schemaVersion**: `1`

##### pursuitId

> `readonly` **pursuitId**: `string`

##### sequence

> `readonly` **sequence**: `number`

##### kind

> `readonly` **kind**: [`ObserverRecordKind`](#observerrecordkind)

##### observedAt

> `readonly` **observedAt**: `number`

##### previousDigest?

> `readonly` `optional` **previousDigest?**: `string`

##### event?

> `readonly` `optional` **event?**: [`RuntimeHookEvent`](index.md#runtimehookevent)\<`unknown`\>

##### decision?

> `readonly` `optional` **decision?**: [`RuntimeDecisionPoint`](index.md#runtimedecisionpoint)

##### digest

> `readonly` **digest**: `string`

***

### ObserverJournal

#### Methods

##### appendEvent()

> **appendEvent**(`event`): `Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Parameters

###### event

[`RuntimeHookEvent`](index.md#runtimehookevent)

###### Returns

`Promise`\<[`ObserverRecord`](#observerrecord)\>

##### appendDecision()

> **appendDecision**(`point`): `Promise`\<[`ObserverRecord`](#observerrecord)\>

###### Parameters

###### point

[`RuntimeDecisionPoint`](index.md#runtimedecisionpoint)

###### Returns

`Promise`\<[`ObserverRecord`](#observerrecord)\>

##### read()

> **read**(): `Promise`\<readonly [`ObserverRecord`](#observerrecord)[]\>

###### Returns

`Promise`\<readonly [`ObserverRecord`](#observerrecord)[]\>

##### hooks()

> **hooks**(): [`RuntimeHooks`](index.md#runtimehooks)

###### Returns

[`RuntimeHooks`](index.md#runtimehooks)

***

### PursuitNodeUsage

One node's token usage by class. Cache and reasoning classes are absent when the provider did
not report them — absence is not zero. `tokensKnown` is `false` when work happened whose token
count no provider reported, which makes `input`/`output` a floor.

#### Properties

##### input

> `readonly` **input**: `number`

##### output

> `readonly` **output**: `number`

##### cacheRead?

> `readonly` `optional` **cacheRead?**: `number`

##### cacheWrite?

> `readonly` `optional` **cacheWrite?**: `number`

##### reasoning?

> `readonly` `optional` **reasoning?**: `number`

##### tokensKnown

> `readonly` **tokensKnown**: `boolean`

***

### PursuitNodePlatform

One node's PLATFORM consumption — box wall time, the resource a subscription seat really pays.

Kept apart from `PursuitNodeCost` because the two answer different questions and fail
independently: a seat run reports a truthful `$0` and real minutes, a caller-account run
reports real dollars and may report no minutes at all. Collapsing them into one "spend known"
figure hides which one is missing.

Absent on a node that ran no box. `boxMinutes` absent WITH the block present says a box ran and
nothing measured it — a missing measurement is never a zero.

#### Properties

##### boxMinutes?

> `readonly` `optional` **boxMinutes?**: `number`

##### boxMinutesKnown

> `readonly` **boxMinutesKnown**: `boolean`

`false` when a box ran whose time could not be closed, so `boxMinutes` is a floor.

##### provenance

> `readonly` **provenance**: `"estimated"` \| `"observed"` \| `"uncaptured"`

`observed` = the platform billed the minutes; `estimated` = Runtime derived them from the box
 lifetime it watched; `uncaptured` = a box ran and nothing measured it.

***

### PursuitNodeCost

One node's dollar cost with the provenance that decides whether it may be compared or summed.

#### Properties

##### usd

> `readonly` **usd**: `number`

##### usdKnown

> `readonly` **usdKnown**: `boolean`

##### usdEstimated?

> `readonly` `optional` **usdEstimated?**: `number`

The part of `usd` a model catalog priced because no provider receipt covered it.

##### provenance

> `readonly` **provenance**: [`PursuitCostProvenance`](#pursuitcostprovenance)

***

### PursuitNodeTiming

One node's clock. `wallMs` is `settledAt - startedAt` and is deliberately distinct from the
executor-reported `spent.ms` sums, which under-report and overlap across parallel children.
`firstTokenAt` stays absent unless a provider reports that instant; it is never inferred from
`firstOutputAt`, which is when the node first reported usage for a turn.

#### Properties

##### startedAt

> `readonly` **startedAt**: `number`

##### firstOutputAt?

> `readonly` `optional` **firstOutputAt?**: `number`

##### firstTokenAt?

> `readonly` `optional` **firstTokenAt?**: `number`

##### settledAt?

> `readonly` `optional` **settledAt?**: `number`

##### wallMs?

> `readonly` `optional` **wallMs?**: `number`

***

### PursuitRunTotals

One run's spend counted once, and each node's own share of it. `inclusive` and the entries of
`exclusiveByNode` are the two views a client needs to show a tree without double counting.

#### Properties

##### inclusive

> `readonly` **inclusive**: [`Spend`](runtime.md#spend)

The whole run counted once. A node's settled `spent` already contains the child work its own
nested tree reported, so summing only the run's top-level nodes plus every node's own
inference counts each model call exactly once.

##### exclusiveByNode

> `readonly` **exclusiveByNode**: `Readonly`\<`Record`\<`string`, [`Spend`](runtime.md#spend)\>\>

Each node's own share: its reported spend and own inference minus what its direct children
reported. Keyed by node id, plus the run root when the root itself metered inference. The
entries sum to `inclusive` by construction.

***

### PursuitRunProjection

One attempt at one concrete Runtime run: the stretch of `agent.run` lifecycle from a `before`
to the `after` or `error` that settles it. A run whose first attempt threw and whose corrected
attempt settled is two rows, so `error` names only the attempt that failed.

A `before` observed while an attempt is still open does not open another: it is a process
that resumed the run after the previous process died without a terminal record, and the row
counts it in `resumeCount`. The alternative, a row per process start, would leave the killed
process's row `running` for the rest of history.

#### Properties

##### runId

> `readonly` **runId**: `string`

##### attemptIndex

> `readonly` **attemptIndex**: `number`

Zero-based position of this attempt among the run's attempts, in journal order.

##### resumeCount

> `readonly` **resumeCount**: `number`

How many times a process resumed this attempt after a predecessor died mid-run.

##### status

> `readonly` **status**: [`PursuitStatus`](#pursuitstatus)

##### settledAt?

> `readonly` `optional` **settledAt?**: `number`

##### error?

> `readonly` `optional` **error?**: `string`

##### firstSequence

> `readonly` **firstSequence**: `number`

##### lastSequence

> `readonly` **lastSequence**: `number`

##### firstObservedAt

> `readonly` **firstObservedAt**: `number`

##### lastObservedAt

> `readonly` **lastObservedAt**: `number`

##### eventCount

> `readonly` **eventCount**: `number`

##### decisionCount

> `readonly` **decisionCount**: `number`

##### targets

> `readonly` **targets**: `Readonly`\<`Record`\<`string`, `number`\>\>

##### decisions

> `readonly` **decisions**: `Readonly`\<`Record`\<`string`, `number`\>\>

##### totals

> `readonly` **totals**: [`PursuitRunTotals`](#pursuitruntotals)

##### spendGaps?

> `readonly` `optional` **spendGaps?**: readonly [`SpendGap`](runtime.md#spendgap)[]

The nodes whose accounting is incomplete. Present exactly when non-empty.

***

### PursuitNodeProjection

#### Properties

##### id

> `readonly` **id**: `string`

##### parentId?

> `readonly` `optional` **parentId?**: `string`

##### runId

> `readonly` **runId**: `string`

Node ids are scoped to this concrete Runtime tree; `(runId,id)` is identity.

##### label?

> `readonly` `optional` **label?**: `string`

##### runtime?

> `readonly` `optional` **runtime?**: `string`

The runner that executed this node — the executor's own name, not a harness guess.

##### depth?

> `readonly` `optional` **depth?**: `number`

##### assignmentId?

> `readonly` `optional` **assignmentId?**: `string`

##### identity?

> `readonly` `optional` **identity?**: `unknown`

##### budget?

> `readonly` `optional` **budget?**: `unknown`

##### status

> `readonly` **status**: [`PursuitStatus`](#pursuitstatus)

##### settledAt?

> `readonly` `optional` **settledAt?**: `number`

##### spent?

> `readonly` `optional` **spent?**: [`Spend`](runtime.md#spend)

The child work this node reported at settlement. Absent until a terminal record lands.

##### ownInference?

> `readonly` `optional` **ownInference?**: [`Spend`](runtime.md#spend)

This node's OWN inference, re-homed from its nested tree. Absent when it drove no turns.

##### usage?

> `readonly` `optional` **usage?**: [`PursuitNodeUsage`](#pursuitnodeusage)

Absent until a spend record lands; the run's `spendGaps` then names the node.

##### cost?

> `readonly` `optional` **cost?**: [`PursuitNodeCost`](#pursuitnodecost)

Absent until a spend record lands; the run's `spendGaps` then names the node.

##### platform?

> `readonly` `optional` **platform?**: [`PursuitNodePlatform`](#pursuitnodeplatform)

What the node consumed on the PLATFORM. Absent on a node that ran no box.

##### timing?

> `readonly` `optional` **timing?**: [`PursuitNodeTiming`](#pursuitnodetiming)

##### attemptId?

> `readonly` `optional` **attemptId?**: `string`

The kernel-minted attempt this node's execution binding is keyed on.

##### execution?

> `readonly` `optional` **execution?**: `object`

The runner-native execution the node bound to: a request, session, run, process, or tree.

###### kind

> `readonly` **kind**: `string`

###### id

> `readonly` **id**: `string`

##### model?

> `readonly` `optional` **model?**: `string`

The model the materialization receipt names, when the runner reported one.

##### backend?

> `readonly` `optional` **backend?**: `string`

The concrete backend the profile materialized onto.

##### placement?

> `readonly` `optional` **placement?**: `Readonly`\<`Record`\<`string`, `string` \| `number` \| `boolean` \| `null`\>\>

##### modelCalls?

> `readonly` `optional` **modelCalls?**: readonly `string`[]

Model-call identifiers this node's own turns reported, in order, deduplicated.

##### materialization?

> `readonly` `optional` **materialization?**: [`ProfileMaterializationReceipt`](runtime.md#profilematerializationreceipt)

##### executionBindings?

> `readonly` `optional` **executionBindings?**: readonly [`ExecutionBindingReceipt`](runtime.md#executionbindingreceipt)[]

##### providerModel?

> `readonly` `optional` **providerModel?**: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence)

What the provider itself reported serving, and why it is unknown when it is.

##### trace?

> `readonly` `optional` **trace?**: [`WorkerTraceEvidence`](runtime.md#workertraceevidence)

Content-addressed pointer to this node's persisted tool trace, or why there is none.

##### outRef?

> `readonly` `optional` **outRef?**: `string`

##### score?

> `readonly` `optional` **score?**: `number`

##### valid?

> `readonly` `optional` **valid?**: `boolean`

##### reason?

> `readonly` `optional` **reason?**: `string`

##### infra?

> `readonly` `optional` **infra?**: `boolean`

##### wait?

> `readonly` `optional` **wait?**: `unknown`

##### firstSequence

> `readonly` **firstSequence**: `number`

##### lastSequence

> `readonly` **lastSequence**: `number`

##### firstObservedAt

> `readonly` **firstObservedAt**: `number`

##### lastObservedAt

> `readonly` **lastObservedAt**: `number`

##### eventCount

> `readonly` **eventCount**: `number`

##### turnCount

> `readonly` **turnCount**: `number`

***

### PursuitProjection

#### Properties

##### pursuitId

> `readonly` **pursuitId**: `string`

##### sequence

> `readonly` **sequence**: `number`

Number of records in this concrete execution journal.

##### chainTip

> `readonly` **chainTip**: `string`

Digest-chain tip for this concrete execution journal.

##### firstObservedAt

> `readonly` **firstObservedAt**: `number`

##### lastObservedAt

> `readonly` **lastObservedAt**: `number`

##### runs

> `readonly` **runs**: readonly [`PursuitRunProjection`](#pursuitrunprojection)[]

##### nodes

> `readonly` **nodes**: readonly [`PursuitNodeProjection`](#pursuitnodeprojection)[]

##### eventCount

> `readonly` **eventCount**: `number`

##### decisionCount

> `readonly` **decisionCount**: `number`

***

### RunDirectoryLockHolder

What the lock file records about its holder.

#### Extended by

- [`RunDirectoryLock`](#rundirectorylock)

#### Properties

##### pid

> `readonly` **pid**: `number`

##### startedAt

> `readonly` **startedAt**: `string`

ISO instant the holder took the lock.

##### runId

> `readonly` **runId**: `string`

##### processStart?

> `readonly` `optional` **processStart?**: `string`

The OS's start token for `pid` when the host reports one (`readProcessStart`). A holder
without one is judged by pid liveness alone, which cannot detect a reused pid.

***

### RunDirectoryLock

A held lock. `release()` removes the file; it is safe to call more than once.

#### Extends

- [`RunDirectoryLockHolder`](#rundirectorylockholder)

#### Properties

##### pid

> `readonly` **pid**: `number`

###### Inherited from

[`RunDirectoryLockHolder`](#rundirectorylockholder).[`pid`](#pid)

##### startedAt

> `readonly` **startedAt**: `string`

ISO instant the holder took the lock.

###### Inherited from

[`RunDirectoryLockHolder`](#rundirectorylockholder).[`startedAt`](#startedat-1)

##### runId

> `readonly` **runId**: `string`

###### Inherited from

[`RunDirectoryLockHolder`](#rundirectorylockholder).[`runId`](#runid-2)

##### processStart?

> `readonly` `optional` **processStart?**: `string`

The OS's start token for `pid` when the host reports one (`readProcessStart`). A holder
without one is judged by pid liveness alone, which cannot detect a reused pid.

###### Inherited from

[`RunDirectoryLockHolder`](#rundirectorylockholder).[`processStart`](#processstart)

##### path

> `readonly` **path**: `string`

#### Methods

##### release()

> **release**(): `Promise`\<`void`\>

###### Returns

`Promise`\<`void`\>

***

### RunDirectoryHolderLiveness

What [runDirectoryHolderIsLive](#rundirectoryholderislive) proved about a run directory's recorded holder.

#### Properties

##### live

> `readonly` **live**: `boolean`

True only while the process that took the lock is still the process that holds the pid.

##### holder?

> `readonly` `optional` **holder?**: [`RunDirectoryLockHolder`](#rundirectorylockholder)

The holder the lock file names. Absent when no lock file names one, which reads as not live.

***

### DurableFailureRecord

What `failure.json` records about the most recent throw.

#### Properties

##### runId

> `readonly` **runId**: `string`

##### pursuitId

> `readonly` **pursuitId**: `string`

##### at

> `readonly` **at**: `string`

ISO instant the throw was recorded.

##### error

> `readonly` **error**: `object`

###### name

> `readonly` **name**: `string`

###### message

> `readonly` **message**: `string`

***

### SupervisePursuitOptions

#### Extends

- [`SuperviseOptions`](runtime.md#superviseoptions)

#### Properties

##### pursuitId

> `readonly` **pursuitId**: `string`

Stable objective identity spanning concrete Runtime runs.

##### runDir

> `readonly` **runDir**: `string`

One concrete Runtime execution owns one durable directory and observer journal.
A pursuit spanning several runs reuses `pursuitId` across distinct `runDir`s;
Intelligence joins those isolated projections without a shared write head.

###### Overrides

[`SuperviseOptions`](runtime.md#superviseoptions).[`runDir`](runtime.md#rundir-2)

##### budget

> `readonly` **budget**: [`Budget`](runtime.md#budget-18)

The conserved compute pool for the whole run.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`budget`](runtime.md#budget-16)

##### rootHandle?

> `readonly` `optional` **rootHandle?**: [`RootHandle`](runtime.md#roothandle-2)\<`unknown`\>

Caller-created live handle for observing, steering, or cancelling this root manager. Runtime
attaches it before execution and detaches it after the join barrier.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`rootHandle`](runtime.md#roothandle-1)

##### signal?

> `readonly` `optional` **signal?**: `AbortSignal`

Caller-owned cancellation for the complete recursive run. Aborting it cascades through the
root scope and every live child, including acquisition and backend execution.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`signal`](runtime.md#signal-20)

##### execution?

> `readonly` `optional` **execution?**: [`AgentExecutionRef`](runtime.md#agentexecutionref)

Trusted candidate and pursuit attribution for the root. The runtime derives profile/task
digests itself from the exact detached values it executes.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`execution`](runtime.md#execution-2)

##### backend?

> `readonly` `optional` **backend?**: [`ExecutorConfig`](runtime.md#executorconfig)

WHERE workers run — derives the worker seam. Provide this OR an explicit `makeWorkerAgent`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`backend`](runtime.md#backend-4)

##### deliverable?

> `readonly` `optional` **deliverable?**: `string` \| [`DeliverableSpec`](runtime.md#deliverablespec)\<`unknown`\>

The independent completion check for backend-derived workers and direct supervisor
 submissions. Strongly recommended: without it the supervisor cannot submit its own work and
 backend-derived workers fall back to their own validity signal. A `string` names an entry in
 `registry.deliverables`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`deliverable`](runtime.md#deliverable-4)

##### resolveDeliverable?

> `readonly` `optional` **resolveDeliverable?**: (`input`) => [`DeliverableSpec`](runtime.md#deliverablespec)\<`unknown`\> \| `undefined`

Resolve the completion check for one exact authorized backend-derived child. The callback runs
after spawn authorization and receives a detached immutable context. It may return `undefined`
to use the run-wide `deliverable`; a managed child receives its selected check for direct work.

###### Parameters

###### input

[`AuthorizedSpawnContext`](runtime.md#authorizedspawncontext)

###### Returns

[`DeliverableSpec`](runtime.md#deliverablespec)\<`unknown`\> \| `undefined`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`resolveDeliverable`](runtime.md#resolvedeliverable-1)

##### registry?

> `readonly` `optional` **registry?**: [`SuperviseRegistry`](runtime.md#superviseregistry)

Name→value tables for the four code-valued options, so a recorded run configuration can name
 them instead of carrying closures. See [SuperviseRegistry](runtime.md#superviseregistry).

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`registry`](runtime.md#registry-3)

##### coordination?

> `readonly` `optional` **coordination?**: [`CoordinationTransportOptions`](runtime.md#coordinationtransportoptions)

Where the coordination MCP binds when the supervisor is harness-driven. Omit = an ephemeral
 port on `127.0.0.1`, which an off-host root cannot reach. A non-loopback host is refused
 unless authentication is configured; provider managers also need a reachable public URL.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`coordination`](runtime.md#coordination-1)

##### peerMail?

> `readonly` `optional` **peerMail?**: `boolean` \| \{ `limits?`: `Partial`\<[`PeerMailLimits`](runtime.md#peermaillimits)\>; \}

OPT-IN peer mail for the run's workers: sibling-to-sibling `send_mail` / `read_mail`, bounded
 and audited (`CoordinationToolsOptions.peerMail`). The runtime mints one capability URL per
 spawn, serves the mail listener beside the coordination MCP, and hands each worker its
 endpoint on [WorkerSpawnContext.peerMailUrl](runtime.md#peermailurl).

 On the backend-derived worker path the runtime also MOUNTS that endpoint, the way a driver
 receives its coordination MCP: out of band on the bridge's `runtime_attachments`, so the
 authored profile digest never moves, and inside the leaf factory, so `authorizeSpawn` has
 already decided the profile. A `bridge` worker therefore calls `send_mail` / `read_mail` as
 native tools. `router`, `router-tools` and `provider` workers run no MCP client, so the URL
 stays the caller's to use; every other backend refuses the spawn rather than mint a
 capability it can never reach. A caller-owned `makeWorkerAgent` owns its own mount.

 Requires a harness-brained supervisor; a router-brained supervisor is refused rather than
 silently unmailed.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`peerMail`](runtime.md#peermail-1)

##### makeWorkerAgent?

> `readonly` `optional` **makeWorkerAgent?**: [`MakeWorkerAgent`](runtime.md#makeworkeragent)

Override the worker seam directly (tests / advanced) instead of deriving it from `backend`.
 This is caller-owned execution: profile security, spawn authorization, and recursive-driver
 selection below apply only to the backend-derived worker path. `authorizeMessage` still
 governs continuations sent through Runtime's coordination tools.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`makeWorkerAgent`](runtime.md#makeworkeragent-1)

##### makeLeafAgent?

> `readonly` `optional` **makeLeafAgent?**: [`MakeWorkerAgent`](runtime.md#makeworkeragent)

Override ONLY how an authorized LEAF executes, keeping the whole backend-derived path —
 profile security, spawn authorization, recursive-driver selection, nested supervisors — in
 force. Unlike `makeWorkerAgent`, which replaces that path, this slots inside it: the kernel
 authorizes and classifies every spawn, and a child that is NOT a driver runs through this
 factory instead of `backend`. A child that IS a driver still becomes a nested supervisor, whose
 own leaves use this same factory. Composes with `authorizeSpawn`; `backend` is then optional.
 This is the seam an offline test or a pinning layer (an agent graph) should use.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`makeLeafAgent`](runtime.md#makeleafagent-1)

##### driverBackend?

> `readonly` `optional` **driverBackend?**: [`ExecutorConfig`](runtime.md#executorconfig)

Run harness-brained supervisors here. Automatic execution supports a local `bridge`, or a
provider advertising runtime MCP attachments with authenticated `coordination.publicUrl`.
 Defaults to `backend`; separate it when managers and workers use different services.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`driverBackend`](runtime.md#driverbackend-1)

##### profileSecurity?

> `readonly` `optional` **profileSecurity?**: `AgentProfileSecurityPolicy`

Security policy applied to every manager-authored child profile before budget reservation.
 The default blocks local and remote MCP, hooks, and connection grants. Pass an explicit
 allowlist to grant remote MCP hosts or other author-controlled capabilities.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`profileSecurity`](runtime.md#profilesecurity-1)

##### authorizeSpawn?

> `readonly` `optional` **authorizeSpawn?**: (`input`) => [`AuthorizedSpawn`](runtime.md#authorizedspawn)

Product authority over one complete manager-authored spawn. The callback sees the detached,
 immutable profile, task, budget, label, and key together, so approving a profile cannot
 authorize a different task. Return the exact allowed profile (which may be narrowed) plus
 trusted candidate/pursuit attribution, or throw to refuse the whole spawn before reservation.

###### Parameters

###### input

###### profile

`AgentProfile`

###### parent

`AgentProfile`

###### parentIdentity

[`NodeExecutionIdentity`](runtime.md#nodeexecutionidentity)

Trusted identity of the manager authorizing this exact child.

###### parentNodeId

`string`

Concrete manager node; never accepted from model-authored tool arguments.

###### assignmentId

`string`

Stable manager-scoped assignment, including deterministic unkeyed siblings.

###### task

`unknown`

###### budget

[`Budget`](runtime.md#budget-18)

###### label

`string`

###### key?

`string`

###### depth

`number`

###### analyst?

`string`

Present (as the analyst id) only when the runtime's analyst-on-settle hook initiated this
 spawn — authored by the runtime, never accepted from a driver's tool arguments. A node-pinning
 authority reads it to admit the analyst node it would refuse as a driver-authored spawn.

###### continuity?

[`ContinuityMode`](runtime.md#continuitymode)

The EFFECTIVE continuity of this spawn, resolved by the coordination layer.

###### Returns

[`AuthorizedSpawn`](runtime.md#authorizedspawn)

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`authorizeSpawn`](runtime.md#authorizespawn-1)

##### authorizeMessage?

> `readonly` `optional` **authorizeMessage?**: (`input`) => [`AuthorizedDownMessage`](runtime.md#authorizeddownmessage)

Product authority over every continuation sent to a live child. When spawn authorization is
enabled, omitting this refuses steer/answer instructions instead of silently extending the
authorized task. The exact worker identity and detached bytes are recorded before delivery.

###### Parameters

###### input

[`DownMessageAuthorizationInput`](runtime.md#downmessageauthorizationinput) & `object`

###### Returns

[`AuthorizedDownMessage`](runtime.md#authorizeddownmessage)

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`authorizeMessage`](runtime.md#authorizemessage-1)

##### router?

> `readonly` `optional` **router?**: [`RouterTransportConfig`](runtime.md#routertransportconfig)

The supervisor's router substrate (`profile.harness` omitted or `cli-base`). The profile's
 model wins.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`router`](runtime.md#router-5)

##### rootDriverFromBackend?

> `readonly` `optional` **rootDriverFromBackend?**: `boolean`

When `driverBackend` is absent, whether an external-harness ROOT may default to running on
 `backend` (where workers run). `true` (default) keeps the convenience every direct caller has.
 A layer that gives `backend` a narrower meaning — `runGraph`, where it places WORKER nodes only
 — sets `false`, so an external root without an explicit `driverBackend` is refused before any
 compute rather than silently driven from the worker placement.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`rootDriverFromBackend`](runtime.md#rootdriverfrombackend)

##### resolveSpawnProfile?

> `readonly` `optional` **resolveSpawnProfile?**: (`profile`) => `AgentProfile`

Pre-journal profile resolution for the spawn pre-flight: the profile a driver authored →
 the profile that will run (`CoordinationToolsOptions.resolveSpawnProfile`). A pinning layer
 sets this alongside `authorizeSpawn` so the backend gate and the authorization see the same
 canonical profile. Identity-free and synchronous; throw to refuse.

###### Parameters

###### profile

`AgentProfile`

###### Returns

`AgentProfile`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`resolveSpawnProfile`](runtime.md#resolvespawnprofile)

##### driveHarness?

> `readonly` `optional` **driveHarness?**: [`DriveHarness`](runtime.md#driveharness-2)

Run an external-harness supervisor explicitly. Required for a remote sandbox; optional as a
 caller-owned override for a local bridge.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`driveHarness`](runtime.md#driveharness-1)

##### driverRetry?

> `readonly` `optional` **driverRetry?**: [`DriverRetryPolicy`](runtime.md#driverretrypolicy)

How hard a transiently-failed EXTERNAL driver is re-entered before the run ends
`driver-failed`. A harness process SIGKILLed at a bridge timeout, a stream cut mid-turn, or an
upstream 5xx used to end a run of arbitrary length while its budget and deadline sat almost
untouched (#741). A retry re-enters the driver over the SAME scope, coordination server, and
live children; the bridge backend reattaches the harness session by its durable execution id.

Runtime's own refusals (a validation guard, an exhausted budget, an abort, a client-side
transport status) are never retried — they were decisions. Retries stop at the budget, the
deadline, an abort, or a run of attempts that changed nothing at all.

Omit = retry under the defaults. `{ enabled: false }` = the historical behavior where the first
driver failure ends the run. Applies to the root manager and every recursive manager under it.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`driverRetry`](runtime.md#driverretry-1)

##### onDriverAttempt?

> `readonly` `optional` **onDriverAttempt?**: (`record`) => `void` \| `Promise`\<`void`\>

Per-attempt record for every external driver in the tree — what makes "failed after N
 attempts, last cause X" visible instead of one backend's last words.

###### Parameters

###### record

[`DriverAttemptRecord`](runtime.md#driverattemptrecord)

###### Returns

`void` \| `Promise`\<`void`\>

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`onDriverAttempt`](runtime.md#ondriverattempt-1)

##### workerRetry?

> `readonly` `optional` **workerRetry?**: [`WorkerSpawnRetryPolicy`](runtime.md#workerspawnretrypolicy)

How a BACKEND-DERIVED WORKER whose spawn was refused before it ran is re-entered, instead of
settling dead with a slot free seconds later.

`driverRetry` guards the root only. A worker that dies is typed into a `down` settlement,
which is the right shape when the worker RAN — and the wrong shape for
`host-executor: acquire timeout after 60000ms (in_flight=4/4, queued=1)`, a queue refusal the
bridge emits before any harness child exists. Measured 2026-08-22 on discovery-lab cells
oscnp s2/s3: ten live agents on one bridge that admits four, and every worker refused at the
60 s acquire deadline was lost for the whole run.

Fail-closed on two proofs that the attempt did no work: the error carries a pre-spawn
signature, AND the attempt yielded no execution event. An attempt that streamed anything may
have metered usage, so a blind re-run would double-spend and stays fatal.

Omit = no retry, the historical behaviour. Applies to backend-derived leaves, including those
a `makeLeafAgent` builds; a caller-owned `makeWorkerAgent` composes
[withWorkerSpawnRetry](runtime.md#withworkerspawnretry) itself.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`workerRetry`](runtime.md#workerretry-1)

##### onWorkerRetry?

> `readonly` `optional` **onWorkerRetry?**: (`attempt`) => `void`

Per-re-entry record for every retried worker spawn — what makes a saturated executor visible
 as waiting rather than as a worker that silently took longer.

###### Parameters

###### attempt

[`WorkerSpawnRetryAttempt`](runtime.md#workerspawnretryattempt)

###### Returns

`void`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`onWorkerRetry`](runtime.md#onworkerretry-1)

##### repromptOnUnmet?

> `readonly` `optional` **repromptOnUnmet?**: `number`

How many times an EXTERNAL-harness driver that RETURNED with `deliverable` still unmet is
re-entered on the SAME live session with the unmet items.

A harness owns its own turn loop, so it decides when it is finished — and it can decide that
while the run has produced nothing. Measured on discovery-lab (2026-09-01, n = 1,422 settled
runs): 376 of 376 winning runs ended on the driver's own completion, and the completion gate
could only LABEL an undelivered result `valid:false`, never send the driver back for it.

A re-prompt is the retry path, not a second loop: same scope, same coordination server, same
live children, and the same budget, deadline, abort, and `driverRetry.maxAttempts` bounds. A
run the coordination server already stopped is never re-prompted — that stop was a decision.

Requires `deliverable`, and applies to every external manager with a completion check. A
recursive manager receives the check selected for its exact assignment. Refused for a
router-brained manager, which runs its turn loop in process. Omit/`0` = never.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`repromptOnUnmet`](runtime.md#repromptonunmet-1)

##### onUnmetContract?

> `readonly` `optional` **onUnmetContract?**: [`OnUnmetContract`](runtime.md#onunmetcontract)

Compose the re-entry instruction for an unmet contract, or return `'stop'` to end the run.
 Requires `repromptOnUnmet >= 1`. Omit = Runtime's own instruction, which names what the run
 owes and reports how many workers passed the check.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`onUnmetContract`](runtime.md#onunmetcontract-3)

##### childSettleGraceMs?

> `readonly` `optional` **childSettleGraceMs?**: `number` \| `null`

How long live children may keep running after the root driver returns or fails, before the join
barrier cascades the abort into them. `null` waits until children settle or the caller cancels.
An explicit run deadline always wins. Omit/`0` = immediate teardown.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`childSettleGraceMs`](runtime.md#childsettlegracems-1)

##### resolveDriveHarness?

> `readonly` `optional` **resolveDriveHarness?**: [`ResolveDriveHarness`](runtime.md#resolvedriveharness-2)

Resolve one custom external-harness session per trusted manager identity. Use this instead of
`driveHarness` when recursive managers must be independently steerable.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`resolveDriveHarness`](runtime.md#resolvedriveharness-1)

##### driveHarnessMaterialization?

> `readonly` `optional` **driveHarnessMaterialization?**: [`ProfileMaterializationContract`](agent.md#profilematerializationcontract)

Required with a custom `driveHarness` or `resolveDriveHarness`: declares which complete
AgentProfile axes that path really applies. Built-in bridge driving supplies its own
full-profile contract.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`driveHarnessMaterialization`](runtime.md#driveharnessmaterialization-1)

##### resolveSupervisorTools?

> `readonly` `optional` **resolveSupervisorTools?**: [`ResolveSupervisorTools`](runtime.md#resolvesupervisortools-2)

Resolve product-owned tools from the exact trusted manager context. The same descriptors and
handlers are bound to router and external-harness managers; resolution happens once per node.
Each handler receives that manager scope's live cancellation signal in its trusted invocation
context, including recursive parent and root cascades, plus `context.verbs` — that manager's
own coordination verbs, callable in code so a product tool can COMPOSE its children (fan out,
chain, join, retry) in one tool call instead of one model turn per verb. Every verb crosses
the same authorizeSpawn / security / allowedModels gate, pool reservation, `maxLiveWorkers`
cap, journal, and bus the MCP verb crosses, at every depth and on both arms.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`resolveSupervisorTools`](runtime.md#resolvesupervisortools-1)

##### escalateQuestion?

> `readonly` `optional` **escalateQuestion?**: [`EscalateQuestion`](runtime.md#escalatequestion)

Where an `ask_parent` question goes when it leaves a manager (see [EscalateQuestion](runtime.md#escalatequestion)).

Installed on EVERY manager of the run, at every depth, so a driver's escalation reaches the
product's own inbox — a UI, an operator queue, a human. Omit and every manager reports
`outcome: 'no-parent'` on `ask_parent`, which is the honest reading when nothing above it is
listening: the runtime routes no question to a parent by itself.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`escalateQuestion`](runtime.md#escalatequestion-2)

##### onCoordinationEvent?

> `readonly` `optional` **onCoordinationEvent?**: (`context`, `eventId`, `record`) => `void` \| `Promise`\<`void`\>

Awaited product transaction hook for every coordination record. `eventId` is stable across a
lost acknowledgement and durable restart; the record is not pull-visible until this commits.

###### Parameters

###### context

[`SupervisorNodeContext`](runtime.md#supervisornodecontext)

###### eventId

`` `sha256:${string}` ``

###### record

[`BusRecord`](runtime.md#busrecord)\<[`CoordinationEvent`](runtime.md#coordinationevent)\>

###### Returns

`void` \| `Promise`\<`void`\>

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`onCoordinationEvent`](runtime.md#oncoordinationevent)

##### extraTools?

> `readonly` `optional` **extraTools?**: readonly `object`[]

WORK tools the supervisor may call DIRECTLY — so a recursive atom can ACT (do simple work
 itself) OR SPAWN (delegate when it needs parallelism), not be a pure manager. Pair with
 `executeExtraTool`. Router arm only (`profile.harness` omitted or `cli-base`).

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`extraTools`](runtime.md#extratools-1)

##### executeExtraTool?

> `readonly` `optional` **executeExtraTool?**: (`name`, `args`) => `Promise`\<`string` \| `null` \| `undefined`\>

Runs an `extraTools` call; null/undefined falls through to the coordination dispatch.

###### Parameters

###### name

`string`

###### args

`Record`\<`string`, `unknown`\>

###### Returns

`Promise`\<`string` \| `null` \| `undefined`\>

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`executeExtraTool`](runtime.md#executeextratool-1)

##### perWorker?

> `readonly` `optional` **perWorker?**: [`Budget`](runtime.md#budget-18)

Per-child budget reserved on each spawn. Defaults to a quarter of the pool's tokens.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`perWorker`](runtime.md#perworker-1)

##### maxLiveWorkers?

> `readonly` `optional` **maxLiveWorkers?**: `number`

Hard cap on simultaneously executing spawned workers across the WHOLE recursive tree. The
 root is excluded; nested drivers and leaves share one allocation, so recursion cannot multiply
 the cap. Omit/`<= 0` = no cap (the conserved pool stays the only bound).

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`maxLiveWorkers`](runtime.md#maxliveworkers-5)

##### analysts?

> `readonly` `optional` **analysts?**: `string` \| [`AnalystRegistry`](runtime.md#analystregistry)

Analyst lenses available to the driver. Required for `analyzeOnSettle`. Unset → status quo
 (the driver receives settled worker outputs, no analyst findings). A `string` names an entry in
 `registry.analysts`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`analysts`](runtime.md#analysts-3)

##### analyzeOnSettle?

> `readonly` `optional` **analyzeOnSettle?**: readonly (`string` \| [`AnalyzeOnSettleRoute`](runtime.md#analyzeonsettleroute))[]

Analyst kind ids run AUTOMATICALLY when a worker settles `done` — each re-enters as a `finding`
 the driver pulls (`await_event`) and composes its next steer from. The self-improving UP-leg,
 threaded to the driver at this level (propagate to sub-drivers via a recursive `makeWorkerAgent`).
 Omit/empty = status quo (no analyst feed). Requires `analysts`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`analyzeOnSettle`](runtime.md#analyzeonsettle)

##### watchWorkers?

> `readonly` `optional` **watchWorkers?**: [`WorkerWatchOptions`](runtime.md#workerwatchoptions)

Watch every worker's LIVE tool trace with the online detector panel and raise a `finding` the
moment one loops or error-storms — so the supervisor learns it mid-run (via `await_event`)
instead of at settle. Pairs with a steerable worker: the finding is the evidence, `steer_agent`
is the correction. Requires a backend whose executor exposes a trace source (the steerable
sandbox worker and the pi wrapper do); other runtimes are simply not watched.

Omit = off (status quo — no online watching, no extra events).

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`watchWorkers`](runtime.md#watchworkers-1)

##### stallAfterMs?

> `readonly` `optional` **stallAfterMs?**: `number`

Idle time after which `observe_agent` reports a running worker as `stalled`. A derived read
 at observation time — nothing is killed or retried. Omit = the runtime default.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`stallAfterMs`](runtime.md#stallafterms-3)

##### continuityByProfile?

> `readonly` `optional` **continuityByProfile?**: `Readonly`\<`Record`\<`string`, [`ContinuityMode`](runtime.md#continuitymode)\>\>

Default continuity per worker PROFILE NAME: `'resume'` makes each spawn of that name after
 the first re-attach to the node's most recent SETTLED worker — a NEW live worker whose spawn
 context carries the prior worker's identity (`WorkerSpawnContext.resume`), which the executor
 seam re-attaches with. `spawn_worker`'s per-call `continuity` argument overrides in either
 direction; `runGraph` derives this from delegates-edge `continuity`. Omit = every spawn is
 `'fresh'` (status quo). See `CoordinationToolsOptions.continuityByProfile` for the
 refusal semantics (no-prior / while-live / with-key) and the process-local resume boundary.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`continuityByProfile`](runtime.md#continuitybyprofile)

##### blobs?

> `readonly` `optional` **blobs?**: [`ResultBlobStore`](runtime.md#resultblobstore)

Worker output store. Defaults to in-memory.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`blobs`](runtime.md#blobs-5)

##### journal?

> `readonly` `optional` **journal?**: [`SpawnJournal`](runtime.md#spawnjournal)

Override the spawn journal directly (advanced; `runDir` is the ordinary durable path). Pair
 with `blobs` — a journal whose result payloads live in a different store cannot replay.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`journal`](runtime.md#journal-4)

##### probes?

> `readonly` `optional` **probes?**: `string` \| [`WaitProbeRegistry`](runtime.md#waitproberegistry)

Predicate registry for `poll` wait-states (`Scope.wait`). A `poll` names its predicate so the
 wait survives a restart; this is what the name resolves against. Unset ⇒ `poll` waits are
 refused `unknown-probe` and `timer` waits still work. A `string` names an entry in
 `registry.probes`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`probes`](runtime.md#probes-3)

##### stopRule?

> `readonly` `optional` **stopRule?**: [`StopRule`](runtime.md#stoprule-1)

PROGRESS-derived stop rule (BOTH arms). Ends a run that has stopped LEARNING before it
exhausts a ceiling — the answer to "a run should end because it is done or stuck, not because
it ran out". It composes with the budget guards and can never override one.

The evaluation boundary differs by arm because the loop does: a router-brained supervisor is
evaluated before each of its own inference turns; a harness-brained supervisor is evaluated on
each worker settle, and a stop aborts its stop signal so the harness ends at its next turn
boundary. Both arms fold the same settled ledger through the same evaluator.

Build it from `supervise/stop-rules`: `plateau({window, minDelta})`,
`noProgressFor({ms, settles})`, `allWorkersStalled({...})`, combined with `anyOf`/`allOf`. The
thresholds are policy and stay with you; the enforcement lives in the runtime. Omit = ceilings
only (unchanged behavior).

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`stopRule`](runtime.md#stoprule-2)

##### onProgressStop?

> `readonly` `optional` **onProgressStop?**: (`reason`) => `void`

One-shot notification of WHY a `stopRule` ended the run (BOTH arms) — so a caller records the
 reason instead of inferring an early stop from an unexhausted budget.

###### Parameters

###### reason

`string`

###### Returns

`void`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`onProgressStop`](runtime.md#onprogressstop-1)

##### maxDepth?

> `readonly` `optional` **maxDepth?**: `number`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`maxDepth`](runtime.md#maxdepth-3)

##### maxTurns?

> `readonly` `optional` **maxTurns?**: `number`

Turn cap for the supervisor's OWN loop (BOTH arms). Router arm: inference turns of the
 driver's tool loop. Harness arm: turns the harness reports, counted off its `iteration`
 stream — reaching the cap aborts the stop signal, so the harness ends at its next turn
 boundary rather than mid-request. `0` lifts the cap on both arms and leaves the conserved
 pool, the deadline, and abort as the bounds; a negative value is refused. Omit = the router
 arm's default cap, and no turn cap on the harness arm.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`maxTurns`](runtime.md#maxturns-2)

##### compaction?

> `readonly` `optional` **compaction?**: [`ToolLoopCompactionOptions`](runtime.md#toolloopcompactionoptions)

Give the supervisor brain a chapter-lifecycle on its OWN context window (ROUTER ARM ONLY —
 a harness owns its own context window and its own compaction, so this is refused for a
 harness-brained supervisor rather than silently ignored): once its coordination transcript
 exceeds `thresholdTokens` it distills to a compact progress note and continues, instead of
 re-billing the whole transcript every turn (the cost that makes the LLM-brain front door lose
 to a dumb-Ralph respawn). The live `Scope` roster is the durable state across chapters.
 Default off. `distill` defaults to a brain self-summary + the settled-worker roster.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`compaction`](runtime.md#compaction-1)

##### runId?

> `readonly` `optional` **runId?**: `string`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`runId`](runtime.md#runid-19)

##### now?

> `readonly` `optional` **now?**: () => `number`

###### Returns

`number`

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`now`](runtime.md#now-16)

##### allowedModels?

> `readonly` `optional` **allowedModels?**: readonly `string`[]

Restrict the run to this subset of models. When set, every configured model — the
 supervisor router model, the profile's model, and the backend's model — must be a member,
 or `supervise()` throws a `ConfigError` before any compute is spent. Unset = unrestricted.

 This is a MODEL-ID filter, not a route filter. The compared values are the bare ids a profile
 declares — `model.default`, `model.small`, `subagents[].model`, `modes[].model`. The composed
 wire id (`harness/provider/model`) is never built here and never compared, so an entry written
 in qualified form matches nothing, and a child that names an allowed id is admitted whatever
 harness and provider its own profile declares. Pin the route with `authorizeSpawn`: it reads
 the authored child profile and may refuse the spawn before any reservation.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`allowedModels`](runtime.md#allowedmodels-2)

##### finalizer?

> `readonly` `optional` **finalizer?**: `string` \| [`SupervisorFinalizer`](runtime.md#supervisorfinalizer)

How the settled-worker ledger becomes the run's output. Default `bestDelivered` — the single
 highest-scoring DELIVERED child (the exact behavior every existing caller had). Alternatives:
 `collectDelivered` (every verified distinct output with provenance — a Pareto set / recorded
 disagreement) or a custom `SupervisorFinalizer`. Whatever the finalizer, it operates on
 structurally DELIVERED outputs only — an undelivered or invalid child stays ineligible. A
 `string` names an entry in `registry.finalizers`.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`finalizer`](runtime.md#finalizer-1)

##### hooks?

> `readonly` `optional` **hooks?**: [`RuntimeHooks`](index.md#runtimehooks)

Lifecycle observers for the whole recursive tree (`Scope` re-seeds them into every nested
 scope). Composed with the `otel` recorder below when both are set. Omit = no observers, which
 is the behavior every existing caller has.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`hooks`](runtime.md#hooks-8)

##### otel?

> `readonly` `optional` **otel?**: `Omit`\<[`SupervisorSpanOptions`](runtime.md#supervisorspanoptions), `"runId"` \| `"now"`\>

OPT-IN OTLP tracing: emit one span per supervised node (opened at spawn, closed at settle,
parented to its parent node's span) plus an `LLM` child span per metered driver turn, so the
tree is readable by any trace viewer instead of only by a journal parser. See `otel-spans.ts`.

Omit and the run emits nothing, allocates no recorder, and installs no hook — telemetry is
never a default. Present with no reachable endpoint (no `exportConfig.endpoint` and no
`OTEL_EXPORTER_OTLP_ENDPOINT`) is also a no-op. The spawn journal is untouched either way:
spans are telemetry, never the replay/resume record.

###### Inherited from

[`SuperviseOptions`](runtime.md#superviseoptions).[`otel`](runtime.md#otel-1)

***

### SupervisedPursuitResult

#### Type Parameters

##### Result

`Result`

#### Properties

##### result

> `readonly` **result**: `Result`

##### pursuit

> `readonly` **pursuit**: [`PursuitProjection`](#pursuitprojection)

##### observerPath

> `readonly` **observerPath**: `string`

##### settlePath

> `readonly` **settlePath**: `string`

`runDir/result.json`: `result` as canonical JSON, written once at settle.

***

### DurableCoordinationStreamIdentity

#### Properties

##### runId

> `readonly` **runId**: `string`

##### ownerIds

> `readonly` **ownerIds**: readonly `string`[]

Exact owner ids present in the side-log, sorted for deterministic display.

##### unscopedRecords

> `readonly` **unscopedRecords**: `number`

Records written before owner-scoped coordination identities were introduced.

##### recordCount

> `readonly` **recordCount**: `number`

***

### DurableSupervisionDiscovery

Identities discoverable from one `supervise({ runDir })` directory without
already knowing the root node or coordination run id stored inside it.

#### Properties

##### runDir

> `readonly` **runDir**: `string`

##### spawnJournalPath

> `readonly` **spawnJournalPath**: `string`

##### coordinationLogPath

> `readonly` **coordinationLogPath**: `string`

##### roots

> `readonly` **roots**: readonly `string`[]

##### rootsBegunAt

> `readonly` **rootsBegunAt**: readonly (`string` \| `null`)[]

`at` from each top-level root's `begin` record, index-aligned with `roots`.

##### coordinationStreams

> `readonly` **coordinationStreams**: readonly [`DurableCoordinationStreamIdentity`](#durablecoordinationstreamidentity)[]

## Type Aliases

### ObserverRecordKind

> **ObserverRecordKind** = `"event"` \| `"decision"`

***

### PursuitStatus

> **PursuitStatus** = `"running"` \| `"done"` \| `"down"`

One settled projection status, shared by runs and nodes. `down` is the journal's own word for a
failure (a settlement is journaled as `kind: 'down'`, cancellation included), so a consumer can
join run rows to node rows on `status` and read one failure population instead of two.

***

### PursuitCostProvenance

> **PursuitCostProvenance** = `"reported"` \| `"estimated"` \| `"partial"` \| `"unknown"`

Where a node's dollar figure came from. `reported` = a provider billed all of it; `estimated` =
a model catalog priced all of it; `partial` = a provider billed part and a catalog priced the
rest; `unknown` = nothing priced it, so `usd` is a floor and never the cost.

***

### PursuitNodePlacement

> **PursuitNodePlacement** = `Readonly`\<`Record`\<`string`, `string` \| `number` \| `boolean` \| `null`\>\>

Where and how a node's execution was placed, read off its execution-binding receipt.

## Variables

### RUN\_DIRECTORY\_LOCK\_FILE

> `const` **RUN\_DIRECTORY\_LOCK\_FILE**: `"supervise.lock"` = `'supervise.lock'`

The lock file `supervisePursuit` holds inside a run directory for the life of one call.

***

### SETTLE\_RECORD\_FILE

> `const` **SETTLE\_RECORD\_FILE**: `"result.json"` = `'result.json'`

The settle record: the returned `SupervisedResult` as canonical JSON, written once.

***

### FAILURE\_RECORD\_FILE

> `const` **FAILURE\_RECORD\_FILE**: `"failure.json"` = `'failure.json'`

The failure record: the most recent throw, replaced by a later throw.

## Functions

### handleChatTurn()

> **handleChatTurn**(`input`): [`ChatTurnResult`](#chatturnresult)

Run one chat turn. Returns immediately with a `ReadableStream` body;
execution starts while the stream is constructed. Backend
failures surface as `error` + `session.run.failed` events.

#### Parameters

##### input

[`RunChatTurnInput`](#runchatturninput)

#### Returns

[`ChatTurnResult`](#chatturnresult)

***

### deriveExecutionId()

> **deriveExecutionId**(`input`): `string`

Derive a stable execution id from the run identity.
The same `(projectId, sessionId, turnIndex)` tuple yields the same id.

Use the result as both `PromptOptions.executionId` and
`PromptOptions.turnId` on the first dispatch.
The execution id addresses the server-side execution for reconnect and
replay; the turn id makes a repeated dispatch idempotent.
An execution id alone does not make a repeated POST idempotent.

Format is readable, not hashed: operators grepping orchestrator logs
for `gtm-agent:thread-abc:3` find the run without translating an
opaque id. Components are URL-encoded so delimiters inside caller ids
cannot collapse distinct tuples. The final id is limited to the
orchestrator replay route's 256-byte maximum. Execution ids are not a
secrecy boundary.

Wire integration:
  - Initial dispatch: pass the result as `executionId` and `turnId`.
  - Stream replay: pass it as `executionId` with `lastEventId`.

#### Parameters

##### input

###### projectId

`string`

###### sessionId

`string`

###### turnIndex

`number`

#### Returns

`string`

#### Throws

`TypeError` when either string id is blank.

#### Throws

`RangeError` when `turnIndex` is invalid or the result exceeds 256 bytes.

***

### verifyObserverRecords()

> **verifyObserverRecords**(`records`, `pursuitId?`): readonly [`ObserverRecord`](#observerrecord)[]

Verify identity, monotonic sequence, payload shape, and the complete digest chain.

#### Parameters

##### records

readonly [`ObserverRecord`](#observerrecord)[]

##### pursuitId?

`string`

#### Returns

readonly [`ObserverRecord`](#observerrecord)[]

***

### observerRecordDigest()

> **observerRecordDigest**(`record`): `string`

Compute the canonical SHA-256 digest for an unsigned observer record.

#### Parameters

##### record

`Omit`\<[`ObserverRecord`](#observerrecord), `"digest"`\>

#### Returns

`string`

***

### createFileObserverHooks()

> **createFileObserverHooks**(`path`, `pursuitId`): `object`

Build the canonical durable observer hook in one call.

#### Parameters

##### path

`string`

##### pursuitId

`string`

#### Returns

`object`

##### journal

> `readonly` **journal**: [`FileObserverJournal`](#fileobserverjournal)

##### hooks

> `readonly` **hooks**: [`RuntimeHooks`](index.md#runtimehooks)

***

### projectPursuit()

> **projectPursuit**(`records`): [`PursuitProjection`](#pursuitprojection)

Fold one append-only execution journal into a deterministic operator projection.

This is intentionally a READ model, not another state machine: it does not own
execution, cannot steer agents, and can be rebuilt from the journal at any time.
Projection verifies the complete hash chain first, so an operator view can never
silently render a mutated or reordered observer history as trustworthy state.

Topology comes only from Runtime's canonical `agent.spawn` facts. Terminal node
state comes only from `agent.child`; concrete run state comes only from the root
`agent.run` lifecycle emitted by `supervisePursuit`, one row per attempt. Node identity is
scoped to the concrete Runtime run so independent trees may both contain `root:s0` without
aliasing, and a node belongs to the attempt that spawned it.

Usage, cost and timing are reported at the class the runtime measured them at. A missing
class stays ABSENT and the run names the node in `spendGaps`; nothing here converts an
unmeasured channel into a zero, because a fabricated zero is indistinguishable from free work.

#### Parameters

##### records

readonly [`ObserverRecord`](#observerrecord)[]

#### Returns

[`PursuitProjection`](#pursuitprojection)

***

### acquireRunDirectoryLock()

> **acquireRunDirectoryLock**(`runDir`, `runId`, `now?`): `Promise`\<[`RunDirectoryLock`](#rundirectorylock)\>

Take `runDir/supervise.lock`, or refuse.

The file is published with its full content or not at all, so a contender never reads a
half-written holder. A lock whose holder is gone (its pid no longer exists, or the pid now
belongs to a process with a different start token) is stale and is removed under the mutation guard;
a pid this process may not signal (`EPERM`) is alive and refuses. An empty file names no
holder and is reclaimed. A file with unreadable content is left in place and refused:
reclaiming it could evict a live holder written by something other than this module.

#### Parameters

##### runDir

`string`

##### runId

`string`

##### now?

() => `number`

#### Returns

`Promise`\<[`RunDirectoryLock`](#rundirectorylock)\>

***

### readRunDirectoryLock()

> **readRunDirectoryLock**(`runDir`): `Promise`\<[`RunDirectoryLockHolder`](#rundirectorylockholder) \| `undefined`\>

Read the holder a lock file names, or `undefined` when no lock file names one.

#### Parameters

##### runDir

`string`

#### Returns

`Promise`\<[`RunDirectoryLockHolder`](#rundirectorylockholder) \| `undefined`\>

***

### runDirectoryHolderIsLive()

> **runDirectoryHolderIsLive**(`runDir`): `Promise`\<[`RunDirectoryHolderLiveness`](#rundirectoryholderliveness)\>

Whether a run directory is still held by the live process that took its lock.

The same rule `acquireRunDirectoryLock` applies to decide whether a lock is stale, exposed so a
caller — a supervisor picking up an abandoned directory, an operator tool listing runs — asks
the question instead of hand-rolling `process.kill(pid, 0)`. A bare signal probe cannot tell a
live holder from an unrelated process that later took the same pid, which is the failure this
lock's start token exists to prevent.

#### Parameters

##### runDir

`string`

#### Returns

`Promise`\<[`RunDirectoryHolderLiveness`](#rundirectoryholderliveness)\>

***

### settleRecordJson()

> **settleRecordJson**(`result`): `string`

The exact bytes `result.json` holds for a result: its JSON value serialized as RFC 8785
canonical JSON. Throws `UnrecordableSettleValueError` before any byte is written when the
result carries a value JSON would misstate.

#### Parameters

##### result

`unknown`

#### Returns

`string`

***

### readSettleRecord()

> **readSettleRecord**(`runDir`): `Promise`\<[`SupervisedResult`](runtime.md#supervisedresult)\<`unknown`\> \| `undefined`\>

Read the settle record a run directory holds, or `undefined` when it holds none. A file that
is present but is not a settle record is corruption and fails loud.

#### Parameters

##### runDir

`string`

#### Returns

`Promise`\<[`SupervisedResult`](runtime.md#supervisedresult)\<`unknown`\> \| `undefined`\>

***

### readFailureRecord()

> **readFailureRecord**(`runDir`): `Promise`\<[`DurableFailureRecord`](#durablefailurerecord) \| `undefined`\>

Read the most recent failure record, or `undefined` when the directory holds none.

#### Parameters

##### runDir

`string`

#### Returns

`Promise`\<[`DurableFailureRecord`](#durablefailurerecord) \| `undefined`\>

***

### supervisePursuit()

> **supervisePursuit**(`profile`, `task`, `opts`): `Promise`\<[`SupervisedPursuitResult`](#supervisedpursuitresult)\<\{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error?`: `undefined`; `reason`: `"aborted"` \| `"all-children-down"` \| `"budget-exhausted"`; \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error?`: `undefined`; `reason`: `"cancelled"`; `source`: `string`; `cancellationReason`: `string`; `operationId?`: `string`; \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `reason`: `"driver-failed"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error`: [`NoWinnerError`](runtime.md#nowinnererror); \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"winner"`; `out`: `unknown`; `outRef`: `string`; `verdict?`: `DefaultVerdict`; `tree`: [`TreeView`](runtime.md#treeview); `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `spentBreakdown?`: \{ `driverInference`: [`Spend`](runtime.md#spend); `childWork`: [`Spend`](runtime.md#spend); \}; \}\>\>

One-call durable pursuit execution over the canonical `supervise()` kernel.

This is an adapter, not a second executor: it composes a durable third-person
observer into Runtime's existing recursive hook stream and then rebuilds the
operator projection after the same `supervise()` call settles. Agents never
receive the observer path or projection and their behavior does not depend on it.

Every concrete execution writes only inside its own `runDir`. Cross-run pursuit
aggregation is therefore lock-free at the observer layer: reuse `pursuitId` across
run directories and let Intelligence join the independently verified projections.

The directory's terminal state is recorded beside `observer.jsonl`: `result.json` holds the
returned result once the run settles and `failure.json` the most recent throw. A directory
whose `result.json` exists refuses re-entry before any compute; a failure record alone does
not, because a caller can correct its input and drive the same run again. For the life of the
call the directory is held by `supervise.lock`, so a second process on the same directory
refuses and names the holder instead of sharing one journal.
An abandoned `supervise.lock.guard` requires removal after confirming no lock mutation is active.

#### Parameters

##### profile

`AgentProfile`

##### task

`unknown`

##### opts

[`SupervisePursuitOptions`](#supervisepursuitoptions)

#### Returns

`Promise`\<[`SupervisedPursuitResult`](#supervisedpursuitresult)\<\{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error?`: `undefined`; `reason`: `"aborted"` \| `"all-children-down"` \| `"budget-exhausted"`; \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error?`: `undefined`; `reason`: `"cancelled"`; `source`: `string`; `cancellationReason`: `string`; `operationId?`: `string`; \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"no-winner"`; `reason`: `"driver-failed"`; `tree`: [`TreeView`](runtime.md#treeview); `downCount`: `number`; `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `leakedReservations?`: readonly [`LeakedReservation`](runtime.md#leakedreservation)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `error`: [`NoWinnerError`](runtime.md#nowinnererror); \} \| \{ `rootProviderModel`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `kind`: `"winner"`; `out`: `unknown`; `outRef`: `string`; `verdict?`: `DefaultVerdict`; `tree`: [`TreeView`](runtime.md#treeview); `spentTotal`: [`Spend`](runtime.md#spend); `providerModel?`: [`ProviderModelExecutionEvidence`](runtime.md#providermodelexecutionevidence); `teardownUnconfirmed?`: readonly [`UnconfirmedTeardown`](runtime.md#unconfirmedteardown)[]; `spendGaps?`: readonly [`SpendGap`](runtime.md#spendgap)[]; `spentBreakdown?`: \{ `driverInference`: [`Spend`](runtime.md#spend); `childWork`: [`Spend`](runtime.md#spend); \}; \}\>\>

***

### discoverDurableSupervisionRun()

> **discoverDurableSupervisionRun**(`runDir`): `Promise`\<[`DurableSupervisionDiscovery`](#durablesupervisiondiscovery)\>

Discover the stable identities recorded by Runtime's durable supervision
files. This is the developer-facing first step before calling
`FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or
`FileCoordinationLog.load(runId, ownerId)`.

Missing files produce empty collections. A malformed committed JSONL record
still fails loud through the same parser used by the runtime; a torn final
append is ignored because it was never acknowledged as committed.

#### Parameters

##### runDir

`string`

#### Returns

`Promise`\<[`DurableSupervisionDiscovery`](#durablesupervisiondiscovery)\>