@tangle-network/agent-runtime 0.116.0 → 0.117.0

package/dist/{environment-provider-CWsRh6Uz.d.ts → environment-provider-CTZjdIUg.d.ts}

@@ -2,7 +2,7 @@ import { d as AgentTaskStatus, o as AgentRuntimeEvent, x as RuntimeStreamEvent }
 import { l as RuntimeHooks } from "./runtime-hooks-sbRpjStq.js";
 import { E as SandboxClient, v as LoopTokenUsage, y as LoopTraceEmitter } from "./types-DnNGJ5Gz.js";
 import { ControlEvalResult, DefaultVerdict, KnowledgeReadinessReport, KnowledgeRequirement, ToolSpan } from "@tangle-network/agent-eval";
-import { AgentProfile as AgentProfile$1, AgentProfileValidationResult } from "@tangle-network/agent-interface";
+import { AgentProfile as AgentProfile$1, AgentProfileValidationResult, Sha256Digest } from "@tangle-network/agent-interface";
 import { BackendType, CreateSandboxOptions, Sandbox } from "@tangle-network/sandbox";
 import { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentCapabilities as AgentEnvironmentCapabilities$1, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentProvider as AgentEnvironmentProvider$1, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentProfileRef as AgentProfileRef$1, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnInput as AgentTurnInput$1, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, CreateAgentEnvironmentInput as CreateAgentEnvironmentInput$1, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "@tangle-network/agent-interface/environment-provider";
 //#region src/runtime/supervise/progress.d.ts
@@ -450,6 +450,26 @@ interface OtelAttribute {
     boolValue?: boolean;
   };
 }
+/**
+ * Create an exporter that APPENDS spans to a local OpenInference-JSONL file, one complete span per
+ * line, instead of posting them to a collector.
+ *
+ * Why this exists beside {@link createOtelExporter}: that one needs an OTLP endpoint, so a run on a
+ * laptop, in CI, or inside a sandbox with no collector emits nothing and its per-turn shape is
+ * simply lost. The journal records the TREE (who spawned whom, what settled, what it spent); it
+ * does not record what happened inside a turn. A run whose tree is readable but whose turns are not
+ * is exactly the state that made an observability gap invisible until someone went looking.
+ *
+ * The line shape is the one `@tangle-network/traces` reads (`spans.otlp.jsonl`) and is a standard
+ * OpenInference representation, so the same file feeds any OpenInference tool with no conversion:
+ * snake_case identity fields, ISO-8601 times, `parent_span_id` empty at the root, and attributes as
+ * a plain object rather than OTLP's key/value array.
+ *
+ * Appends synchronously per span so a killed process keeps every span it had already finished —
+ * matching the spawn journal's durability posture, since a trace that only survives a clean exit is
+ * useless for the runs you most want to look at.
+ */
+declare function createOpenInferenceFileExporter(filePath: string): OtelExporter;
 /**
  * Create an OTEL exporter. Returns undefined when no endpoint is configured.
  */
@@ -675,6 +695,12 @@ interface WaitOpts {
 interface Agent<Task, Out> {
   readonly name: string;
   act(task: Task, scope: Scope<Out>): Promise<Out>;
+  /**
+   * Optional manager inbox. A parent or attached `RootHandle` uses this to deliver the same raw
+   * down-message accepted by executor inboxes. Return `false` when the manager has no live receive
+   * path; returning `true` means the message was accepted for the current manager session.
+   */
+  deliver?(msg: unknown): void | boolean;
 }
 /**
  * The leaf runtime — ONE open interface, not a closed union. `execute` returns a
@@ -687,16 +713,17 @@ interface Agent<Task, Out> {
  * Built-in implementations (in `runtime.ts`, NOT variants here): router/inline (a direct
  * Router/HTTP inference call, no box), sandbox (COMPOSES `runAgentRounds` as a leaf, forwarding
  * PR #150's optional `lineage` passthrough — does NOT reinvent checkpoint/fork), cli
- * (Halo/RLM subprocess; `budgetExempt`, excluded from equal-k by construction). A user's
+ * (Halo/RLM subprocess; `budgetExempt`, refused by budgeted supervision). A user's
  * own agent (mastra/agno/raw HTTP/anything) is first-class by implementing this interface.
  */
 interface Executor<Out> {
   /** Stable runtime tag for traces + the equal-k exemption check. */
   readonly runtime: Runtime;
   /**
-   * When true, this executor's spend is NOT metered against the conserved pool and its
-   * iterations are excluded from the equal-k assertion (a `cli` subprocess without
-   * token accounting). Fail-loud everywhere else: a metered executor MUST report usage.
+   * When true, this executor cannot report the usage a conserved pool would need (for example, a
+   * subscription CLI with no token receipt). `Executor` can still be used directly, but `Scope`
+   * refuses it before `execute` so unknown compute can never appear as measured zero in a
+   * supervised or equal-resource run. A metered executor MUST report usage.
    */
   readonly budgetExempt?: boolean;
   /**
@@ -709,10 +736,10 @@ interface Executor<Out> {
    * Optional inbox: receive an out-of-band message from the driver mid-run (the `send`/`steer_agent`
    * verb). A streaming executor drains pending messages between turns and folds them into the next
    * step (a steer / interrupt / resume). A one-shot executor that can't be steered mid-flight omits
-   * this; `Scope.send` then returns `false` for it. Never throws — a malformed message is the
-   * executor's to ignore.
+   * this; `Scope.send` then returns `false` for it. Never throws — an inbox that rejects a malformed
+   * message returns `false`, and that refusal propagates to the caller.
    */
-  deliver?(msg: unknown): void;
+  deliver?(msg: unknown): void | boolean;
   /**
    * Optional LIVE progress: what this worker is doing RIGHT NOW, read synchronously and
    * cheaply while `execute` is still streaming. The scope already derives activity timing,
@@ -751,6 +778,15 @@ interface Executor<Out> {
     verdict?: DefaultVerdict;
     spent: Spend;
   };
+  /**
+   * Optional accounting split for recursive executors.
+   * `reported` is the child-work spend written on this node's settlement; `reservation` is the
+   * whole amount reconciled against this node's parent reservation.
+   * They differ when a driver owns a nested allocation: its child work and own inference consume
+   * that allocation together, while the journal keeps those two categories separate.
+   * Valid after `execute` resolves or throws; ordinary leaf executors omit it.
+   */
+  accounting?(): ExecutorAccounting | undefined;
   /**
    * A driver-executor's OWN-inference subtree total (rolled up from its nested tree's `metered`
    * events) — the parent scope journals it as a `metered` event for this node on settle, on BOTH
@@ -761,6 +797,24 @@ interface Executor<Out> {
    */
   metered?(): Spend | undefined;
 }
+/** Why Runtime cannot provide structured tool-call evidence for one settled execution. */
+type WorkerTraceUnavailableReason = 'execution-did-not-start' | 'executor-did-not-expose-trace-source' | 'trace-source-unavailable' | 'no-tool-spans-captured' | 'invalid-tool-spans' | 'trace-collection-failed' | 'trace-persistence-failed' | 'legacy-settlement-without-trace-evidence' | 'not-an-executor';
+/** Durable proof of a worker's structured tool trace, or the exact reason it is unavailable. */
+type WorkerTraceEvidence = {
+  readonly status: 'available';
+  /** Content-addressed pointer to a persisted `WorkerToolTraceArtifact`. */
+  readonly traceRef: string;
+  readonly spanCount: number;
+} | {
+  readonly status: 'unavailable';
+  readonly reason: WorkerTraceUnavailableReason;
+};
+/** Split used by a recursive executor when journaled child work differs from the full amount
+ * reconciled against its parent reservation. */
+interface ExecutorAccounting {
+  readonly reported: Spend;
+  readonly reservation: Spend;
+}
 /** Terminal artifact of a one-shot `Executor.execute`. */
 interface ExecutorResult<Out> {
   outRef: string;
@@ -799,11 +853,12 @@ type UsageEvent = {
  * External executors can register additional runtime strings without widening this type. */
 type Runtime = 'router' | 'inline' | 'sandbox' | 'cli' | (string & {});
 /**
- * `AgentProfile` does NOT carry a `harness`/backend field — `harness` lives on the
- * sandbox SDK's `BackendConfig`, not the portable profile. So an agent is mapped to its
- * executor through this MINIMAL wrapper, never by fabricating a field onto `AgentProfile`.
+ * `AgentProfile.harness` is a portable preference; this wrapper records the executor decision for
+ * one concrete run. A caller may honor the preference, override it for a comparison cell, or supply
+ * an executor directly, without changing the profile's behavioral identity.
  *
  * Resolution (in `runtime.ts`):
+ *  - `executorFactory` present → BYO: build it after admission with the live context.
  *  - `executor` present        → BYO: use it verbatim (a user's own `Executor`).
  *  - `harness === null`        → router/inline: a direct Router call, no box.
  *  - `harness` is a `BackendType` → sandbox: compose `runAgentRounds` against `profile` on that backend.
@@ -813,9 +868,121 @@ interface AgentSpec {
   readonly profile: AgentProfile$1;
   /** `null` selects router/inline; a `BackendType` selects the sandboxed harness. */
   readonly harness: BackendType | null;
+  /** Trusted candidate/campaign attribution supplied by the caller. Profile/task digests are
+   *  computed by Scope from the exact values it executes and cannot be supplied here. */
+  readonly execution?: AgentExecutionRef;
+  /** Per-spawn factory carrying caller configuration. Constructed only after admission, with the
+   *  real child signal and nested-scope context. */
+  readonly executorFactory?: ExecutorFactory<unknown>;
   /** Bring-your-own executor: when set, overrides harness-based resolution entirely. */
   readonly executor?: Executor<unknown>;
 }
+/** Caller-owned identity beyond the exact profile/task bytes Scope can compute itself. */
+interface AgentExecutionRef {
+  readonly candidateDigest?: Sha256Digest;
+  readonly correlation?: Readonly<Record<string, string>>;
+}
+/** Durable identity of one realized node. Missing digests mean the input was not canonical JSON. */
+interface NodeExecutionIdentity extends AgentExecutionRef {
+  readonly profileDigest?: Sha256Digest;
+  readonly taskDigest?: Sha256Digest;
+}
+/** A named model carried into an execution, or an explicit reason the exact model is unknowable. */
+type MaterializedModelIdentity = {
+  readonly status: 'known';
+  readonly id: string;
+} | {
+  readonly status: 'unknown';
+  readonly reason: string;
+};
+/** External execution identity that operators can use to join this node to its backend. */
+interface MaterializedExecutionIdentity {
+  /** Backend-native identity kind, for example `request`, `session`, `run`, `process`, or `tree`. */
+  readonly kind: string;
+  readonly id: string;
+}
+/**
+ * Data-only declaration from trusted executor code about the exact sealed plan `execute` uses.
+ * Scope snapshots this value and computes the durable receipt; callers never provide digests.
+ */
+interface ExecutorMaterialization {
+  /** Complete profile after trusted runtime-owned attachments or backend overlays were applied. */
+  readonly effectiveProfile: AgentProfile$1;
+  /** Concrete backend or harness selected for this run. */
+  readonly backend: string;
+  /** Exact selected model, or an explicit unknown reason. */
+  readonly model: MaterializedModelIdentity;
+  /** Backend-native session/run/request/process identity. */
+  readonly execution: MaterializedExecutionIdentity;
+  /** Named implementation that turns the effective profile into executable backend inputs. */
+  readonly materializer: string;
+  /** Finite JSON describing the exact materialization plan. Persisted by digest only. */
+  readonly plan: unknown;
+  /** Trusted runtime-only attachments, such as the coordination MCP. Persisted by digest only. */
+  readonly platformAttachments?: unknown;
+}
+/** Volatile execution routing that is true for one attempt but is not profile identity. The full
+ * binding is hashed and discarded; only the safe structural descriptor is journaled. */
+interface ExecutorExecutionBinding {
+  readonly attemptId: string;
+  readonly binding: unknown;
+  readonly descriptor: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** Why exact materialization evidence is unavailable for a node. */
+type UnknownMaterializationReason = 'executor-did-not-report' | 'invalid-executor-report' | 'root-agent-did-not-report';
+/** What the kernel can prove about one node's actual execution plan. */
+type ProfileMaterializationReceipt = {
+  readonly status: 'known';
+  readonly authoredProfileDigest: Sha256Digest;
+  readonly effectiveProfileDigest: Sha256Digest;
+  readonly materializationPlanDigest: Sha256Digest;
+  readonly platformAttachmentsDigest?: Sha256Digest;
+  readonly runtime: Runtime;
+  readonly backend: string;
+  readonly model: MaterializedModelIdentity;
+  readonly execution: MaterializedExecutionIdentity;
+  readonly materializer: string;
+} | {
+  readonly status: 'unknown';
+  readonly authoredProfileDigest?: Sha256Digest;
+  readonly runtime: Runtime;
+  readonly reason: UnknownMaterializationReason;
+};
+/** One attempt's immutable link from a stable materialization plan to its actual transport. */
+type ExecutionBindingReceipt = {
+  readonly status: 'known';
+  readonly attemptId: string;
+  readonly materializationReceiptDigest: Sha256Digest;
+  readonly bindingDigest: Sha256Digest;
+  readonly descriptor: Readonly<Record<string, string | number | boolean | null>>;
+} | {
+  readonly status: 'unknown';
+  readonly attemptId: string;
+  readonly materializationReceiptDigest: Sha256Digest;
+  readonly reason: UnknownMaterializationReason;
+};
+/** Trusted root composition evidence. Generic `Agent.act` roots omit this and remain unknown. */
+type RootMaterialization = {
+  readonly runtime: Runtime;
+  readonly declaration: ExecutorMaterialization;
+  readonly binding: Omit<ExecutorExecutionBinding, 'attemptId'>;
+} | {
+  /** The runtime-owned external adapter will publish the exact declaration after its dynamic
+   * platform attachment (for example a coordination URL) exists and before paid work starts. */
+  readonly runtime: Runtime;
+  readonly declaration: 'deferred';
+  /** Exact admitted profile used to validate the stable effective identity at publication. */
+  readonly authoredProfile: AgentProfile$1;
+};
+/** Kernel-owned context for the concrete supervised node a factory is constructing. */
+interface ExecutorNodeContext {
+  readonly rootId: NodeId;
+  readonly parentId: NodeId;
+  readonly nodeId: NodeId;
+  /** Kernel-minted identity for this concrete execution attempt. */
+  readonly attemptId: string;
+  readonly identity?: NodeExecutionIdentity;
+}
 /**
  * Builds a fresh `Executor` for one spawn from the resolved spec. Per-spawn (not
  * shared) so each child owns its own box/abort/teardown lifecycle. A BYO factory lets a
@@ -827,6 +994,8 @@ type ExecutorFactory<Out> = (spec: AgentSpec, ctx: ExecutorContext) => Executor<
  *  the factory reaching into module globals. */
 interface ExecutorContext {
   readonly signal: AbortSignal;
+  /** Present when Scope constructs the executor for a supervised node. */
+  readonly node?: ExecutorNodeContext;
   /** Opaque seams the registry threads through; a built-in narrows what it needs. */
   readonly seams: Readonly<Record<string, unknown>>;
 }
@@ -840,8 +1009,8 @@ interface ExecutorRegistry {
   /** Register a factory for a named runtime. Throws on a duplicate name (fail loud). */
   register<Out>(runtime: Runtime, factory: ExecutorFactory<Out>): void;
   /**
-   * Resolve a spec to a factory. Precedence: a BYO `spec.executor` → a trivial factory
-   * returning it; else `harness === null` → the `'router'` factory; else a registered
+   * Resolve a spec to a factory. Precedence: a BYO `spec.executorFactory` → `spec.executor` →
+   * `harness === null` → the `'router'` factory; else a registered
    * factory for the harness-derived runtime. Returns a typed outcome — the caller
    * inspects `succeeded` before `value` (no silent fallback).
    */
@@ -890,6 +1059,9 @@ type NodeId = string;
 interface SpawnOpts {
   readonly budget: Budget;
   readonly label: string;
+  /** Manager-scoped semantic assignment identity. Unlike `key`, this names every spawn, including
+   * unkeyed siblings, so product traces can join authorization, node, and backend execution. */
+  readonly assignmentId?: string;
   readonly restart?: Restart;
   /** Teardown grace handed to the executor when this node is reaped. */
   readonly shutdown?: number | 'brutalKill' | 'infinity';
@@ -906,13 +1078,17 @@ interface SpawnOpts {
   readonly key?: string;
 }
 /** Fail-closed spawn rejections: an exhausted pool, a dollar request against a root that budgets
- *  no dollars, an exceeded recursion ceiling, or a `key` that is still LIVE in this scope (the
- *  same assignment may not run twice concurrently).
+ *  no dollars, an exceeded recursion ceiling, a full tree-wide worker allocation, or a `key` that
+ *  is still LIVE in this scope (the same assignment may not run twice concurrently).
  *
  *  `usd-unbudgeted` is separate from `budget-exhausted` because the two call for opposite
  *  responses: an exhausted pool may admit a smaller request, while an unbudgeted dollar channel
- *  refuses every amount until the ROOT budget names a `maxUsd`. */
-type SpawnRejection = 'budget-exhausted' | 'usd-unbudgeted' | 'depth-exceeded' | 'duplicate-key';
+ *  refuses every amount until the ROOT budget names a `maxUsd`.
+ *
+ *  `below-runtime-floor` is separate for the same reason and points the opposite way from
+ *  `budget-exhausted`: the request is under what that harness spends before it reads its task, so
+ *  it is unsatisfiable at that SIZE and the fix is to RAISE it, never to retry smaller. */
+type SpawnRejection = 'budget-exhausted' | 'usd-unbudgeted' | 'below-runtime-floor' | 'depth-exceeded' | 'duplicate-key' | 'invalid-identity' | 'key-conflict' | 'max-live-workers' | 'scope-aborted';
 /**
  * What a KEYED spawn resolved to when the key had a prior attempt. Absent on a fresh key (and on
  * every unkeyed spawn). `'completed'` is the exactly-once path: NOTHING was spawned — the handle
@@ -920,8 +1096,10 @@ type SpawnRejection = 'budget-exhausted' | 'usd-unbudgeted' | 'depth-exceeded' |
  * `'lost'` DID spawn fresh: the prior attempt settled `down` (retried) or was journaled as
  * started but never settled — the process died with it in flight and the built-in executors
  * cannot re-attach to a dead process's work, so the result is explicitly in doubt (lost), never
- * silently duplicated. An executor that CAN re-attach to a still-running external execution (a
- * live sandbox box) extends this union with an adoption state; none of the built-ins can today.
+ * silently duplicated. On restart, an in-doubt attempt's full declared reservation is charged and
+ * its telemetry remains unknown; a fresh retry is admitted only from safely remaining capacity.
+ * An executor that CAN re-attach to a still-running external execution extends this union with an
+ * adoption state; none of the built-ins can today.
  */
 type SpawnPrior<Out = unknown> = {
   readonly state: 'completed';
@@ -945,6 +1123,14 @@ interface Handle<Out> {
   readonly id: NodeId;
   readonly label: string;
   readonly status: NodeStatus;
+  /** Manager-scoped assignment identity supplied at admission. */
+  readonly assignmentId?: string;
+  /** Durable identity of the authorized profile/task/candidate represented by this handle. */
+  readonly identity?: NodeExecutionIdentity;
+  /** Stable execution plan once Runtime has committed it. */
+  readonly materialization?: ProfileMaterializationReceipt;
+  /** Immutable per-attempt backend bindings committed so far, oldest first. */
+  readonly executionBindings?: ReadonlyArray<ExecutionBindingReceipt>;
   abort(reason?: string): void;
   /** Phantom: binds the handle to the child's output type so `spawn<C>` returns a
    *  `Handle<C>` distinct from a `Handle<other>`. Type-only — never present at runtime. */
@@ -962,6 +1148,10 @@ type Settled<Out> = {
   outRef: string;
   verdict?: DefaultVerdict;
   spent: Spend;
+  /** Structured tool evidence captured before this settlement was journaled. */
+  trace: WorkerTraceEvidence;
+  /** Epoch ms parsed from the durable settlement record when available. */
+  settledAt?: number;
   seq: number;
 } | {
   kind: 'down';
@@ -970,6 +1160,10 @@ type Settled<Out> = {
   /** True = infrastructure failure (excluded from merge `n` / equal-k), not a bad result. */
   infra: boolean;
   restartCount: number;
+  /** Partial structured tool evidence captured before this failure was journaled. */
+  trace: WorkerTraceEvidence;
+  /** Epoch ms parsed from the durable settlement/cancellation record when available. */
+  settledAt?: number;
   seq: number;
 };
 /**
@@ -980,13 +1174,17 @@ type Settled<Out> = {
  */
 interface Scope<Out> {
   /**
-   * Spawn a child. Reserves `opts.budget` from the conserved pool atomically; refunds the
-   * unspent remainder on settle. Returns a typed outcome — fail-closed on an exhausted
-   * pool, an exceeded depth ceiling, or a still-live duplicate `key` (the caller inspects
-   * `ok` before `handle`). A KEYED spawn whose key already settled `done` spends nothing:
-   * it returns the committed result on `prior` instead of re-running (see `SpawnOpts.key`).
+   * Spawn a child. For a fresh key or an unkeyed spawn, tree-wide worker admission happens before a
+   * lazy factory is called, so a full worker allocation creates no worker, executor, or reservation.
+   * Reserves `opts.budget` from the conserved pool atomically; refunds the unspent remainder on
+   * settle. Returns a typed outcome — fail-closed on an exhausted pool, an exceeded depth ceiling, a
+   * full worker allocation, or a still-live duplicate `key` (the caller inspects `ok` before
+   * `handle`). A KEYED spawn whose key already settled `done` invokes the factory only far enough to
+   * prepare and authorize the exact profile/task identity, then compares that identity with the
+   * journal. On a match it spends nothing, constructs no executor, reserves no budget, and runs no
+   * work: it returns the committed result on `prior` (see `SpawnOpts.key`).
    */
-  spawn<C extends Out>(agent: Agent<unknown, C>, task: unknown, opts: SpawnOpts): {
+  spawn<C extends Out>(agent: Agent<unknown, C> | (() => Agent<unknown, C>), task: unknown, opts: SpawnOpts): {
     ok: true;
     handle: Handle<C>;
     prior?: SpawnPrior<C>;
@@ -1088,13 +1286,21 @@ interface Scope<Out> {
   /** Conserved-pool readouts (post-reservation). */
   readonly budget: Readonly<{
     tokensLeft: number;
+    /** `false` once a turn settled without reporting its tokens: `tokensLeft` is then a ceiling,
+     *  not a measurement. */
+    tokensKnown: boolean;
     usdLeft: number;
     usdCapped: boolean;
+    usdKnown: boolean;
+    iterationsLeft: number;
     deadlineMs: number;
     reservedTokens: number;
-    /** Present and `false` once a turn settled without reporting its tokens: `tokensLeft` is then
-     *  a ceiling, not a measurement. Absent means every settled turn reported. */
-    tokensKnown?: boolean;
+  }>;
+  /** One tree-wide view of simultaneous spawned work. Every nested scope reads the same counter;
+   *  the root agent itself is not a spawned worker. `freeSlots` is `null` when no limit is set. */
+  readonly workerCapacity: Readonly<{
+    live: number;
+    freeSlots: number | null;
   }>;
 }
 /**
@@ -1136,6 +1342,8 @@ interface ResumedWork<Out> {
 interface ResumedKeyState<Out = unknown> {
   readonly id: NodeId;
   readonly label: string;
+  /** Identity recorded when this key was first admitted. Every reuse must match it exactly. */
+  readonly identity?: NodeExecutionIdentity;
   readonly state: 'completed' | 'down' | 'in-doubt';
   /** The rehydrated settlement; absent exactly when `state` is `'in-doubt'`. */
   readonly settled?: Settled<Out>;
@@ -1147,10 +1355,23 @@ interface NodeSnapshot {
   readonly status: NodeStatus;
   readonly runtime: Runtime;
   readonly budget: Budget;
+  /** Exact nested journal tree owned by this node, when Runtime attested recursive ownership. */
+  readonly ownedTreeRoot?: NodeId;
+  /** Manager-scoped assignment identity, including deterministic ids for unkeyed siblings. */
+  readonly assignmentId?: string;
+  readonly identity?: NodeExecutionIdentity;
+  /** Kernel-owned execution evidence. `unknown` is distinct from a known zero/empty plan. */
+  readonly materialization?: ProfileMaterializationReceipt;
+  /** Immutable attempt bindings, oldest first. A retried/resumed node may have more than one. */
+  readonly executionBindings?: ReadonlyArray<ExecutionBindingReceipt>;
+  /** Epoch ms of the terminal journal record; absent while live or when legacy evidence lacks it. */
+  readonly settledAt?: number;
   /** Conserved spend so far for this node. */
   readonly spent: Spend;
   /** `outRef` once the node is `done` (the replay/result pointer). */
   readonly outRef?: string;
+  /** Present on terminal executor nodes; legacy records carry an explicit unavailable reason. */
+  readonly trace?: WorkerTraceEvidence;
 }
 /** The live tree — what `scope.view` / `RootHandle.view()` materialize for a viewer. */
 interface TreeView {
@@ -1173,8 +1394,31 @@ type SpawnEvent = {
   /** The semantic spawn key (`SpawnOpts.key`), when the spawn carried one — what a resumed
    *  run matches to resolve the same assignment to its committed result. */
   key?: string;
+  /** Manager-scoped assignment identity used to join unkeyed and keyed work alike. */
+  assignmentId?: string;
   budget: Budget;
   runtime: Runtime;
+  /** Exact nested journal tree this node owns. Runtime writes this only after privately
+   * attesting the executor as a recursive scope owner. Its absence means no tree is followed,
+   * including records written before this field existed and caller leaves named `driver`. */
+  ownedTreeRoot?: NodeId;
+  /** Exact profile/task digests plus trusted candidate/campaign attribution when available. */
+  identity?: NodeExecutionIdentity;
+  seq: number;
+  at: string;
+} | {
+  /** Volatile transport/session binding for exactly one attempt. The full binding is retained
+   * only by digest; descriptor fields are safe structural labels, never credential-bearing URLs. */
+  kind: 'execution-bound';
+  id: NodeId;
+  binding: ExecutionBindingReceipt;
+  seq: number;
+  at: string;
+} | {
+  /** Trusted runtime transformation from the authorized profile to actual wire bytes. */
+  kind: 'materialized';
+  id: NodeId;
+  receipt: ProfileMaterializationReceipt;
   seq: number;
   at: string;
 } | {
@@ -1186,6 +1430,11 @@ type SpawnEvent = {
   verdict?: DefaultVerdict;
   spent: Spend;
   infra?: boolean;
+  /** Exact child failure. Present on every new `status: 'down'` record; optional only so
+   * journals written before this field existed remain replayable. */
+  reason?: string;
+  /** Structured tool evidence. Optional only for journals written before trace capture. */
+  trace?: WorkerTraceEvidence;
   seq: number;
   at: string;
 } | {
@@ -1261,6 +1510,11 @@ interface Supervisor<Task, Out> {
 interface SupervisorOpts {
   /** The root conserved-pool ceiling (tokens + usd + iterations + deadline). */
   readonly budget: Budget;
+  /** Exact root profile/task identity supplied by the one-call composition surface. */
+  readonly rootIdentity?: NodeExecutionIdentity;
+  /** Trusted composition evidence for a root whose `act` drives an external backend. A generic
+   *  root omits it and is durably marked unknown; model-facing Scope never receives this writer. */
+  readonly rootMaterialization?: RootMaterialization;
   /** Trace-correlation root + the journal/blob root key. */
   readonly runId: NodeId;
   /** Event source — defaults to the in-memory journal in the impl; pass JSONL/FS for durability. */
@@ -1275,6 +1529,9 @@ interface SupervisorOpts {
   readonly probes?: WaitProbeRegistry;
   /** Runtime recursion-depth ceiling (paired with the conserved pool per R3). */
   readonly maxDepth?: number;
+  /** Hard tree-wide cap on simultaneously executing spawned workers. The root is excluded; every
+   *  nested driver and leaf shares this one allocation. Omit/`<= 0` leaves worker count uncapped. */
+  readonly maxLiveWorkers?: number;
   /**
    * OTP intensity breaker: more than `maxRestarts` child restarts within `withinMs`
    * trips the supervisor to `no-winner` rather than restarting forever.
@@ -1373,16 +1630,23 @@ type SupervisedResult<Out> = {
    *  recoverable by the caller. A non-`Error` rejection is normalized, never dropped. */
   error: NoWinnerError;
 };
-/** Live root handle — the substrate a chat/pi-viz client attaches to (Q2). `signal`
- *  delivers an out-of-band message to the running root; `view()` materializes the tree. */
+/** Live root handle — a chat/pi-viz client uses it to inspect and control one root run. */
 interface RootHandle<Out> {
   view(): TreeView;
+  /** Optional for structural compatibility with existing view/signal/abort wrappers. Handles
+   * minted by `createRootHandle` implement the required form in `SteerableRootHandle`. */
+  deliver?(msg: unknown): boolean;
   signal(msg: RootSignal): void;
   abort(reason?: string): void;
   /** Phantom: binds the handle to the supervised run's output type. Type-only — never
    *  present at runtime; lets `attach(h: RootHandle<Out>)` stay output-typed. */
   readonly __out?: Out;
 }
+/** A Runtime-minted root handle that can deliver raw steering or answers to a live manager inbox.
+ * Delivery returns `false` when the manager has no receive path; detached calls fail loud. */
+interface SteerableRootHandle<Out> extends RootHandle<Out> {
+  deliver(msg: unknown): boolean;
+}
 /** Out-of-band message to a running root. Open by intent — a client extends it. */
 type RootSignal = {
   kind: 'pause';
@@ -1452,6 +1716,8 @@ declare function resolveAgentEnvironmentProvider(provider: AgentEnvironmentProvi
 interface ProviderAsSandboxClientOptions {
   defaults?: Partial<CreateAgentEnvironmentInput>;
   requireTerminalEvent?: boolean;
+  /** Require declared live continuation plus concrete session controls. */
+  requireSession?: boolean;
   mapCreateOptions?: (options: CreateSandboxOptions | undefined) => Partial<CreateAgentEnvironmentInput>;
 }
 /** Adapt a neutral environment provider to the `SandboxClient` interface used by existing loop paths.
@@ -1484,5 +1750,5 @@ interface ProviderExecutorOptions {
  * @experimental */
 declare function providerAsExecutor(provider: AgentEnvironmentProvider, options?: ProviderExecutorOptions): ExecutorFactory<unknown>;
 //#endregion
-export { ResumedWork as $, createRuntimeEventCollector as $t, providerAsSandboxClient as A, readWorkerProgress as An, EvalRunsExportResult as At, Executor as B, buildRuntimeEventOtelSpans as Bt, ProviderAsSandboxClientOptions as C, ActivityLog as Cn, TraceContext as Ct, WorkspaceRequest as D, ScopeProgressInput as Dn, EvalRunEvent as Dt, SandboxClientProviderOptions as E, ExecutorProgress as En, traceContextToEnv as Et, createTangleSandboxExactProcessProvider as F, OtelExporter as Ft, Handle as G, toOtelAttributes as Gt, ExecutorFactory as H, exportEvalRuns as Ht, Agent as I, OtelSpan as It, NodeSnapshot as J, RuntimeStreamEventSink as Jt, NoWinnerError as K, RuntimeEventCollector as Kt, AgentSpec as L, RuntimeEventOtelOptions as Lt, sandboxClientAsProvider as M, LoopSpanNode as Mt, CreateTangleSandboxExactProcessProviderOptions as N, OtelAttribute as Nt, createAgentEnvironmentProviderRegistry as O, WorkerProgress as On, EvalRunGeneration as Ot, SandboxControlClient as P, OtelExportConfig as Pt, ResumedKeyState as Q, SanitizedKnowledgeRequirement as Qt, Budget as R, buildLoopOtelSpans as Rt, PlacementInfo as S, sandboxSessionTraceSource as Sn, workerTraceSeamKey as St, ResourceRequest as T, DEFAULT_STALL_AFTER_MS as Tn, readTraceContextFromEnv as Tt, ExecutorRegistry as U, generateSpanId as Ut, ExecutorContext as V, createOtelExporter as Vt, ExecutorResult as W, loopEventToOtelSpan as Wt, Restart as X, RuntimeTelemetryOptions as Xt, NodeStatus as Y, RuntimeStreamEventSummary as Yt, ResultBlobStore as Z, SanitizedKnowledgeReadinessReport as Zt, CheckpointRequest as _, SessionTraceBox as _n, WidenGate as _t, AgentEnvironmentProviderRef as a, WaitOutcome as an, SpawnEvent as at, ExecResult as b, createPushTraceSource as bn, readWorkerTraceContext as bt, AgentEnvironmentStatus as c, WaitRejection as cn, SpawnPrior as ct, AgentSession as d, isWaitOutcome as dn, SupervisedResult as dt, createRuntimeStreamEventCollector as en, RootHandle as et, AgentSessionRef as f, pollFor as fn, Supervisor as ft, CheckpointRef as g, SessionMessageLike as gn, WaitOpts as gt, AgentTurnResult as h, waitUntil as hn, UsageEvent as ht, AgentEnvironmentProvider$1 as i, PendingWait as in, Settled as it, resolveAgentEnvironmentProvider as j, INTELLIGENCE_WIRE_VERSION as jt, providerAsExecutor as k, createActivityLog as kn, EvalRunsExportConfig as kt, AgentEnvironmentSummary as l, WaitSpec as ln, SpawnRejection as lt, AgentTurnInput$1 as m, validateWaitSpec as mn, TreeView as mt, AgentEnvironmentCapabilities$1 as n, sanitizeKnowledgeReadinessReport as nn, Runtime as nt, AgentEnvironmentProviderRegistry as o, WaitProbe as on, SpawnJournal as ot, AgentSessionStatus as p, timerAt as pn, SupervisorOpts as pt, NodeId as q, RuntimeStreamEventCollector as qt, AgentEnvironmentEvent as r, sanitizeRuntimeStreamEvent as rn, Scope as rt, AgentEnvironmentQuery as s, WaitProbeRegistry as sn, SpawnOpts as st, AgentEnvironment as t, sanitizeAgentRuntimeEvent as tn, RootSignal as tt, AgentProfileRef$1 as u, createWaitProbes as un, Spend as ut, CreateAgentEnvironmentInput$1 as v, ToolStepInput as vn, WorkerTraceResolver as vt, ProviderExecutorOptions as w, ActivityNote as wn, createPropagatingTraceEmitter as wt, ForkRequest as x, decodeToolPart as xn, workerTraceEnv as xt, ExecRequest as y, TraceSource as yn, WorkerTraceSeamCarrier as yt, DefaultVerdict as z, buildLoopSpanNodes as zt };
-//# sourceMappingURL=environment-provider-CWsRh6Uz.d.ts.map
+export { MaterializedModelIdentity as $, buildLoopOtelSpans as $t, providerAsSandboxClient as A, validateWaitSpec as An, WidenGate as At, DefaultVerdict as B, ActivityNote as Bn, readTraceContextFromEnv as Bt, ProviderAsSandboxClientOptions as C, WaitProbeRegistry as Cn, SupervisedResult as Ct, WorkspaceRequest as D, isWaitOutcome as Dn, UnknownMaterializationReason as Dt, SandboxClientProviderOptions as E, createWaitProbes as En, TreeView as Et, createTangleSandboxExactProcessProvider as F, TraceSource as Fn, readWorkerTraceContext as Ft, ExecutorExecutionBinding as G, createActivityLog as Gn, EvalRunsExportResult as Gt, Executor as H, ExecutorProgress as Hn, EvalRunEvent as Ht, Agent as I, createPushTraceSource as In, workerTraceEnv as It, ExecutorNodeContext as J, OtelAttribute as Jt, ExecutorFactory as K, readWorkerProgress as Kn, INTELLIGENCE_WIRE_VERSION as Kt, AgentExecutionRef as L, decodeToolPart as Ln, workerTraceSeamKey as Lt, sandboxClientAsProvider as M, SessionMessageLike as Mn, WorkerTraceUnavailableReason as Mt, CreateTangleSandboxExactProcessProviderOptions as N, SessionTraceBox as Nn, WorkerTraceResolver as Nt, createAgentEnvironmentProviderRegistry as O, pollFor as On, UsageEvent as Ot, SandboxControlClient as P, ToolStepInput as Pn, WorkerTraceSeamCarrier as Pt, MaterializedExecutionIdentity as Q, RuntimeEventOtelOptions as Qt, AgentSpec as R, sandboxSessionTraceSource as Rn, TraceContext as Rt, PlacementInfo as S, WaitProbe as Sn, SteerableRootHandle as St, ResourceRequest as T, WaitSpec as Tn, SupervisorOpts as Tt, ExecutorAccounting as U, ScopeProgressInput as Un, EvalRunGeneration as Ut, ExecutionBindingReceipt as V, DEFAULT_STALL_AFTER_MS as Vn, traceContextToEnv as Vt, ExecutorContext as W, WorkerProgress as Wn, EvalRunsExportConfig as Wt, ExecutorResult as X, OtelExporter as Xt, ExecutorRegistry as Y, OtelExportConfig as Yt, Handle as Z, OtelSpan as Zt, CheckpointRequest as _, sanitizeAgentRuntimeEvent as _n, SpawnJournal as _t, AgentEnvironmentProviderRef as a, generateSpanId as an, ProfileMaterializationReceipt as at, ExecResult as b, PendingWait as bn, SpawnRejection as bt, AgentEnvironmentStatus as c, RuntimeEventCollector as cn, ResumedKeyState as ct, AgentSession as d, RuntimeStreamEventSummary as dn, RootMaterialization as dt, buildLoopSpanNodes as en, NoWinnerError as et, AgentSessionRef as f, RuntimeTelemetryOptions as fn, RootSignal as ft, CheckpointRef as g, createRuntimeStreamEventCollector as gn, SpawnEvent as gt, AgentTurnResult as h, createRuntimeEventCollector as hn, Settled as ht, AgentEnvironmentProvider$1 as i, exportEvalRuns as in, NodeStatus as it, resolveAgentEnvironmentProvider as j, waitUntil as jn, WorkerTraceEvidence as jt, providerAsExecutor as k, timerAt as kn, WaitOpts as kt, AgentEnvironmentSummary as l, RuntimeStreamEventCollector as ln, ResumedWork as lt, AgentTurnInput$1 as m, SanitizedKnowledgeRequirement as mn, Scope as mt, AgentEnvironmentCapabilities$1 as n, createOpenInferenceFileExporter as nn, NodeId as nt, AgentEnvironmentProviderRegistry as o, loopEventToOtelSpan as on, Restart as ot, AgentSessionStatus as p, SanitizedKnowledgeReadinessReport as pn, Runtime as pt, ExecutorMaterialization as q, LoopSpanNode as qt, AgentEnvironmentEvent as r, createOtelExporter as rn, NodeSnapshot as rt, AgentEnvironmentQuery as s, toOtelAttributes as sn, ResultBlobStore as st, AgentEnvironment as t, buildRuntimeEventOtelSpans as tn, NodeExecutionIdentity as tt, AgentProfileRef$1 as u, RuntimeStreamEventSink as un, RootHandle as ut, CreateAgentEnvironmentInput$1 as v, sanitizeKnowledgeReadinessReport as vn, SpawnOpts as vt, ProviderExecutorOptions as w, WaitRejection as wn, Supervisor as wt, ForkRequest as x, WaitOutcome as xn, Spend as xt, ExecRequest as y, sanitizeRuntimeStreamEvent as yn, SpawnPrior as yt, Budget as z, ActivityLog as zn, createPropagatingTraceEmitter as zt };
+//# sourceMappingURL=environment-provider-CTZjdIUg.d.ts.map