@tangle-network/agent-runtime 0.68.0 → 0.70.0

package/dist/loops.d.ts

@@ -1,18 +1,3151 @@
+import { ChatClient, AnalystFinding, AgentProfile, AnalystRunInputs, ToolSpan, StreamingDetector, DetectorSignal, buildTrajectory } from '@tangle-network/agent-eval';
+export { AnalystFinding, DefaultVerdict, computeFindingId, makeFinding } from '@tangle-network/agent-eval';
+import { SandboxInstance, CreateSandboxOptions, SandboxEvent, BackendType } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-export { AgenticOptions, AgenticRunResult, AgenticSurface, AgenticTask, AgenticTool, AnytimeReport, AnytimeStrategySummary, AnytimeTaskCurve, ArtifactHandle, AuditIntentInput, AuditIntentOptions, AuthorStrategyOptions, AuthoredProfile, AuthoredStrategy, BenchmarkCell, BenchmarkConfig, BenchmarkLift, BenchmarkReport, BenchmarkStrategySummary, BenchmarkTaskRow, BridgeSeam, BudgetPool, BudgetReadout, ChampionPick, ChampionPolicy, CheckpointCapableBox, CliSeam, CliWorktreeSeam, CompletionAnalyst, CompletionEvidence, CompletionPolicy, CompletionVerdict, CoordinationDriverOptions, CoordinationMcpHandle, CreateScopeAnalystOptions, CriuCapableClient, Deliverable, DriverChat, DriverMessage, DriverToolCall, DriverTurn, Environment, EvolutionArchiveNode, EvolutionAuthor, EvolutionBandInfo, EvolutionCandidate, EvolutionGeneration, EvolutionReport, ExecutorConfig, FileCorpus, FileResultBlobStore, FileSpawnJournal, ForkCapableBox, GitWorkspaceOptions, HarvestCorpusOptions, HarvestFailure, HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemoryRunContext, InMemoryRunContextOptions, InMemorySpawnJournal, Inbox, InboxMessage, IntentAudit, LoopDispatchOptions, LoopOptionsForDispatch, McpEndpoint, McpEnvironmentOptions, NestedScopeSeam, Observation, ObserveInput, ObserveOptions, OpenSandboxRunOptions, PromotionGateOptions, PromotionVerdict, RegistryAnalyzeProjection, ReservationTicket, RouterSeam, RouterToolsSeam, RunAgenticOptions, SandboxCapabilities, SandboxLineage, SandboxLineageHandle, SandboxRun, SandboxSeam, SessionCapableBox, SessionMessageLike, SessionTraceBox, Shell, ShotPersona, ShotSpec, Strategy, StrategyCtx, StrategyEvolutionConfig, StrategyResult, SurfaceScore, ToolPartDecoder, ToolStepInput, TraceSource, TrajectoryAnalysis, TurnResult, UsageSink, VerifierEnvironmentOptions, WatchTraceOptions, WaterfallCollector, WaterfallReport, WaterfallSpan, Workspace, WorkspaceCommit, WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, authoredWorker, breadthDriver, buildSteerContext, builtinShapes, cliWorktreeExecutor, completionAuthorizes, contentAddress, coordinationDriverAgent, createBudgetPool, createExecutor, createExecutorRegistry, createInMemoryRunContext, createInbox, createMcpEnvironment, createPartsTraceSource, createPushTraceSource, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeAnthropicPart, decodeOpenAiPart, decodeOpencodePart, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultToolDetectors, definePersona, defineStrategy, depthDriver, deterministicCompletion, discriminatingMeans, driverChild, driverExecutorFactory, driverRuntime, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, isDriverSpec, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, nestedScopeSeamKey, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerDriverChat, runAgentic, runBenchmark, runInWorkspace, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, supervisorSkill, toToolSpan, toolPartDecoders, trajectoryReport, verify, watchTrace, widen, withDriverExecutor } from './runtime.js';
-export { d as AssertTraceDerivedFindings, A as AuthoredHarness, u as CoderCheckConstraints, v as CoderCheckInput, g as CombinatorShape, c as Corpus, l as CorpusFilter, C as CorpusRecord, w as DefinePersona, D as DefinePersonaInput, t as DeliverableSpec, E as EqualKArm, x as EqualKOnCost, q as EqualKOnCostOptions, r as EqualKVerdict, y as Fanout, F as FanoutOptions, z as FanoutSynthesis, j as FanoutWinnerSelector, B as FlatWidenGate, p as LoopShape, G as LoopUntil, L as LoopUntilSpec, H as LoopUntilState, O as Outcome, I as Panel, J as PanelJudge, P as PanelSpec, K as PanelVerdict, M as PatchDeliverableOptions, m as Persona, N as PersonaContext, Q as PersonaExecutors, U as Pipeline, i as PipelineStage, X as RenderCorpusToInstructions, R as RenderCorpusToInstructionsOptions, Y as RunPersonified, n as RunPersonifiedOptions, f as ScopeAnalyst, S as ScopeAnalyzeInput, h as ScopeWidenGate, Z as ShapeBudget, _ as ShapeContext, o as ShapeRegistry, e as SteerContext, $ as TrajectoryNode, s as TrajectoryReport, a0 as TrajectoryReportFn, T as TrajectoryReportOptions, a1 as Verify, V as VerifySpec, a2 as Widen, a3 as WidenDecision, a4 as WidenLineage, k as WidenSpec, W as WinnerStrategy, a5 as WorktreeCliExecutorOptions, a6 as WorktreeCommandResult, a as WorktreeFanoutOptions, b as WorktreePatchArtifact, a7 as countDiffLines, a8 as createWorktreeCliExecutor, a9 as gateOnDeliverable, aa as isNonEmptyPatch, ab as patchDelivered, ac as runCoderChecks, ad as touchedPathsFromPatch, ae as touchesSecretPath, af as worktreeFanout } from './worktree-fanout-DUiKPApb.js';
-export { a as RouterChatResult, b as RouterChatToolsResult, R as RouterConfig, c as RouterToolCall, d as RouterToolLoopResult, T as ToolSpec, r as routerChatWithTools, e as routerChatWithUsage, f as routerToolLoop } from './router-client-30Y_pca8.js';
-export { R as RunLoopOptions, c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-D3PwlG7J.js';
-export { B as BusEvent, p as BusRecord, q as BusStats, E as EventBus, P as PublishOptions, r as createEventBus } from './coordination-Curpzeyc.js';
-export { A as Agent, h as AgentSpec, B as Budget, n as Executor, bc as ExecutorContext, b9 as ExecutorFactory, E as ExecutorRegistry, bd as ExecutorResult, be as Handle, N as NodeId, bf as NodeSnapshot, bg as NodeStatus, bh as Restart, g as ResultBlobStore, j as RootHandle, bi as RootSignal, bj as Runtime, S as Scope, l as Settled, b7 as SpawnEvent, i as SpawnJournal, bk as SpawnOpts, m as Spend, k as SupervisedResult, bb as Supervisor, bl as SupervisorOpts, b8 as TreeView, ba as UsageEvent, bm as WidenGate } from './delegates-CLFNAKyi.js';
-export { A as AgentRunSpec, D as Driver, E as ExecCtx, I as Iteration, F as LoopDecisionPayload, G as LoopEndedPayload, H as LoopIterationDispatchPayload, J as LoopIterationEndedPayload, M as LoopIterationStartedPayload, a as LoopLineageOptions, N as LoopPlanDescription, P as LoopPlanPayload, b as LoopResult, e as LoopSandboxPlacement, Q as LoopStartedPayload, T as LoopTeardownFailedPayload, f as LoopTokenUsage, g as LoopTraceEmitter, d as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, S as SandboxClient, U as ValidationCtx, V as Validator } from './types-Crxftafi.js';
-export { DefaultVerdict } from '@tangle-network/agent-eval';
-import './runtime-hooks-C7JwKb9E.js';
-import '@tangle-network/agent-eval/campaign';
-import './types-p8dWBIXL.js';
-import '@tangle-network/agent-interface';
-import './local-harness-BE_h8szs.js';
+import { g as ResultBlobStore, i as SpawnJournal, N as NodeId, bb as SpawnEvent, bc as ExecutorFactory, A as Agent, B as Budget, S as Scope, l as Settled, k as SupervisedResult, m as Spend, bd as UsageEvent, E as ExecutorRegistry, L as LocalHarness, be as Supervisor } from './delegates-DqAgo32T.js';
+export { h as AgentSpec, n as Executor, bf as ExecutorContext, bg as ExecutorResult, bh as SupervisorOpts, bi as TreeView, bj as WidenGate } from './delegates-DqAgo32T.js';
+import { M as MakeWorkerAgent, a as CoordinationTools, A as AnalystRegistry, C as CoordinationEvent, j as QuestionPolicy } from './coordination-C7WxwHXq.js';
+export { B as BusEvent, p as BusRecord, q as BusStats, E as EventBus, P as PublishOptions, r as createEventBus } from './coordination-C7WxwHXq.js';
+import { b as RuntimeHooks, I as Iteration, S as SandboxClient, T as Driver, A as AgentRunSpec, a as OutputAdapter, V as Validator, U as ExecCtx, W as LoopWinner, X as LoopLineageOptions, Y as LoopResult, d as LoopTokenUsage, R as RuntimeStreamEvent } from './types-BYa2ZOAx.js';
+export { Z as LoopDecisionPayload, _ as LoopEndedPayload, $ as LoopIterationDispatchPayload, a0 as LoopIterationEndedPayload, a1 as LoopIterationStartedPayload, a2 as LoopPlanDescription, a3 as LoopPlanPayload, c as LoopSandboxPlacement, a4 as LoopStartedPayload, a5 as LoopTeardownFailedPayload, e as LoopTraceEmitter, L as LoopTraceEvent, a6 as ValidationCtx } from './types-BYa2ZOAx.js';
+import { C as CorpusRecord, c as Corpus, O as Outcome, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, e as SteerContext, f as ScopeAnalyst, F as FanoutOptions, g as CombinatorShape, h as ScopeWidenGate, L as LoopUntilSpec, P as PanelSpec, i as PipelineStage, W as WinnerStrategy, j as FanoutWinnerSelector, V as VerifySpec, k as WidenSpec, l as CorpusFilter, R as RenderCorpusToInstructionsOptions, D as DefinePersonaInput, m as Persona, n as RunPersonifiedOptions, o as ShapeRegistry, p as LoopShape, E as EqualKArm, q as EqualKOnCostOptions, r as EqualKVerdict, T as TrajectoryReportOptions, s as TrajectoryReport, t as DeliverableSpec } from './worktree-fanout-gNfl0Byj.js';
+export { A as AuthoredHarness, u as DefinePersona, v as EqualKOnCost, w as Fanout, x as FanoutSynthesis, y as FlatWidenGate, z as LoopUntil, B as LoopUntilState, G as Panel, H as PanelJudge, I as PanelVerdict, J as PatchDeliverableOptions, K as PersonaContext, M as PersonaExecutors, N as Pipeline, Q as RenderCorpusToInstructions, U as RunPersonified, X as ShapeBudget, Y as ShapeContext, Z as TrajectoryNode, _ as TrajectoryReportFn, $ as Verify, a0 as Widen, a1 as WidenDecision, a2 as WidenLineage, a3 as WorktreeCliExecutorOptions, a4 as WorktreeCommandResult, a as WorktreeFanoutOptions, b as WorktreePatchArtifact, a5 as createWorktreeCliExecutor, a6 as gateOnDeliverable, a7 as patchDelivered, a8 as worktreeFanout } from './worktree-fanout-gNfl0Byj.js';
+import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
+import { A as AnalystRegistryLike } from './types-DJu6TBGp.js';
+import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
+import { R as RouterConfig, a as ToolLoopChat, T as ToolSpec } from './router-client-C7kp_ECN.js';
+export { b as RouterChatResult, c as RouterChatToolsResult, d as RouterToolCall, e as RouterToolLoopResult, r as routerBrain, f as routerChatWithTools, g as routerChatWithUsage, h as routerToolLoop } from './router-client-C7kp_ECN.js';
+import { stuckLoopView, toolWasteView } from '@tangle-network/agent-eval/pipelines';
 import 'node:child_process';
-import '@tangle-network/agent-eval/pipelines';
-import './coder-2leJPOvC.js';
-import './substrate-CUgk7F7s.js';
+import './substrate-BoRXgvka.js';
+
+/**
+ * @experimental
+ *
+ * Event-sourced spawn journal for the recursive execution atom (build steps 3 + 7).
+ *
+ * The supervision tree is journaled as an append-only event log: every `spawned`,
+ * `settled`, and `cancelled` is recorded AFTER it is observed-committed (never
+ * speculative), mirroring `ConversationJournal`'s begin/append/load shape. The log
+ * holds only the THIN decision record — ids, parentage, budget, the spend a decision
+ * consumed, and a content-addressed `outRef`. The payloads the driver branched on
+ * (the `out` artifacts) live in a separate `ResultBlobStore`, keyed by `outRef`, so
+ * the journal stays small (decisions) and replay rehydrates the exact `Settled` from
+ * the blob store (evidence). This is the decision/payload split the replay argument
+ * rests on (B1/B2).
+ *
+ * Replay determinism (B2): `seq` is the monotonic cursor order `scope.next()` yielded
+ * each settlement — NOT wall-clock. `replaySpawnTree` sorts strictly by `seq` before
+ * touching the blob store, so the order in which rehydration `get`s resolve can never
+ * reorder the replayed `Settled[]`; the result is identical regardless of blob latency.
+ */
+
+/**
+ * Mint the content-addressed `outRef` for a result artifact: `sha256:<hex>` over a
+ * stable JSON encoding. Producers call this to derive the `outRef` they journal and
+ * `put`; the FS/in-mem stores re-derive it on `put` to verify the supplied ref
+ * matches (fail loud on a mismatch — a forged ref breaks the replay invariant).
+ *
+ * Stable encoding: object keys are sorted recursively so two structurally-equal
+ * artifacts hash identically regardless of key insertion order.
+ */
+declare function contentAddress(artifact: unknown): string;
+/**
+ * In-memory `ResultBlobStore`. Content-addressed: `put` verifies the supplied
+ * `outRef` matches the artifact's hash so a stale/forged ref fails loud rather than
+ * silently rehydrating the wrong payload. Idempotent on an identical re-put.
+ */
+declare class InMemoryResultBlobStore implements ResultBlobStore {
+    private readonly blobs;
+    put(outRef: string, artifact: unknown): Promise<void>;
+    get(outRef: string): Promise<unknown | undefined>;
+}
+/**
+ * In-memory `SpawnJournal`. Appends are observed-committed only; the impl enforces
+ * the corruption guards a durable replay rests on:
+ *  - an event before `beginTree` is a corrupted tree (fail loud),
+ *  - a duplicate `seq` within a tree is a corrupted cursor (fail loud) — two
+ *    settlements cannot share the cursor position replay orders by.
+ */
+declare class InMemorySpawnJournal implements SpawnJournal {
+    private readonly trees;
+    loadTree(root: NodeId): Promise<SpawnEvent[] | undefined>;
+    beginTree(root: NodeId, at: string): Promise<void>;
+    appendEvent(root: NodeId, ev: SpawnEvent): Promise<void>;
+}
+
+/**
+ * createWaterfallCollector — 100% trajectory observability from the lifecycle stream:
+ * every spawn/settle (shots, analysts, nested agents) becomes one timed, billed span.
+ * The sum of spans IS the run's cost story — what each step cost in dollars, tokens,
+ * and wall-clock, rendered as a text waterfall or exported as structured rows for any
+ * chart. Attach the collector's `hooks` to `runAgentic`/`runBenchmark`; spans accumulate
+ * across every task the hooks observe.
+ */
+
+interface WaterfallSpan {
+    id: string;
+    /** The spawn label (`shot:0`, `analyst:1`, a nested agent's label) — the row name. */
+    label: string;
+    runId: string;
+    parentId?: string;
+    startMs: number;
+    endMs?: number;
+    status: 'running' | 'done' | 'down';
+    usd: number;
+    tokens: {
+        input: number;
+        output: number;
+    };
+    score?: number;
+}
+interface WaterfallReport {
+    spans: WaterfallSpan[];
+    /** Wall-clock of the observed window (first spawn → last settle). */
+    totalMs: number;
+    totalUsd: number;
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    /** Rollup by label prefix (the part before ':') — shots vs analysts vs anything else. */
+    byKind: Record<string, {
+        count: number;
+        ms: number;
+        usd: number;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+interface WaterfallCollector {
+    /** Attach these to RunAgenticOptions.hooks / BenchmarkConfig.hooks. */
+    hooks: RuntimeHooks;
+    report(): WaterfallReport;
+    /** The text waterfall — one row per span, bars scaled to the observed window. */
+    render(opts?: {
+        width?: number;
+        maxRows?: number;
+    }): string;
+    reset(): void;
+}
+declare function createWaterfallCollector(): WaterfallCollector;
+
+/**
+ * anytimeReport — time-to-satisfactory-output metrics, derived entirely from the
+ * waterfall's spans (no new instrumentation): per task, the best-so-far score after each
+ * shot with its elapsed wall-clock and cumulative spend; per strategy, the standard
+ * anytime-optimization metrics:
+ *
+ *   TTT  time-to-target — elapsed ms until best-so-far ≥ the target (per task; median
+ *        over tasks that reached it)
+ *   STT  shots-to-target — attempts until best-so-far ≥ target
+ *   ERT  expected running time (the COCO benchmarking convention): TOTAL time spent
+ *        across all tasks — including failures' full budgets — divided by the number of
+ *        tasks that reached the target. The honest "how long per success, all-in".
+ *   AUC  the anytime curve's area (mean best-so-far score across the budget, per shot
+ *        index) — higher = climbs earlier.
+ *
+ * The "satisfactory" bar follows the COCO/BBOB convention: a SET of satisficing targets
+ * (e.g. [0.5, 0.8, 1.0] on the normalized check score), each measured independently —
+ * runtime-to-target per (task, target) pair — optionally overridden per task
+ * (`targetFor`) when satisfaction is task-specific. Spans come from
+ * `createWaterfallCollector().report()`; tasks are grouped by the supervisor runId
+ * (`agentic:<strategy>:<taskId>`); shot spans are `shot:N` labels.
+ */
+
+interface AnytimeTaskCurve {
+    taskId: string;
+    strategy: string;
+    /** Best-so-far after each settled shot: elapsed ms from the task's first spawn,
+     *  cumulative usd, and the running max score. */
+    points: Array<{
+        elapsedMs: number;
+        cumUsd: number;
+        best: number;
+    }>;
+    /** Per satisficing target (keyed by the target value as a string): the first point
+     *  where best ≥ target, or null when never reached within budget. */
+    hits: Record<string, {
+        ms: number;
+        shots: number;
+        usd: number;
+    } | null>;
+}
+interface AnytimeStrategySummary {
+    strategy: string;
+    /** The satisficing target this row summarizes. */
+    target: number;
+    tasks: number;
+    reachedTarget: number;
+    /** Median time-to-target over the tasks that reached it (null when none did). */
+    medianTttMs: number | null;
+    medianShotsToTarget: number | null;
+    /** COCO ERT: Σ all task wall-time (incl. failures) / #successes. Null when 0 succeed. */
+    ertMs: number | null;
+    /** Same construction over dollars: Σ all spend / #successes. */
+    erUsd: number | null;
+    /** Mean best-so-far score by shot index (the anytime curve, averaged over tasks). */
+    curveByShot: number[];
+    /** Area under the per-shot anytime curve, normalized to [0,1]. */
+    auc: number;
+}
+interface AnytimeReport {
+    targets: number[];
+    perTask: AnytimeTaskCurve[];
+    /** One summary per (strategy, target) pair — the COCO-style multi-target view. */
+    perStrategy: AnytimeStrategySummary[];
+}
+/** Derive anytime metrics from waterfall spans. `targets` are the satisficing score
+ *  bars (default [1] = fully resolved; COCO-style multi-target: [0.5, 0.8, 1]);
+ *  `targetFor` overrides the bar per task (task-specific satisfaction) — when set, the
+ *  per-task bar replaces every entry of `targets` for that task. */
+declare function anytimeReport(spans: WaterfallSpan[], opts?: {
+    targets?: number[];
+    targetFor?: (taskId: string) => number;
+}): AnytimeReport;
+/** One row per (strategy, satisficing target): the shareable time-to-satisfactory table. */
+declare function renderAnytimeTable(report: AnytimeReport): string;
+
+/**
+ * auditIntent — the route-rigor analyst: is this trajectory even going the RIGHT WAY?
+ *
+ * `observe()` critiques execution quality ("what's unfinished"). This audits ALIGNMENT —
+ * a different failure class the score can't see until it's too late: an agent can be
+ * executing flawlessly down the wrong route. The auditor reads the trajectory and
+ * compares three intents:
+ *
+ *   declared  — what the task says to do (the prompt / acceptance criteria)
+ *   revealed  — what the agent is ACTUALLY optimizing, inferred from its action pattern
+ *               (the inverse-inference move: actions reveal objectives)
+ *   user      — what the principal actually wants (the contract, when it differs from
+ *               the literal task text), plus where the user's own trajectory is heading
+ *
+ * and returns a verdict (aligned / drifting / diverged) with evidence and ONE
+ * recommended intervention. FIREWALLED like every analyst: input is the trajectory and
+ * the intents — never the verifier or its data (zero check-leakage, so route auditing
+ * is always Goodhart-safe to run online).
+ *
+ * Where it runs: between shots (steer the next one), as a watchdog over the lifecycle
+ * stream (abort-and-refund a diverged rollout — the budget pool makes early abort
+ * strictly valuable), or post-hoc over a whole BenchmarkReport (the meta-intent pass:
+ * is the LOOP optimizing the right thing — degenerate submissions, check-gaming shapes,
+ * objective drift across tasks).
+ */
+
+interface AuditIntentInput {
+    /** The declared intent: the task text / acceptance criteria the agent was given. */
+    declaredIntent: string;
+    /** The trajectory so far — tool calls + results + assistant turns (any event shapes). */
+    trace: ReadonlyArray<unknown>;
+    /** The principal's actual intent when it differs from the literal task (the contract). */
+    userIntent?: string;
+    /** The loop-level purpose (meta-intent): what the WHOLE run is for — lets the auditor
+     *  flag locally-sensible work that serves the wrong larger objective. */
+    metaIntent?: string;
+    runId?: string;
+}
+interface AuditIntentOptions {
+    chat: ChatClient;
+    model?: string;
+    /** Override the auditor instruction (optimizable like any analyst prompt). */
+    auditorInstruction?: string;
+    /** Cap trace lines fed to the auditor. Default 80. */
+    maxTraceLines?: number;
+    signal?: AbortSignal;
+}
+interface IntentAudit {
+    /** What the agent's actions reveal it is actually optimizing — one sentence. */
+    revealedIntent: string;
+    verdict: 'aligned' | 'drifting' | 'diverged';
+    /** Trajectory-grounded evidence for the verdict (specific calls/patterns). */
+    evidence: string;
+    /** The single recommended intervention. */
+    recommendation: 'continue' | 'steer' | 'abort';
+    /** When recommendation is 'steer': the corrective instruction to inject. */
+    steer?: string;
+    confidence: number;
+}
+declare const defaultAuditorInstruction: string;
+declare function auditIntent(input: AuditIntentInput, opts: AuditIntentOptions): Promise<IntentAudit>;
+
+/**
+ * @experimental
+ *
+ * Completion / satisfiability — the OTHER output of the pluggable analyst (the steer output
+ * is `AnalystFinding[]` via the `analyze` hook; this is the "is it done?" output via the
+ * `complete` hook). A `CompletionAnalyst` reads a node's trace and returns a `CompletionVerdict`
+ * the PARENT (driver) acts on: end the node, or keep going. It fits ANY node and composes to
+ * any depth — a 1-deep loop has one; an N-deep tree has one per node.
+ *
+ * The verdict's authority scales with its DETERMINISM (the thing that varies by task):
+ *   - `deterministic` — build/test/lint pass, a proof checks, every claim's citation resolves:
+ *     ground truth, the driver TRUSTS it and ends. Not an opinion.
+ *   - `probabilistic` — a quality/soundness judgment (marketing, "the experiment is sound"):
+ *     ADVISORY. It passes to the driver with its reasons; the driver validates (here: a
+ *     confidence threshold; a richer driver may re-examine the reasons) before ending.
+ *
+ * Two stop-signal mechanisms, by node mode, both → one `CompletionVerdict`:
+ *   - sandbox-agent (text stream): a unique per-node STOP SENTINEL the agent emits when done
+ *     (`stopSentinel` / `sentinelCompletion`) — ralph-loop style; the seed makes it
+ *     unguessable + attributable, so it can't be spuriously emitted or confused with content.
+ *   - deterministic check (compile/test/citation/proof): `deterministicCompletion(check)` —
+ *     a verifier over the output, never the judge verdict (selector ≠ judge holds).
+ */
+
+/** Trace-derived evidence for a completion claim — an artifact (output) or a verifier metric,
+ *  never the judge's own verdict. Mirrors the steer-firewall's provenance discipline. */
+interface CompletionEvidence {
+    kind: 'artifact' | 'metric';
+    uri: string;
+}
+/** The "is it done?" verdict an analyst returns to the parent. */
+interface CompletionVerdict {
+    done: boolean;
+    /** How verifiable the claim is — sets whether the driver trusts it or validates it. */
+    determinism: 'deterministic' | 'probabilistic';
+    /** Why the analyst believes it is (or isn't) done — what the driver validates. */
+    reasons?: string;
+    /** 0..1, for probabilistic verdicts; the driver's validation threshold reads this. */
+    confidence?: number;
+    evidence?: ReadonlyArray<CompletionEvidence>;
+}
+/** Reads a node's trace → a completion verdict. Same input shape as the `analyze` hook, so
+ *  ONE analyst node can back both channels (findings for steer, a verdict for stop). */
+interface CompletionAnalyst<Task, Output> {
+    assess(input: {
+        task: Task;
+        history: ReadonlyArray<Iteration<Task, Output>>;
+    }): CompletionVerdict | Promise<CompletionVerdict>;
+}
+/** When a verdict authorizes the driver to END. Deterministic → trust (ground truth);
+ *  probabilistic → validate by confidence threshold (the driver's check). */
+interface CompletionPolicy {
+    /** Minimum confidence a PROBABILISTIC verdict must clear to end. Default 0.8. */
+    minConfidence?: number;
+}
+declare function completionAuthorizes(v: CompletionVerdict, policy?: CompletionPolicy): boolean;
+/**
+ * A unique, attributable stop sentinel for a node (ralph-loop style). Deterministic from the
+ * seed (no Math.random — reproducible + attributable to the node); the agent is instructed to
+ * emit it VERBATIM when it judges itself done. Unguessable enough that content never trips it.
+ */
+declare function stopSentinel(seed: string): string;
+/**
+ * Completion for a sandbox-agent node: done iff the latest output carries the node's stop
+ * sentinel. PROBABILISTIC (the agent's own self-judgment) — the driver validates it.
+ */
+declare function sentinelCompletion<Task>(sentinel: string, opts?: {
+    confidence?: number;
+}): CompletionAnalyst<Task, string>;
+/**
+ * Completion for a DETERMINISTIC check (build/test/lint/citation/proof): done iff the check
+ * passes. Ground truth — the driver ends directly, no validation. The check reads the output
+ * (a verifier), never the judge verdict — selector ≠ judge stays intact.
+ */
+declare function deterministicCompletion<Task, Output>(check: (output: Output, history: ReadonlyArray<Iteration<Task, Output>>) => {
+    passed: boolean;
+    reasons?: string;
+}): CompletionAnalyst<Task, Output>;
+
+/**
+ * The third-person observer — the connective tissue that closes the loop.
+ *
+ * A driver spawns a worker; the worker can't see itself. `observe` reads the
+ * worker's TRACE (what it actually did — every tool call, cost, failure) and
+ * produces two streams:
+ *   - `findings` / `report` — fed back DOWN (a steer for the next attempt) and
+ *     OUT (the operator-facing "what I noticed + what to change").
+ *   - `learned` — durable facts written to the cross-run `Corpus` so the NEXT
+ *     run starts smarter (the continuous half of "continuous self-improvement").
+ *
+ * Findings are TRACE-derived, never JUDGE-derived (`derived_from_judge:false`):
+ * the observer reads behavior, never the acceptance verdict — the selector≠judge
+ * firewall (docs/learning-flywheel.md). The observer is harness-agnostic: it
+ * reads a trace + an output, so it watches opencode, codex, hermes, or a BYO
+ * agent identically.
+ */
+
+interface ObserveInput {
+    /** What the worker was asked to do. */
+    task: string;
+    /** What it produced (its final answer / artifact summary). */
+    output: string;
+    /** The worker's trace — any event array (sandbox events, tool-call records). */
+    trace: ReadonlyArray<unknown>;
+    /** Terminal status only (passed/failed/unknown) — NOT a judge score; the
+     *  observer never reads the verdict, it reads behavior. */
+    outcome?: 'passed' | 'failed' | 'unknown';
+    /** Provenance back to the run. */
+    runId?: string;
+}
+interface ObserveOptions {
+    /** The model-call seam (agent-eval `createChatClient`: router / cli-bridge / …). */
+    chat: ChatClient;
+    model?: string;
+    /** When set, learned facts are appended (idempotent) for the next run to read. */
+    corpus?: Corpus;
+    /** Tags written onto learned facts + used by the next run's corpus query. */
+    tags?: ReadonlyArray<string>;
+    signal?: AbortSignal;
+    /** Cap the trace lines fed to the observer (keeps the call cheap). Default 80. */
+    maxTraceLines?: number;
+    /** Override the analyst's system instruction — the prompt that turns a trace into
+     *  findings + recommended_actions. The analyst IS the steerer, so this is the knob a
+     *  prompt optimizer (GEPA) tunes. Omitted ⇒ the default observer instruction. The
+     *  firewall (trace-only, never the verdict) is structural (input has no score), so a
+     *  custom instruction cannot break it. */
+    analystInstruction?: string;
+}
+/** The default observer instruction — exported so an optimizer can seed its population. */
+declare const defaultAnalystInstruction: string;
+interface Observation {
+    findings: AnalystFinding[];
+    /** Facts persisted to the corpus (empty when no corpus was supplied). */
+    learned: CorpusRecord[];
+    /** Operator-facing markdown: what the observer noticed + what to change. */
+    report: string;
+}
+declare function observe(input: ObserveInput, opts: ObserveOptions): Promise<Observation>;
+/** Operator-facing report, split by who should act. The agent block is the
+ *  steer; the operator block is the advice. */
+declare function renderReport(findings: ReadonlyArray<AnalystFinding>): string;
+
+/**
+ * harvestCorpus — production traces → corpus, the G2 bridge (the playbook's step 6).
+ * The flywheel's write side, batched: run the firewalled `observe()` analyst over a
+ * stream of completed runs (yesterday's production traces, a benchmark's rollouts, a
+ * fleet's day) and accrete the trace-derived facts into the durable corpus.
+ *
+ * Store-agnostic by design: the caller maps its trace store's rows (a
+ * `ProductionTraceSink` ndjson, OTLP spans, RunRecords) to `ObserveInput` — task text,
+ * final output, the event trace, terminal outcome. The analyst reads BEHAVIOR only
+ * (the firewall is structural: the input carries no judge verdict), and corpus appends
+ * are idempotent on (claim + tags), so re-harvesting the same window is safe.
+ *
+ * The nightly product job is then three lines:
+ *   const runs = mapSinkRowsToObserveInputs(await readSink(yesterday))
+ *   const report = await harvestCorpus({ runs, chat, corpus, tags: ['gtm-agent'] })
+ *   log(report)   // runsObserved / findings / learned / failures
+ *
+ * NOTE on the read side: harvesting is safe and cheap; *injecting* facts back into runs
+ * is the measured danger zone — naive unconditional priming tested NEGATIVE (−11.6pp,
+ * context pollution; result now in .evolve/current.json + memory). Gate any priming design on its
+ * own A/B; the corpus's first consumers are operators and optimizers, not prompts.
+ */
+
+interface HarvestCorpusOptions {
+    /** The completed runs to analyze — map your store's rows to `ObserveInput`. */
+    runs: AsyncIterable<ObserveInput> | Iterable<ObserveInput>;
+    /** The model-call seam (agent-eval `createChatClient`). */
+    chat: ChatClient;
+    model?: string;
+    /** The durable corpus the facts accrete into. */
+    corpus: Corpus;
+    /** Tags written onto learned facts (the product/domain key the read side queries by). */
+    tags?: ReadonlyArray<string>;
+    /** Override the analyst instruction (the GEPA-tunable knob). */
+    analystInstruction?: string;
+    /** Runs analyzed in parallel. Default 4. */
+    concurrency?: number;
+    /** Hard cap on runs consumed from the stream (a cost guard for unbounded stores). */
+    maxRuns?: number;
+    signal?: AbortSignal;
+}
+interface HarvestFailure {
+    runId: string;
+    error: string;
+}
+interface HarvestReport {
+    runsObserved: number;
+    /** Total findings the analyst produced (including ones already known). */
+    findings: number;
+    /** NEW facts actually appended (idempotent dedup excludes re-learned ones). */
+    learned: number;
+    /** Per-run analysis failures — reported, never silently dropped. */
+    failures: HarvestFailure[];
+}
+declare function harvestCorpus(opts: HarvestCorpusOptions): Promise<HarvestReport>;
+
+/**
+ * Adapt an `ExecutorFactory` into a `SandboxClient` for `runLoop`. The factory is
+ * instantiated fresh per `streamPrompt` (mirrors the per-spawn executor lifecycle):
+ * run once on the prompt, emit the terminal result event, tear down.
+ */
+declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): SandboxClient;
+
+/**
+ * @experimental
+ *
+ * `runLoop` — the topology-agnostic kernel built atop the sandbox SDK.
+ *
+ * Each iteration:
+ *   1. `driver.plan(task, history)` → N tasks (1 = refine, N = fanout, 0 = stop)
+ *   2. For each task (parallel, bounded by `maxConcurrency`):
+ *        a. round-robin an `AgentRunSpec` from `agentRuns`
+ *        b. `sandboxClient.create({ backend: { profile }, ...overrides })`
+ *        c. emit `loop.iteration.dispatch` with the placement
+ *           (`{ sibling, sandboxId }` or `{ fleet, fleetId, machineId, sandboxId }`)
+ *        d. iterate `box.streamPrompt(taskToPrompt(task))` and collect events
+ *   3. `output.parse(events)` → typed `Output`
+ *   4. `validator?.validate(output)` → `DefaultVerdict`
+ *   5. Append `Iteration` to history; emit `loop.iteration.ended`
+ *   6. `driver.decide(history)` → if terminal, return result + winner
+ *
+ * The kernel owns: iteration accounting, per-iteration timing, error
+ * capture, abort propagation, concurrency cap, cost aggregation, and trace
+ * emission. The kernel does NOT own: what the agent runs (sandbox SDK +
+ * profile), how outputs are decoded (output adapter), how outputs are
+ * scored (validator), or topology (driver).
+ */
+
+/** @experimental */
+interface RunLoopOptions<Task, Output, Decision> {
+    driver: Driver<Task, Output, Decision>;
+    /**
+     * Single agent spec — every iteration uses this profile. Mutually
+     * exclusive with `agentRuns`.
+     */
+    agentRun?: AgentRunSpec<Task>;
+    /**
+     * Multiple specs for heterogeneous fanout. The kernel round-robins
+     * through them when the driver plans N tasks. Mutually exclusive with
+     * `agentRun`.
+     */
+    agentRuns?: AgentRunSpec<Task>[];
+    output: OutputAdapter<Output>;
+    validator?: Validator<Output>;
+    task: Task;
+    ctx: ExecCtx;
+    /** Default 10. Hard cap on total iterations across all `plan()` rounds. */
+    maxIterations?: number;
+    /** Default 4. In-flight worker cap within a single `plan()` batch. */
+    maxConcurrency?: number;
+    /**
+     * Pre-allocated id for trace correlation. Default = `loop-${random}`.
+     * Surfaces as `runId` on every emitted `LoopTraceEvent`.
+     */
+    runId?: string;
+    /**
+     * Clock override; default `Date.now`. Deterministic tests pass a
+     * monotonic counter to stabilize iteration timing fields.
+     */
+    now?: () => number;
+    /**
+     * Override the default winner selector (highest-valid-score, ties broken
+     * by earliest iteration).
+     */
+    selectWinner?: (iterations: Iteration<Task, Output>[]) => LoopWinner<Task, Output> | undefined;
+    /**
+     * Same-sandbox driver mode — a kernel→caller out-channel, not a value handed
+     * in. When set, the kernel keeps each finished worker box alive across the
+     * `plan()` boundary and hands it here, so a same-sandbox planner
+     * (one that reuses the worker's box) can stream its move INTO the
+     * worker's live box — steering from the worker's real filesystem and state,
+     * not just a history summary. The kernel owns teardown: every box kept alive
+     * this way is destroyed at loop end (and the callback is invoked with
+     * `undefined` then as a teardown sentinel). Without it, worker boxes are torn
+     * down per-iteration (default) and a same-sandbox planner has nothing to
+     * reuse. Intended for single-worker (refine) loops: under fanout every box is
+     * still kept for teardown, but only the last-finishing box is handed here, so
+     * a planner sees an arbitrary branch's filesystem — pair it with refine.
+     */
+    onWorkerBox?: (box: SandboxInstance | undefined) => void;
+    /**
+     * Opt-in box-lineage controls. Default OFF — unset means every iteration
+     * acquires a fresh box, streams once, and tears it down (today's behavior,
+     * byte-identical). With `sessionContinuity` on, a refine round continues the
+     * parent iteration's session on its live box; with `forkFanout` on (and a
+     * fork-capable platform), a fanout round forks the parent's checkpoint so the
+     * branches share a context prefix. The lineage owns every box it starts or
+     * forks and tears them all down at loop end — so these paths are mutually
+     * exclusive with `onWorkerBox`, which claims the same box-ownership channel.
+     * @experimental
+     */
+    lineage?: LoopLineageOptions;
+}
+/** @experimental */
+declare function runLoop<Task, Output, Decision>(options: RunLoopOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
+/**
+ * The kernel's winner argmax — best-valid-score, ties broken by earliest index,
+ * falling back to the best-scoring non-errored output when none is valid. Exported
+ * so the `runProgram` tree executor selects across merged sub-loop iterations with
+ * the SAME semantics the kernel uses at a single loop's finalize (one selector, not
+ * a forked copy).
+ */
+declare function defaultSelectWinner<Task, Output>(iterations: Iteration<Task, Output>[]): LoopWinner<Task, Output> | undefined;
+
+/**
+ * `loopDispatch` — turn `runLoop` into an agent-eval campaign dispatch.
+ *
+ * Without this adapter a consumer wiring `runLoop` into `runProfileMatrix` /
+ * `runCampaign` has to, by hand, every time: (a) build an `ExecCtx` with a
+ * sandbox client, (b) adapt the campaign `DispatchContext.trace` into a
+ * `LoopTraceEmitter` (or lose all loop trace correlation), and (c) remember to
+ * forward the loop's cost + tokens via `ctx.cost` (forgetting it yields a
+ * `{0,0}` cell the backend-integrity guard reads as a stub). Three foot-guns,
+ * the third silent. The fleet's products skipped (c) and fell back to a
+ * `workerRecords[]` side-channel — the exact anti-pattern the substrate exists
+ * to kill.
+ *
+ * `loopDispatch` collapses all three into one typed call:
+ *
+ *   const dispatch = loopDispatch({
+ *     sandboxClient,
+ *     toLoopOptions: (scenario, profile) => ({ driver, agentRun, output, validator, task }),
+ *   })
+ *   await runProfileMatrix({ profiles, scenarios, dispatch, judges, commitSha })
+ *
+ * Usage is reported automatically; trace events are forwarded automatically;
+ * the ctx is built automatically. The seam becomes impossible to mis-wire.
+ *
+ * Typed structurally against the campaign `DispatchContext` (imported type-only
+ * from `@tangle-network/agent-eval/campaign`) — a downward dependency, never an
+ * inversion.
+ */
+
+/** runLoop options minus the `ctx` (loopDispatch builds the ctx). */
+type LoopOptionsForDispatch<Task, Output, Decision> = Omit<RunLoopOptions<Task, Output, Decision>, 'ctx'>;
+interface LoopDispatchOptions<Task, Output, Decision, TScenario extends Scenario, TArtifact> {
+    /** Sandbox client used for every cell's `runLoop`. Supplied once. */
+    sandboxClient: SandboxClient;
+    /** Build the per-cell runLoop options from the scenario (+ profile, when
+     *  used with `runProfileMatrix`). */
+    toLoopOptions: (scenario: TScenario, profile: AgentProfile) => LoopOptionsForDispatch<Task, Output, Decision>;
+    /** Map the finished loop to the artifact the judges score. Default:
+     *  `result.winner?.output`. A loop with no winner yields `undefined` (judges
+     *  skip the cell) — but the loop's token usage is STILL reported, so the
+     *  integrity guard sees real activity. */
+    toArtifact?: (result: LoopResult<Task, Output, Decision>) => TArtifact;
+    /** Forward `loop.*` trace events into the campaign's scoped trace so loop
+     *  spans correlate with the cell. Default true. */
+    forwardTrace?: boolean;
+    /** Cost-meter source label for the loop's spend. Default `'loop'`. */
+    costSource?: string;
+}
+/**
+ * Adapter for `runProfileMatrix` (profile is an axis). Returns a
+ * `ProfileDispatchFn` that runs `runLoop` per (profile, scenario) cell and
+ * reports usage automatically.
+ */
+declare function loopDispatch<Task, Output, Decision, TScenario extends Scenario, TArtifact>(opts: LoopDispatchOptions<Task, Output, Decision, TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
+
+/**
+ * The general agentic primitive — sequential (depth) and parallel (breadth) over a shared,
+ * checkable artifact, driven through the keystone Supervisor as one recursive `Agent.act`.
+ *
+ * The domain lives behind ONE seam — `AgenticSurface` (open an artifact, list tools, call a tool,
+ * score the artifact, close it). EnterpriseOps implements it (seed a gym DB, MCP tools, SQL
+ * verifier); Commit0/AppWorld/terminal-bench implement it the same way (a repo workspace, shell
+ * tools, the test suite). The drivers below are domain-blind: they run over any surface.
+ *
+ * Two shapes, the agent's POMDP rollout as the unit:
+ *  - DEPTH   one persistent artifact carried across shots. Each shot the agent works the tool loop;
+ *            between shots a trace-analyst (selector≠judge: reads the trajectory, never the score)
+ *            steers the resumed session toward what's unfinished. shot n stands on shot n-1's
+ *            artifact state + history. This is continuation — long-horizon, same artifact.
+ *  - BREADTH K independent artifacts, each a fresh rollout, the deployable verifier picks the best.
+ *
+ * Both are an `Agent` whose `act` spawns leaf shots through `scope.spawn` and reacts via
+ * `scope.next()` — so the conserved budget pool meters them (equal-k by construction), the journal
+ * records the tree, and the same primitive nests. `runAgentic` runs the chosen driver through
+ * `createSupervisor().run`. The leaf (one shot over a handle) is resolved per-spawn from a
+ * surface-closed registry — the open `Executor` seam, not bespoke per-benchmark glue.
+ */
+
+interface AgenticTask {
+    readonly id: string;
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    /** Opaque domain payload the surface reads (EOPS: servers/verifiers/tools). Drivers never read it. */
+    readonly meta?: Record<string, unknown>;
+}
+interface ArtifactHandle {
+    readonly id: string;
+    readonly surface: string;
+    /** Opaque per-artifact context the surface stashes (EOPS: the seeded gym server + db id). */
+    readonly ctx?: unknown;
+}
+interface AgenticTool {
+    readonly type: 'function';
+    readonly function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface SurfaceScore {
+    passes: number;
+    total: number;
+    /** Checks excluded as malformed (data defect, not the agent). `total === 0` ⇒ unscoreable. */
+    errored: number;
+}
+/** A stateful, checkable environment an agent operates over with tools. Open behind one interface. */
+interface AgenticSurface {
+    readonly name: string;
+    open(task: AgenticTask): Promise<ArtifactHandle>;
+    tools(task: AgenticTask, handle: ArtifactHandle): Promise<AgenticTool[]>;
+    call(handle: ArtifactHandle, name: string, args: Record<string, unknown>): Promise<string>;
+    score(task: AgenticTask, handle: ArtifactHandle): Promise<SurfaceScore>;
+    close(handle: ArtifactHandle): Promise<void>;
+}
+interface AgenticOptions {
+    routerBaseUrl: string;
+    routerKey: string;
+    model: string;
+    temperature?: number;
+    /** Completion cap per worker turn — REQUIRED for thinking models (they burn unbounded
+     *  budgets on reasoning and return empty content without it). Omitted ⇒ provider default. */
+    maxTokens?: number;
+    /** Turns the agent may take within ONE shot before the driver intervenes. */
+    innerTurns?: number;
+    /** The depth STEERER's analyst instruction (observe()'s system prompt). The knob a
+     *  prompt optimizer (GEPA) tunes — the analyst IS the steerer. Omitted ⇒ the default. */
+    analystInstruction?: string;
+    /** The critic's model — lets the analyst be a stronger (or cheaper) model than the
+     *  worker. Omitted ⇒ the worker's `model`. */
+    analystModel?: string;
+    /** Across-run learning: when set, the analyst's observe() pass appends trace-derived
+     *  facts here (the flywheel write side). Priming (the read side) is the caller's move —
+     *  query the corpus and fold facts into the task's systemPrompt before runAgentic. */
+    corpus?: Corpus;
+    /** Tags written onto learned facts (and used by the caller's priming query). */
+    corpusTags?: string[];
+}
+type Msg = Record<string, unknown>;
+interface ShotResult {
+    messages: Msg[];
+    score: number;
+    passes: number;
+    total: number;
+    completions: number;
+    toolErrors: number;
+}
+interface AgenticRunResult {
+    /** The strategy name (built-in 'depth'/'breadth' or a custom strategy's name). */
+    mode: string;
+    score: number;
+    resolved: boolean;
+    completions: number;
+    /** DEPTH: score after each shot — the progress-over-rounds curve. BREADTH: best-so-far per rollout. */
+    progression: number[];
+    shots: number;
+    /** The cost vector, stamped by `runAgentic` from the Supervisor's conserved pool: real
+     *  router tokens, priced usd (0 when the model is unpriced — never fabricated), wall ms. */
+    usd: number;
+    ms: number;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+/** DEPTH: one persistent artifact, carried across analyst-steered shots. */
+declare function depthStrategy(surface: AgenticSurface, task: AgenticTask, opts: AgenticOptions, cfg: {
+    maxShots: number;
+}): Agent<unknown, Outcome<unknown>>;
+/** BREADTH: K independent rollouts (each own artifact), verifier picks the best. */
+declare function breadthStrategy(_surface: AgenticSurface, task: AgenticTask, opts: AgenticOptions, cfg: {
+    width: number;
+}): Agent<unknown, Outcome<unknown>>;
+/**
+ * A Strategy is HOW you spend the compute budget to beat the Environment's check — it
+ * builds the driver `Agent` the Supervisor runs. This is the OPEN extension point: a dev
+ * authors their own by implementing `driver()` to return an Agent whose `act()` spawns
+ * shots/analysts via `scope.spawn` / `scope.next` / `scope.send`. The two built-ins are
+ * the reference implementations to copy:
+ *   sample — K INDEPENDENT attempts, keep the best-verifying (best-of-N / resample).
+ *   refine — attempt → observe() reads the trace → steer the next → repeat (iterate).
+ * (A multi-agent "team" is just a Strategy whose driver spawns several different agents.)
+ */
+interface Strategy {
+    readonly name: string;
+    driver(surface: AgenticSurface, task: AgenticTask, opts: AgenticOptions, budget: number): Agent<unknown, Outcome<unknown>>;
+}
+declare const sample: Strategy;
+declare const refine: Strategy;
+/** A role for one shot — multi-agent loops (researcher + engineer, a panel of k
+ *  researchers) give each shot its own system prompt and optionally its own model. */
+interface ShotPersona {
+    /** Replaces the task's systemPrompt for a FRESH shot; on a carried conversation it is
+     *  injected as a hand-off message (the transcript's earlier roles stay intact). */
+    systemPrompt?: string;
+    /** Per-shot model override (e.g. a stronger model for the engineer shot). */
+    model?: string;
+}
+interface ShotSpec {
+    /** present ⇒ continue this artifact (depth); absent ⇒ the shot opens a fresh one (sample/restart). */
+    handle?: ArtifactHandle;
+    messages?: Msg[];
+    steer?: string;
+    persona?: ShotPersona;
+    /** Restrict THIS shot to a subset of the domain's tools (by name) — focus a shot on
+     *  the relevant capabilities. Restriction-only; unknown names throw. Omitted ⇒ all. */
+    tools?: string[];
+}
+interface StrategyResult {
+    score: number;
+    resolved: boolean;
+    completions: number;
+    progression: number[];
+    shots: number;
+}
+/** Artifact lifecycle a strategy may manage itself — open/close ONLY. Raw `call`/`score`
+ *  are withheld: scores reach the body solely through `shot()`'s ShotResult (the
+ *  harness-verified channel), so a body cannot peek the check or fabricate around it. */
+interface StrategyArtifacts {
+    readonly name: string;
+    open(task: AgenticTask): Promise<ArtifactHandle>;
+    close(handle: ArtifactHandle): Promise<void>;
+}
+/** What a strategy body composes with: the artifact lifecycle, the budget, and the two steps. */
+interface StrategyCtx {
+    /** Open/close artifacts the body manages itself (e.g. one persistent handle for depth). */
+    readonly surface: StrategyArtifacts;
+    readonly task: AgenticTask;
+    readonly opts: AgenticOptions;
+    readonly budget: number;
+    readonly scope: Scope<Outcome<unknown>>;
+    /** Run ONE worker shot; its harness-scored result, or null if it went down. */
+    shot(spec?: ShotSpec): Promise<ShotResult | null>;
+    /** The firewalled critic reads the trajectory → a steer string, or null on COMPLETE/down. */
+    critique(messages: Msg[]): Promise<string | null>;
+    /** The RAW analyst channel: the firewalled critic answers `instruction` over the
+     *  trajectory verbatim — no findings extraction, so verdict-shaped formats
+     *  (CONTINUE/STOP decisions, calibrated predictions) survive. Same firewall:
+     *  trajectory in, never scores. Null when the analyst went down. */
+    consult(messages: Msg[], instruction: string): Promise<string | null>;
+    /** The tools THIS artifact's task actually offers (names + descriptions only — never
+     *  the implementations). Tool sets vary per task on heterogeneous domains; a strategy
+     *  that restricts shots MUST select from this list, never from hardcoded names. */
+    listTools(handle: ArtifactHandle): Promise<Array<{
+        name: string;
+        description?: string;
+    }>>;
+}
+/** Author a Strategy from the composable steps — the open, compact way. */
+declare function defineStrategy(name: string, run: (ctx: StrategyCtx) => Promise<StrategyResult>): Strategy;
+/** A NEW strategy, authored from the steps (~20 lines): refine, but when a steered shot
+ *  fails to improve the score it ABANDONS that line and restarts fresh (branch-when-stuck)
+ *  — the widen/MCTS idea the depth-stuck failure motivated. Scored keep-best (the best
+ *  checkpoint across all lines), the deployable metric. This is the "experts build BETTER
+ *  optimizations" path: a new technique, compact, with zero Supervisor ceremony. */
+declare const adaptiveRefine: Strategy;
+/** The explore-then-exploit MIX: spend ⌈budget/2⌉ on independent samples (kept open),
+ *  then refine the best-verifying line with the remaining budget. Sample's basin escape +
+ *  refine's accumulation — the third built-in, authored from the public steps. */
+declare const sampleThenRefine: Strategy;
+interface RunAgenticOptions extends AgenticOptions {
+    surface: AgenticSurface;
+    task: AgenticTask;
+    /** Lifecycle observability — every spawn/settle (shots, analysts) streams here live.
+     *  The seam online watchdogs/route-auditors subscribe to. */
+    hooks?: RuntimeHooks;
+    /** A Strategy (the open way) — author/pass your own. Overrides `mode` when present. */
+    strategy?: Strategy;
+    /** Built-in shorthand: 'depth'→refine, 'breadth'→sample. Default 'depth'. */
+    mode?: 'depth' | 'breadth';
+    /** budget: refine→max shots; sample→rollout width. */
+    budget: number;
+    rootBudget?: Budget;
+}
+/** Run a Strategy through the keystone Supervisor — `Agent.act` over a conserved-budget Scope. */
+declare function runAgentic(opts: RunAgenticOptions): Promise<AgenticRunResult>;
+
+/**
+ * runBenchmark — the packaged optimization suite. Define a domain by implementing an
+ * `Environment` (open / tools / call / score / close); get the optimization strategies
+ * compared, scored by your own deployable check, with a paired-bootstrap report — free.
+ *
+ * The mental model: you have a TASK + a deployable CHECK + a compute BUDGET. A strategy
+ * is how you spend the budget to beat the check. Two built-ins:
+ *
+ *   sample  — N independent attempts, keep the best-verifying one.   (best-of-N / resample)
+ *   refine  — attempt → a critic reads the trace → steer the next → repeat. (iterate-with-feedback)
+ *
+ * Both run at equal budget through the Supervisor's conserved pool; the headline is the
+ * paired lift of refine over sample. Author your own strategy with `defineStrategy`.
+ */
+
+/** A checkable task domain — implement these 5 hooks and the suite does the rest. The
+ *  same seam as `AgenticSurface`; `Environment` is the RL/gym-standard name for it. */
+type Environment = AgenticSurface;
+interface BenchmarkConfig {
+    /** The task domain (5 hooks). */
+    environment: Environment;
+    /** The tasks to score across. */
+    tasks: AgenticTask[];
+    /** The worker: model + router + (optional) the critic's instruction (the steerer knob). */
+    worker: AgenticOptions;
+    /** Which strategies to compare. Pass the built-ins (`refine`, `sample`) or your own.
+     *  Default: [sample, refine]. */
+    strategies?: Strategy[];
+    /** Shots (refine) / width (sample) — the equal compute budget per strategy. Default 3. */
+    budget?: number;
+    /** Tasks scored in parallel. Default 3. */
+    concurrency?: number;
+    /** Progress hook — fires as each task settles (the live-monitoring seam: append to a
+     *  progress file, render a tree, stream to a dashboard). `done` counts settled tasks. */
+    onTask?: (row: BenchmarkTaskRow, done: number, total: number) => void;
+    /** Lifecycle observability — every spawn/settle of every cell's shots/analysts streams
+     *  here live (the watchdog/route-auditor seam, passed through to `runAgentic`). */
+    hooks?: RuntimeHooks;
+}
+interface BenchmarkLift {
+    /** Mean of paired deltas (refine − sample). */
+    mean: number;
+    low: number;
+    high: number;
+    n: number;
+}
+/** One strategy's outcome on one task — the per-task cell an optimizer consumes. */
+interface BenchmarkCell {
+    score: number;
+    resolved: boolean;
+    /** The progress curve (refine: score per shot; sample: best-so-far per rollout). */
+    progression: number[];
+    usd: number;
+    ms: number;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+interface BenchmarkTaskRow {
+    taskId: string;
+    /** Per-strategy cells; absent when the task errored before completing all strategies. */
+    cells?: Record<string, BenchmarkCell>;
+    /** Per-strategy failures on this task: the strategy competed, threw, and scored an
+     *  honest zero — it loses, it does not poison the row. The message is kept so a later
+     *  generation's author can see WHY a candidate died. */
+    errors?: Record<string, string>;
+    /** Why the task was excluded (infra/setup failure) — never silently dropped. */
+    error?: string;
+}
+interface BenchmarkStrategySummary {
+    /** Mean verifier score (0..1). */
+    score: number;
+    /** Fraction of tasks fully resolved. */
+    resolved: number;
+    /** Mean cost vector per task. */
+    usd: number;
+    ms: number;
+}
+interface BenchmarkReport {
+    n: number;
+    excluded: number;
+    /** Per-strategy means (keyed by strategy.name). */
+    perStrategy: Record<string, BenchmarkStrategySummary>;
+    /** The full per-task × per-strategy table — the LOSSES an optimizer (GEPA, a
+     *  strategy-author, an operator) consumes. Includes errored tasks with the reason. */
+    perTask: BenchmarkTaskRow[];
+    /** The non-dominated strategies on (score ↑, $/task ↓) — collapse-last, per the canon:
+     *  a strategy that ties on score at half the cost WINS and a scalar would hide it. */
+    pareto: string[];
+    /** The headline when both `refine` and `sample` ran: paired-bootstrap lift of refine over sample. */
+    refineVsSample?: BenchmarkLift;
+}
+/** Run the requested strategies over the tasks, scored by the Environment's own check.
+ *  Resilient: a task whose rollouts fail (transient infra) is excluded from the stats but
+ *  reported in `perTask` with the error — never silently dropped. */
+declare function runBenchmark(cfg: BenchmarkConfig): Promise<BenchmarkReport>;
+/** Pretty-print a report — the "free optimization" verdict, with the cost vector. */
+declare function printBenchmarkReport(report: BenchmarkReport): void;
+
+/**
+ * createMcpEnvironment — wrap any MCP server as an `Environment` (the product-adoption
+ * primitive: a product's agent tools are usually already an MCP surface, so the domain
+ * only writes the lifecycle hooks — open a scoped artifact, score it with a deployable
+ * check, close it — and the tool plumbing is derived from the server).
+ *
+ * What the helper owns (the generic 80%, hardened on the EnterpriseOps gym):
+ *   - JSON-RPC `tools/list` → `AgenticTool[]`, with schemas coerced to the
+ *     OpenAI-tool-valid shape (top-level oneOf/anyOf/allOf/enum/not are rejected by
+ *     tool-calling providers; nested combinators are fine).
+ *   - JSON-RPC `tools/call` → the tool's text content (errors surfaced as `ERROR: …`
+ *     strings — a bad call is the agent's outcome, not an infra fault).
+ *   - SSE response parsing (streamable-HTTP MCP servers answer with `data:` lines).
+ *   - Bounded retry with backoff on thrown fetches (transient network ≠ task failure).
+ *
+ * What the domain supplies: `open` (create/seed the per-task artifact and return its
+ * MCP endpoint — url + headers carry the per-artifact scoping, e.g. a database id
+ * header), `score` (the deployable check), and optional `close`/`selectTools`.
+ */
+
+/** Where a handle's MCP server lives; headers carry per-artifact scoping. */
+interface McpEndpoint {
+    url: string;
+    headers?: Record<string, string>;
+}
+interface McpEnvironmentOptions {
+    name: string;
+    /** Create/seed the per-task artifact; return its handle + the MCP endpoint scoped to it. */
+    open(task: AgenticTask): Promise<{
+        handle: ArtifactHandle;
+        endpoint: McpEndpoint;
+    }>;
+    /** The deployable check over the artifact's current state. */
+    score(task: AgenticTask, handle: ArtifactHandle): Promise<SurfaceScore>;
+    /** Teardown (delete the seeded artifact). Optional — omit for stateless servers. */
+    close?(handle: ArtifactHandle): Promise<void>;
+    /** Restrict/order the server's tools per task (e.g. the task's selected_tools). Default: all. */
+    selectTools?(task: AgenticTask, all: AgenticTool[]): AgenticTool[];
+    /** Cap on a tool result's text fed back to the worker. Default 1500 chars. */
+    maxResultChars?: number;
+}
+declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
+
+/**
+ * @experimental
+ *
+ * Analyst-on-scope (G1) — the analyze→findings→steer wire over the reactive `Scope`.
+ *
+ * The analyst runs over the children drained so far and hands its findings to the steer
+ * decision behind a provenance firewall (`assertTraceDerivedFindings`) that keeps the external
+ * write-only judge out of that decision (selector ≠ judge). The reactive `Scope` has no rounds:
+ * a combinator's `act` asks a `ScopeAnalyst` to turn the children it has drained off
+ * `scope.next()` SO FAR into `AnalystFinding[]`, and steers from THOSE findings through a single
+ * `SteerContext`.
+ *
+ * The analyst itself is not a new type — it is "just an `Agent<unknown, AnalystFinding[]>`" the
+ * combinator spawns over a child's trace (harness `null`/`cli`). `createScopeAnalyst` spawns that
+ * agent through `Scope.spawn` (so its compute is metered by the conserved pool like any child),
+ * drains its settlement, then enforces the firewall on the way out — a judge-derived finding
+ * ABORTS, it is never filtered. Fail loud: a down analyst, a non-array result, or a tainted finding
+ * throws; there is no silent empty-findings path that would let a combinator steer on nothing.
+ */
+
+declare const assertTraceDerivedFindings: AssertTraceDerivedFindings;
+/**
+ * The analyst run an `Agent<unknown, AnalystFinding[]>` performs over the children settled so far.
+ * The combinator supplies the analyst's task projection (how to frame the drained settlements as
+ * the analyst's input) — the analyst's `act` reads the trace and returns its raw findings; the
+ * firewall is enforced afterwards by `createScopeAnalyst`, not by the analyst itself.
+ */
+interface CreateScopeAnalystOptions<D> {
+    /** The analyst agent the combinator spawns over the trace. `harness` is the persona's choice
+     *  (`null` for an inline router analyst, a `BackendType` for a sandboxed one). Its `act` returns
+     *  the RAW findings; this module asserts the firewall on them before returning. */
+    readonly analyst: Agent<unknown, ReadonlyArray<AnalystFinding>>;
+    /** Build the analyst agent's task from the analyze input (the root-task framing + the children
+     *  drained so far). Pure projection — the analyst interprets it, this never reads it. */
+    buildTask(input: ScopeAnalyzeInput<D>): unknown;
+    /** The conserved budget reserved for one analyst spawn. The pool reserves against it and fails
+     *  closed; an analyst that cannot be admitted is a fail-loud abort, never silent empty findings. */
+    readonly budget: Budget;
+    /** Trace/journal label for the spawned analyst child. Default `'analyst'`. */
+    readonly label?: string;
+}
+/**
+ * Build a `ScopeAnalyst` that spawns the analyst agent through `Scope.spawn` (so its compute is
+ * metered by the conserved pool), drains its single settlement, and enforces the trace-derived
+ * firewall before returning. The `scope` is the SAME scope the combinator is draining its children
+ * from — the analyst is spawned as a sibling and its result is read off `scope.next()` in cursor
+ * order, replay-safe like any other child.
+ *
+ * Fail loud (no silent empty findings):
+ *  - the pool refuses the analyst spawn → `AnalystError` (the steer would otherwise run on nothing)
+ *  - the analyst settles `down` → `AnalystError` (a broken capture path, not a verdict)
+ *  - the analyst returns a non-array → `PlannerError`
+ *  - any finding cites judge-derived metric evidence → `PlannerError` via the firewall
+ */
+declare function createScopeAnalyst<D>(scope: Scope<Outcome<D>>, options: CreateScopeAnalystOptions<D>): ScopeAnalyst<D>;
+/**
+ * Project a `ScopeAnalyzeInput` into the `AnalystRegistry.run` arguments. The registry runs over a
+ * `runId` + `AnalystRunInputs` (a trace store / run record / artifact dir), NOT in-memory scope
+ * settlements — so the CALLER owns the projection from the combinator's drained children to the
+ * registry's inputs (e.g. the trace store the run already wrote). This adapter never invents that
+ * bridge; it only runs the projected inputs and firewalls the merged findings.
+ */
+interface RegistryAnalyzeProjection {
+    readonly runId: string;
+    readonly inputs: AnalystRunInputs;
+    /** Optional `run` opts (e.g. `priorFindings`) forwarded verbatim to the registry. */
+    readonly opts?: Parameters<AnalystRegistryLike['run']>[2];
+}
+/**
+ * A `ScopeAnalyst` backed by an `AnalystRegistry` — the panel-of-analysts seam. The registry merges
+ * N analyst KINDS into one `AnalystRunResult.findings`; `analyze` runs it over the caller-projected
+ * `{ runId, inputs }` and pipes the merged findings through the SAME `assertTraceDerivedFindings`
+ * firewall `createScopeAnalyst` uses (single-sourced selector≠judge). Distinct from `panel()`
+ * (judges-vs-one-artifact) — this is analysts-over-a-trace, the diagnosis side of the wire.
+ *
+ * Fail loud: a registry that throws propagates; a judge-derived finding aborts via the firewall.
+ * The projection is the caller's (`buildInputs`) — if the scope settlements do not cleanly map to
+ * the registry's `AnalystRunInputs`, that is a caller-side contract gap, surfaced there, not papered
+ * over with a fabricated input here.
+ */
+declare function registryScopeAnalyst<D>(registry: AnalystRegistryLike, buildInputs: (input: ScopeAnalyzeInput<D>) => RegistryAnalyzeProjection): ScopeAnalyst<D>;
+/**
+ * Build the `SteerContext` a combinator reads to steer (its `loopUntil.until`, `widen` gate, any
+ * future steer). One place enforces the firewall: `findings` is asserted trace-derived before it is
+ * surfaced, and `lastValidScore` is provided for OBSERVABILITY only — a combinator that steers off
+ * it re-introduces selector = judge, the coupling the architecture forbids.
+ *
+ * `findings` is re-asserted here even when it came from `createScopeAnalyst` (which already asserted
+ * it): the assertion is cheap and idempotent, and a `SteerContext` may be built from findings that
+ * arrived by another path (a caller-supplied diagnosis). Belt-and-suspenders on the one coupling
+ * that must never leak.
+ */
+declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, settledSoFar: ReadonlyArray<Settled<Outcome<D>>>): SteerContext<D>;
+
+/**
+ * @experimental
+ *
+ * The generic combinator library — the content-free act-bodies the wave's §1 contract froze.
+ *
+ * Each export is a `CombinatorShape<Task, D>` (an alias of `LoopShape<Task, D>`): a factory
+ * `(ShapeContext) => Agent<Task, Outcome<D>>` whose `act` runs ONE composition shape over the
+ * keystone `Scope` — spawn children through `ctx.spawnChild` + `scope.spawn`, drain settlements
+ * via `scope.next()`, select across `done` children with the SINGLE-SOURCED `settledToIteration`
+ * + `defaultSelectWinner` (selector≠judge — never a re-rank behind the driver), and synthesize a
+ * terminal `Outcome<D>`.
+ *
+ * The shapes carry NO domain: a "research sweep over angles" is `fanout(angles, { synthesize })`
+ * under a research persona; a "code build test" is `pipeline([plan, implement, integrate])` under
+ * a coder persona. The SHAPE is here; the model/prompt/role/goal live on the `Persona` + task,
+ * threaded to each child verbatim by the spec-objects the builders take. No model name, prompt,
+ * role, or domain noun appears below.
+ *
+ * Two fail-loud invariants every combinator honors: a child the conserved pool cannot admit is a
+ * CONCRETE blocker (never an eager over-fan, never a silent drop), and a `blocked` outcome always
+ * names at least one blocker (a shape that cannot finish MUST say why — `blocked([])` throws).
+ */
+
+/**
+ * The single content-free valid-only winner selector. Among the gated-VALID children only
+ * (`verdict.valid === true`), pick by `strategy` — best score / smallest delivered artifact /
+ * earliest — ties broken by earliest index; returns `undefined` when NONE is valid (an ungated
+ * output can never win — the deliverable gate is the point). `sizeOf` (for `'smallest-artifact'`)
+ * reads the child's settled deliverable — the raw value a leaf settles, or the unwrapped `Outcome<D>`
+ * a delegate path produces; a domain passes e.g. patch diff-lines. This is the de-duplicated home of
+ * the selection logic previously copied per role.
+ */
+declare function selectValidWinner<D>(opts?: {
+    strategy?: WinnerStrategy;
+    sizeOf?: (deliverable: D) => number;
+}): FanoutWinnerSelector<D>;
+/**
+ * `pipeline(stages)` — run the stages in order, feeding each stage's `done` deliverable into the
+ * next stage's task. The first stage that ends `blocked` (a child that went down, a child the
+ * pool would not admit, or a stage whose `collect` chose to block) short-circuits — its blockers
+ * ARE the pipeline's blockers, never coerced past a failed stage. The terminal stage's `done`
+ * deliverable is the pipeline's deliverable.
+ */
+declare function pipeline<Task, D>(stages: ReadonlyArray<PipelineStage<Task, unknown, unknown>>): CombinatorShape<Task, D>;
+/**
+ * `fanout(items, opts)` — spawn one child per item in a single round (bounded by the conserved
+ * pool's fail-closed admission), drain via `scope.next()`, then either synthesize over the
+ * gathered settlements (one SEPARATE synthesis child) or return the best-valid child via the
+ * single-sourced selector. A round that admitted zero children, or whose synthesis child could
+ * not be admitted, is a concrete blocker.
+ */
+declare function fanout<Task, Item, D>(items: ReadonlyArray<Item>, opts: FanoutOptions<Item, D>): CombinatorShape<Task, D>;
+/**
+ * `loopUntil(seed, spec)` — one `step` child per round; `fold` accumulates each settlement into
+ * the running state; `until` (reading the round's trace findings, NOT a fresh raw verdict) is
+ * the deployable stop. The conserved pool IS the loop bound: once `spawn` fails closed the loop
+ * stops. A loop that exhausted the pool without `until` ever satisfying is a concrete blocker.
+ *
+ * When `ctx.analyst` is set, each round runs it over the children settled so far and steers
+ * `until` on the resulting trace-derived findings (the analyst spawns into THIS scope, so its
+ * compute is conserved-pooled — equal-k holds by construction). Absent an analyst the findings
+ * argument is the empty array — never a fabricated finding (fail-loud honesty over a silent default).
+ */
+declare function loopUntil<Task, State, D>(seed: State, spec: LoopUntilSpec<Task, State, D>): CombinatorShape<Task, D>;
+/**
+ * `panel(spec)` — spawn the M judge children over the SAME artifact, drain their settlements,
+ * and fold them into a panel verdict via the pure WRITE-ONLY `merge` (a judge's output never
+ * reaches another judge's task; the merge never spawns or re-ranks). A `down` judge carries no
+ * verdict and is excluded from the merge denominator. A panel that admitted no judge is a
+ * concrete blocker before `merge` is consulted.
+ */
+declare function panel<Task, Artifact, D>(spec: PanelSpec<Artifact, D>): CombinatorShape<Task, D>;
+/**
+ * `verify(spec)` — an IMPLEMENT child produces a candidate, then a SEPARATE VERIFIER child grades
+ * it; only a `valid` verifier verdict ships. Any other outcome (implement down, verifier down,
+ * verifier verdict absent or not `valid`) is a concrete blocker carrying the failure verbatim —
+ * never a coerced "done". The implement child does not grade itself.
+ */
+declare function verify<Task, Candidate, D>(spec: VerifySpec<Task, Candidate, D>): CombinatorShape<Task, D>;
+/**
+ * `widen(spec)` — the streaming spawn-on-completion driver. Spawns the seed lineages, then REACTS
+ * to each `scope.next()`: on every settled child it consults `spec.gate.decide` and, when the gate
+ * returns `widen`, spawns AT MOST ONE more child toward the chosen lineage under the remaining
+ * conserved pool. `promising` is derived from the round's trace findings (the analyst seam),
+ * never a child's raw `verdict` — and the default gate (`flatWidenGate`) never widens, so the R2
+ * firewall stays dormant. Terminal selection is `spec.synthesize` over every settled lineage.
+ *
+ * When `ctx.analyst` is set, `decide` is consulted with that round's trace-derived findings;
+ * absent an analyst the findings argument is the empty array a flat gate ignores. The analyst
+ * spawns into THIS scope (conserved-pooled, so equal-k holds). Streaming caveat: a wired analyst
+ * drains its own child off the SHARED cursor by id-match, so on a NON-flat gate (which spawns
+ * widen children that are live concurrently) the analyst can consume a sibling's settlement before
+ * the widen loop sees it. The shipped default (`flatWidenGate`) never widens, so no widen child is
+ * ever live when the analyst runs and the wire is exact; a non-flat gate must drive the analyst on
+ * a scope whose siblings are quiesced, or read findings without the shared-cursor drain.
+ */
+declare function widen<Task, Seed, D>(spec: WidenSpec<Seed, D>): CombinatorShape<Task, D>;
+/**
+ * The flat default `ScopeWidenGate` — never widens, keeping the R2 selector≠judge collision
+ * dormant. A gate run passes this explicitly; a test asserts the default is flat.
+ */
+declare function flatWidenGate<D>(): ScopeWidenGate<D>;
+
+/**
+ * @experimental
+ *
+ * The cross-run corpus (G2) — the learning-flywheel's durable accreted-fact store.
+ *
+ * `Corpus` is DISTINCT from the per-run `SpawnJournal` (decisions/replay) and `ResultBlobStore`
+ * (payloads): a `CorpusRecord` is a FACT one run LEARNED that a FUTURE run reads back (the
+ * world-model), not a replay input. This module owns the two impls the wave surface pins —
+ * `InMemoryCorpus` and `FileCorpus` (JSONL, append-only) — plus `renderCorpusToInstructions`,
+ * the READ side that projects accreted facts into a fresh `AgentProfile`'s instruction seams.
+ *
+ * The boundary is fail-loud, typed-outcome: `append` is idempotent on an identical record and
+ * returns a typed error (never throws, never a silent overwrite) on a conflicting re-append under
+ * the same `id`. Malformed records — a structurally-invalid `CorpusRecord` from disk or a caller —
+ * fail loud (the validator throws), since a corpus that silently accepts garbage would poison
+ * every downstream run that reads it back.
+ */
+
+/**
+ * In-memory `Corpus`. Keyed by record `id`; `append` validates the record, is idempotent on an
+ * identical re-append, and returns a typed `{ succeeded: false }` on a conflicting re-append under
+ * the same `id` (never overwrites). `query` routes through the single-sourced `applyFilter`.
+ */
+declare class InMemoryCorpus implements Corpus {
+    private readonly byId;
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+}
+/**
+ * JSONL on disk — one validated `CorpusRecord` per line, append-only. `query` replays the whole
+ * file, validating every line (a malformed line fails loud — a corrupted corpus must never read
+ * back silently) and folding by `id`: a later identical line dedups, a later conflicting line
+ * under the same `id` is a corruption (fail loud). `append` first replays to enforce the same
+ * idempotence/conflict contract as the in-mem impl, then fsyncs the new line so a crash between
+ * writes never loses an acknowledged fact. Shares the JSONL append-line spine with the spawn
+ * journal, but the interface stays separate (a learned fact is not a replay record).
+ */
+declare class FileCorpus implements Corpus {
+    private readonly path;
+    constructor(path: string);
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+    private load;
+    private appendLine;
+}
+/**
+ * The learning-flywheel READ side. Queries the corpus through `filter`, renders the matching facts
+ * (most-confident first, capped by `maxLines`) into instruction lines, and returns a FRESH
+ * `AgentProfile` with them merged in — never mutates the input profile. Default `target: 'prompt'`
+ * appends the lines to `prompt.instructions[]` (the additive append-line seam); `target:
+ * 'resources'` folds them into the single-blob `resources.instructions` string (preserving any
+ * existing blob, but failing loud on a non-string existing blob — a `resources.instructions` that
+ * was already an `AgentProfileResourceRef` cannot be string-appended without dropping it).
+ *
+ * An empty query result returns a fresh COPY of the profile with no instruction change (a valid
+ * "nothing learned yet" read, not an error).
+ */
+declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOptions): Promise<AgentProfile$1>;
+
+/**
+ * @experimental
+ *
+ * The personify layer impl — `definePersona` (the thin builder) + `runPersonified` (composes
+ * the persona + chosen shape onto the keystone `Supervisor`), plus `createShapeContext`, the
+ * seam that hands a shape its spawn helpers without it touching the registry.
+ *
+ * This file adds NO engine: `runPersonified` is `createSupervisor().run(rootAgent, task, …)`
+ * where `rootAgent` is the persona's chosen `LoopShape` applied to a `ShapeContext`. All the
+ * conserved-budget / journal / abort / typed-result machinery is the keystone's; this layer
+ * only wires the persona's CONTENT (root spec + directive + context + seams) into it.
+ *
+ * One non-obvious invariant it must honor: `createSupervisor().run` builds the root `Scope`
+ * with an EMPTY seam bag (`seams: {}`), so the built-in metered runtimes (router/sandbox/cli)
+ * cannot read their seams off `ExecutorContext` through the default supervisor path. A persona
+ * that supplies raw `seams` is therefore wrapped here into a registry whose resolved factories
+ * receive a ctx with the persona seams merged in — so a persona never has to pre-close its
+ * factories by hand. A persona may instead supply a fully-built `registry` and skip the wrap.
+ */
+
+/**
+ * Build a frozen `Persona`. Fails loud on the executors-supplied invariant: a persona with
+ * neither a pre-built registry nor a seam bag cannot resolve its built-in runtimes, so it is
+ * unrunnable — refuse it at definition time, not at the first spawn. Pure; no I/O.
+ */
+declare function definePersona<D = unknown>(input: DefinePersonaInput<D>): Persona<D>;
+/**
+ * Compose the persona + chosen shape onto a fresh keystone `Supervisor`. Resolves the shape
+ * (a factory verbatim, or a registered name through `builtinShapes`), applies it to a
+ * `ShapeContext`, and runs the resulting root `Agent` to a typed `SupervisedResult<Outcome>`.
+ * Fail loud on an unknown shape name or an unresolvable persona registry — never a silent
+ * default-shape fallback.
+ */
+declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>): Promise<SupervisedResult<Outcome<D>>>;
+
+/**
+ * @experimental
+ *
+ * The loop-shape registry — the OPEN, content-free extension point for the personify layer.
+ *
+ * A `LoopShape` is reusable STRUCTURE (how to decompose / fan out / verify / synthesize),
+ * parameterized by a persona's CONTENT. The registry lets a caller resolve a composed shape by
+ * NAME: register a factory once, then `runPersonified({ shape: '<name>' })` resolves it with zero
+ * edits elsewhere. `register` fails loud on a duplicate; `resolve` returns a typed outcome so an
+ * unknown name is a named error, never a silent default.
+ *
+ * No shape is pre-registered: the generic combinators (`pipeline`/`fanout`/`loopUntil`/`panel`/
+ * `verify`/`widen`) take spec arguments, so they are not bare zero-arg factories — a caller that
+ * wants name-resolution registers its own COMPOSED shape (a combinator already applied to its
+ * spec) on a registry instance. The registry carries SHAPE only; the domain lives on the persona.
+ */
+
+/**
+ * Build a fresh open `ShapeRegistry`. A factory is stored type-erased and re-cast on resolve — the
+ * caller asserts the `<Task, D>` it expects, exactly as the executor registry stores its factories.
+ */
+declare function createShapeRegistry(): ShapeRegistry;
+/** The default registry `runPersonified` resolves a shape name against. Empty by construction —
+ *  a caller registers its own composed shapes; the engine ships no domain shape. */
+declare const builtinShapes: ShapeRegistry;
+/** Register a composed shape on the default `builtinShapes` registry — the one-call extension
+ *  point a caller invokes so its shape is resolvable by name with zero edits to the engine. */
+declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+
+/**
+ * @experimental
+ *
+ * Trajectory trace + cost ledger — the post-hoc tree reconstructor (§4 of `wave-types`).
+ *
+ * `trajectoryReport` rebuilds the WHOLE realized spawn tree from the durable
+ * `SpawnJournal` (+ optionally the `ResultBlobStore` for `done` artifacts): every node
+ * (driver AND leaf), the real parent/child edges, each node's terminal status, its OWN
+ * conserved `Spend`, and the `Spend` ROLLED UP over its subtree. Roll-up is a post-order
+ * fold over the parent edges: a node's `rolledUpSpend` is its own spend plus every
+ * descendant's, so a driver is charged for the fanout it caused — the root's roll-up is
+ * the whole run's conserved total (tokens + usd + iterations + ms).
+ *
+ * `equalKOnCost` compares separate runs (arms) on that conserved COST, not on raw
+ * iteration COUNT. The sandbox executor reports tokens/usd INCLUSIVE of a leaf's internal
+ * sub-agent fanout, so charging an arm by `total.tokens`/`total.usd` (not by how many
+ * `next()` cursors it logged) closes the leaf-fanout confound: a treatment leaf that fanned
+ * out internally pays for it in cost, where a per-iteration count would hide it. The
+ * within-run conserved pool already guarantees `Σk` equal by construction; this check is the
+ * CROSS-run analogue the pool cannot reach — proving equal compute before any win is claimed.
+ *
+ * Pure over the journal/blobs — no live agent calls; safe to run on a finished run's log.
+ */
+
+/**
+ * Reconstruct the whole spawn tree for `root` with per-node + rolled-up `Spend`. Reads the
+ * journal for structure + spend and, when `withOutputs`, the blob store for each `done`
+ * node's artifact. Fail loud on a tree that was never journaled, a settle/cancel for an
+ * un-spawned node (a corrupted log), or — under `withOutputs` — a `done` node whose blob the
+ * store cannot rehydrate (a silent gap would mis-cost or mis-evidence the tree).
+ */
+declare function trajectoryReport(journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId, options?: TrajectoryReportOptions): Promise<TrajectoryReport>;
+/**
+ * Assert the arms are comparable at EQUAL conserved COST (tokens + usd), NOT raw iteration
+ * count. Compares each arm's root-rolled-up `total` on the two conserved channels: an arm is
+ * within-tolerance when the per-channel spread (max − min across arms) over the median is
+ * `≤ tolerance`. Pure over the reports — no I/O. Fails loud on an empty arm list (nothing to
+ * compare) so a vacuous "equal" is never returned.
+ */
+declare function equalKOnCost(arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions): EqualKVerdict;
+
+interface PromotionGateOptions {
+    /** The HOLDOUT report — must carry per-task cells for both strategy names. */
+    report: BenchmarkReport;
+    /** The incumbent champion's strategy name. */
+    incumbent: string;
+    /** The challenger's strategy name. */
+    candidate: string;
+    /** 'superiority' (default): the candidate must score significantly BETTER.
+     *  'non-inferiority': the candidate must prove its score is not worse than the
+     *  incumbent by more than `scoreTolerance` AND its cost savings are significant —
+     *  the gate for "same quality, cheaper" claims. */
+    mode?: 'superiority' | 'non-inferiority';
+    /** non-inferiority: the score CI lower bound must clear −scoreTolerance. Default 0.05. */
+    scoreTolerance?: number;
+    /** The CI lower bound on the paired lift must EXCEED this (score scale). Default 0. */
+    deltaThreshold?: number;
+    /** Minimum paired tasks before significance can be claimed. Default 6 — below that
+     *  the bootstrap CI is too wide to separate a real lift from the per-task noise. */
+    minPairedTasks?: number;
+    /** Bootstrap statistic over the paired deltas. Default 'mean'. */
+    statistic?: 'mean' | 'median';
+    /** Fixed by the substrate by default — the same report always yields the same verdict. */
+    seed?: number;
+    resamples?: number;
+}
+interface PromotionVerdict {
+    promoted: boolean;
+    reason: 'identical-champion' | 'few-tasks' | 'no-margin' | 'significant' | 'non-inferior-and-cheaper' | 'non-inferiority-unproven' | 'not-cheaper';
+    mode: 'superiority' | 'non-inferiority';
+    /** Paired tasks that carried both strategies' cells. */
+    n: number;
+    /** Paired (candidate − incumbent) lift across the holdout tasks. */
+    lift: {
+        mean: number;
+        median: number;
+        low: number;
+        high: number;
+    };
+    /** non-inferiority mode: paired (incumbent − candidate) cost SAVINGS per task (usd) —
+     *  positive means the candidate is cheaper; significant iff the CI low clears zero. */
+    costSavings?: {
+        mean: number;
+        median: number;
+        low: number;
+        high: number;
+    };
+    /** Paired (candidate − incumbent) wall-clock per task (ms) — negative = the candidate
+     *  is FASTER. Informational in every mode (never gates); the latency answer to "what
+     *  does this win actually cost the user?". */
+    latency?: {
+        mean: number;
+        median: number;
+        low: number;
+        high: number;
+    };
+}
+declare function promotionGate(opts: PromotionGateOptions): PromotionVerdict;
+
+/**
+ * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
+ * dispatch.
+ *
+ * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
+ * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
+ * `runLoop` must forward the loop's cost AND token usage, or the guard reads
+ * the run as a stub and throws. `reportLoopUsage` is that one line:
+ *
+ *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
+ *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
+ *     reportLoopUsage(ctx, result)
+ *     return result.winner?.output as A
+ *   }
+ *
+ * Typed structurally against the campaign `DispatchContext.cost` so this module
+ * stays free of an agent-eval import — it works with any cost meter exposing
+ * `observe` + `observeTokens`.
+ */
+
+/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
+interface UsageSink {
+    observe(amountUsd: number, source: string): void;
+    observeTokens(usage: LoopTokenUsage): void;
+}
+/**
+ * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
+ * meter so the backend-integrity guard sees real LLM activity. `source`
+ * defaults to `'loop'`.
+ */
+declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
+
+/**
+ * @experimental
+ *
+ * `acquireSandbox` — cold-start-resilient sandbox acquisition. Eliminates the
+ * "create timed out at the proxy" failure mode conceptually by DECOUPLING "the
+ * create HTTP call returned" from "the sandbox is ready":
+ *
+ *   - Create is initiated with a known `name`.
+ *   - Readiness is observed from the sandbox's own `status` (`refresh()` polls
+ *     true state), NOT from whether the create call returned in time.
+ *   - If the create call itself times out at a gateway (502/503/504/522/524 or
+ *     a transport timeout), provisioning is still running server-side — so we
+ *     find the named sandbox via `list()` and wait for it to reach `running`.
+ *
+ * Result: a scale-from-zero cold start (node boot + host-agent registration,
+ * minutes) can no longer surface as a create failure behind a ~100s proxy
+ * limit. The loop becomes indifferent to whether the host pool is warm or cold.
+ *
+ * Invariant: an instance reporting no `status` (the minimal test fakes) is
+ * treated as ready; only an explicit `pending`/`provisioning` status triggers
+ * waiting, and only a retryable THROW triggers the find-by-name path. Real
+ * errors (auth, validation, budget) fail loud. A box that is created (or found)
+ * but never reaches `running` (abort, terminal status, budget) is torn down
+ * before the failure propagates, so an abort storm during cold start does not
+ * leak live sandboxes.
+ */
+
+/** @experimental */
+interface AcquireOptions {
+    /**
+     * Total budget for the sandbox to reach `running`, covering on-demand node
+     * cold-start. Default 600_000ms — matches the orchestrator's pending-host
+     * registration window so we never give up before the platform itself would.
+     */
+    readyTimeoutMs?: number;
+    /** Poll interval while waiting for `running` / for the named sandbox to appear. */
+    pollIntervalMs?: number;
+    /** Cancellation (user abort). Distinct from create-call timeouts. */
+    signal?: AbortSignal;
+    /** Stamp a name so a timed-out create is recoverable by lookup. Auto-generated if absent. */
+    name?: string;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+    /** Sleep override for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** @experimental */
+declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOptions, acquire?: AcquireOptions): Promise<SandboxInstance>;
+
+/**
+ * @experimental
+ *
+ * Capability probe for the loop kernel's backend-blind lineage seams. The
+ * kernel must NEVER ask "is this Docker or Firecracker?"; it asks "can this
+ * platform fork a checkpoint?" via `client.criuStatus()` and degrades to fresh
+ * boxes when the answer is no. CRIU availability is a per-platform fact, so the
+ * probe is memoized per client — one network round-trip, reused across every
+ * fanout in the run.
+ *
+ * Invariant: a client with no `criuStatus` method (the loop's test fakes, the
+ * raw SDK before it grew the probe) reports `canFork = false`. The seam is
+ * fail-CLOSED — never assume forking works, only enable it on a positive probe.
+ */
+
+/**
+ * What the loop kernel is allowed to know about a sandbox backend: a single
+ * capability bit, never the backend's identity. `canFork` gates the
+ * checkpoint+fork fanout path; everything else (session continuation) is a
+ * universal SDK feature that needs no probe.
+ *
+ * @experimental
+ */
+interface SandboxCapabilities {
+    /**
+     * True only when `client.criuStatus()` returned `{ available: true }`. When
+     * false, a fork-enabled fanout degrades to independent fresh boxes — same
+     * result, no shared context prefix.
+     */
+    canFork: boolean;
+}
+/**
+ * Probe (and memoize per client) what the loop may rely on. A client without a
+ * `criuStatus` method, or whose probe rejects, yields `canFork = false` — a
+ * failed probe must never claim a capability the platform may not have. The
+ * promise is cached so concurrent fanout branches share one round-trip.
+ *
+ * @experimental
+ */
+declare function probeSandboxCapabilities(client: SandboxClient): Promise<SandboxCapabilities>;
+/**
+ * Narrowed view of the optional CRIU probe. The loop-side `SandboxClient`
+ * does not require `criuStatus`; this widens it optionally so the probe can be
+ * read without importing sandbox-backend specifics. @experimental
+ */
+interface CriuCapableClient {
+    criuStatus?: () => Promise<{
+        available: boolean;
+        criuVersion?: string;
+        reason?: string;
+    }>;
+}
+
+/**
+ * Sandbox-event → runtime-event mapping.
+ *
+ * The sandbox SDK emits a polymorphic `SandboxEvent = { type, data, id? }`
+ * whose `type` vocabulary is backend-determined (opencode, etc.) rather than
+ * enumerated by the SDK. Two consumers project it:
+ *   - the loop kernel's cost ledger (`extractLlmCallEvent`) — sums usage off
+ *     every cost-bearing event, regardless of stream shape;
+ *   - the `AgentRuntime.act` streaming contract (`mapSandboxEvent`) — projects
+ *     incremental events to the `RuntimeStreamEvent` chat-UX vocabulary.
+ *
+ * Both live here so the empirically-observed `type` vocabulary has one home.
+ */
+
+/**
+ * Extract a `RuntimeStreamEvent`-shaped `llm_call` from a sandbox event when
+ * the event carries usage/cost data. Returns `undefined` for non-cost events
+ * so the kernel can iterate the full stream without branching.
+ *
+ * Canonical cost-carrying types observed in the wild:
+ *   - `llm_call` — `data: { model, tokensIn, tokensOut, costUsd, ... }`
+ *   - `message.completed` / `result` — `data: { usage: { inputTokens,
+ *      outputTokens, totalCostUsd? } }`
+ *   - `cost.usage` / `usage` — same shape under a dedicated type
+ *
+ * Numeric coercion is strict: `Number.isFinite` gates every accumulator write
+ * so a sentinel `NaN` from a misbehaving backend cannot poison the ledger.
+ */
+declare function extractLlmCallEvent(event: SandboxEvent, agentRunName: string): (RuntimeStreamEvent & {
+    type: 'llm_call';
+}) | undefined;
+/**
+ * Project one `SandboxEvent` onto the `RuntimeStreamEvent` chat-UX vocabulary,
+ * for runtimes that bridge a sandbox `streamPrompt` into the
+ * `AgentRuntime.act` streaming contract. Returns `undefined` for events that
+ * have no faithful projection — the raw stream is preserved separately for the
+ * `OutputAdapter`, so an unmapped event never loses data.
+ *
+ * Mapped (the task-optional incremental variants — no synthesized task
+ * lifecycle, no guessed tool-part shapes):
+ *   - `message.part.updated` text part → `text_delta`
+ *   - `message.part.updated` reasoning/thinking part → `reasoning_delta`
+ *   - cost-bearing events → `llm_call` (shared with the ledger extractor)
+ *
+ * The opencode backend emits incremental text as
+ * `{ type: 'message.part.updated', data: { part: { type, text }, delta } }`;
+ * `delta` is the increment, `part.text` the running accumulation.
+ */
+declare function mapSandboxEvent(event: SandboxEvent, opts?: {
+    agentRunName?: string;
+}): RuntimeStreamEvent | undefined;
+
+/**
+ * @experimental
+ *
+ * `SandboxLineage` — the backend-blind owner of box + session handles for a
+ * single `runLoop` invocation. It exists so `run-loop.ts` never references a
+ * backend (Docker / Firecracker): the lineage turns "continue this session" and
+ * "fork this branch" into capability-gated sandbox-SDK calls and degrades to
+ * fresh boxes when a capability is absent.
+ *
+ * Three operations, mirroring the kernel's per-iteration choices:
+ *   - `start(spec, prompt)`  → a fresh box; the FIRST `streamPrompt` carries a
+ *      minted `sessionId` so later `continue` calls reuse the same server-side
+ *      conversation instead of re-injecting prior context as prompt text.
+ *   - `continue(handle, prompt)` → the SAME box, `streamPrompt({ sessionId })`.
+ *      The context lives in the sandbox; the prompt is only the new turn. Before
+ *      streaming it ASSERTS the session is still live server-side (via
+ *      `box.session(id).status()`): if the platform never honored the
+ *      client-minted id (or reaped it), `status()` is `null` and `continue`
+ *      fails loud rather than silently re-running the turn without prior context.
+ *   - `fork(handle, n, ...)` → when `canFork`, `checkpoint({ leaveRunning })` on
+ *      the parent then `fork(checkpointId)` × n so N branches inherit a shared
+ *      context prefix; otherwise N independent fresh boxes (same result, no
+ *      prefix). Either way each branch streams its own turn. Child-box creation
+ *      is bounded by the lineage's `maxConcurrency` — a 20-way fanout under a
+ *      concurrency cap of 2 provisions boxes in bounded waves, not all at once.
+ *
+ * Invariant: the lineage OWNS every box it starts or forks and tears them all
+ * down on `teardown()` (or earlier via `prune`). It never tears down a box
+ * mid-flight — the kernel decides when a handle is done. Streaming itself stays
+ * in `run-loop.ts`; the lineage only hands back the live `streamPrompt` iterable
+ * so the kernel keeps ownership of event collection, cost accounting, and trace
+ * emission.
+ */
+
+/**
+ * A live box plus the session that threads its iterations together. Handed back
+ * by `start`/`fork`, passed into `continue`/`fork` to descend from. Opaque to
+ * the kernel beyond `box` (for placement/teardown) and `sessionId` (trace).
+ *
+ * @experimental
+ */
+interface SandboxLineageHandle {
+    /** The owned, running sandbox this handle drives. */
+    box: SandboxInstance;
+    /**
+     * Stable session id threaded through this box's `streamPrompt` calls. Minted
+     * by the lineage on `start`; reused on `continue` so the server continues the
+     * same conversation. A forked handle starts a fresh session on its new box —
+     * the shared context comes from the checkpoint, not a shared session id.
+     */
+    sessionId: string;
+}
+/**
+ * Owns box + session handles for one loop run and offers the three
+ * capability-gated lifecycle moves. Construct via `createSandboxLineage`.
+ *
+ * @experimental
+ */
+interface SandboxLineage {
+    /**
+     * Acquire a fresh box and begin a new session on it. Returns the handle and
+     * the live `streamPrompt` iterable for the first turn (caller drains it).
+     */
+    start(spec: AgentRunSpec<unknown>, prompt: string, signal: AbortSignal): Promise<{
+        handle: SandboxLineageHandle;
+        events: AsyncIterable<SandboxEvent>;
+    }>;
+    /**
+     * Continue an existing handle's session with one more turn on the SAME box.
+     * The prior context is server-side; `prompt` is only the new turn. Asserts the
+     * session is still known to the sandbox first (fail-loud) so a platform that
+     * silently dropped the client-minted session id surfaces as an error instead
+     * of a contextless turn the caller mistakes for a real continuation.
+     */
+    continue(handle: SandboxLineageHandle, prompt: string, signal: AbortSignal): Promise<AsyncIterable<SandboxEvent>>;
+    /**
+     * Branch `count` children from `parent`. When the platform can fork, each
+     * child inherits `parent`'s checkpoint — and therefore the parent's IMAGE and
+     * PROFILE: under a real fork `specs[i]` does NOT re-select a per-branch
+     * profile (the SDK forks the running box, it can't swap the image). `specs[i]`
+     * picks the per-branch profile ONLY on the degraded fresh-box path (no CRIU).
+     * A heterogeneous-profile fanout therefore homogenizes to the parent's profile
+     * when fork is available — pass a single shared spec for forked fanouts, or
+     * use `random@k` (no fork) when branches must differ. Each child's first turn
+     * streams `prompts[i]`. Child-box creation is bounded by `maxConcurrency`.
+     */
+    fork(parent: SandboxLineageHandle, prompts: string[], specs: AgentRunSpec<unknown>[], signal: AbortSignal): Promise<{
+        handle: SandboxLineageHandle;
+        events: AsyncIterable<SandboxEvent>;
+    }[]>;
+    /**
+     * Destroy every owned box whose handle is NOT in `keep`, freeing it before
+     * loop end. The kernel calls this after a round when it can prove no future
+     * round will descend from the pruned boxes (deterministic, monotonic branch
+     * selection); boxes still reachable as a future branch source are retained.
+     * Best-effort, bounded, parallel — a failed delete never throws.
+     */
+    prune(keep: Iterable<SandboxLineageHandle>): Promise<void>;
+    /** Destroy every box this lineage owns. Best-effort, bounded, parallel. */
+    teardown(): Promise<void>;
+}
+/**
+ * Build a lineage bound to one client + its probed capabilities. The
+ * capabilities are passed in (not re-probed) so the kernel probes once per run
+ * and the lineage stays a pure function of "what this platform can do".
+ *
+ * @experimental
+ */
+declare function createSandboxLineage(client: SandboxClient, capabilities: SandboxCapabilities, options?: {
+    maxConcurrency?: number;
+    streaming?: 'sse' | 'poll';
+}): SandboxLineage;
+/**
+ * Loop-side widening of the box's optional checkpoint method. The
+ * `SandboxClient`/`SandboxInstance` surface the kernel relies on does not
+ * require checkpointing; this reads it optionally so the lineage can probe-gate
+ * without importing sandbox-backend specifics. @experimental
+ */
+interface CheckpointCapableBox {
+    checkpoint?: (options?: {
+        leaveRunning?: boolean;
+        tags?: string[];
+    }) => Promise<{
+        checkpointId: string;
+    }>;
+}
+/** Loop-side widening of the box's optional fork method. @experimental */
+interface ForkCapableBox {
+    fork?: (checkpointId: string, options?: {
+        name?: string;
+    }) => Promise<SandboxInstance>;
+}
+/**
+ * Loop-side widening of the box's optional session accessor. The real
+ * `SandboxInstance` exposes `session(id).status()`; the loop reads it optionally
+ * so `continue` can assert session liveness without requiring it of the test
+ * fakes. `status()` resolves `null` when the id is unknown to the sandbox.
+ * @experimental
+ */
+interface SessionCapableBox {
+    session?: (id: string) => {
+        status: () => Promise<unknown | null>;
+    };
+}
+
+/**
+ * `openSandboxRun` — the ONE harness-agnostic seam for running an agent in a
+ * sandbox over a persistent artifact: run it, stream it, RESUME the same session
+ * across turns. Domain-agnostic: a coding agent, a research agent, a tax/legal
+ * agent — all flow through this; the domain lives only in the `Deliverable<Out>`
+ * the caller supplies, never in a per-domain copy of this function.
+ *
+ * It is a thin facade (NOT a new layer) over code that already exists and is
+ * already hardened:
+ *   - `acquireSandbox` — cold-start / 502-503-504 / gateway-timeout recovery,
+ *   - `buildBackendOptions` — the harness IS `backend.type` (opencode / codex /
+ *     claude-code / kimi-code / hermes / pi); the only "which agent" knob,
+ *   - `createSandboxLineage` — `start` mints a session; `resume` continues the
+ *     SAME server-side session with a fail-loud `assertSessionLive`.
+ *
+ * The one genuinely-new piece is {@link Deliverable}: it widens the pure
+ * `OutputAdapter.parse(events)` to ALSO admit a post-turn read off the box FS —
+ * the structural gap that made the bench gates hand-roll `box.fs.read`, because a
+ * large produced file (a git diff, a generated document) truncates in the chat
+ * stream and a pure events-parser cannot reach the workspace. Per the SDK, a
+ * RELATIVE `deliverable.path` resolves from the workspace root and an ABSOLUTE one
+ * (e.g. `/tmp/solution.patch`) reads the container filesystem directly — both are
+ * valid; pick the one the agent actually wrote to. Avoid `..` traversal segments.
+ *
+ * What this deliberately does NOT do (so it stays a facade, not slop): no custom
+ * reconnect/replay (the SDK + platform own per-session buffering + `Last-Event-ID`);
+ * no fork verb (platform CRIU is probe-gated and currently absent — fork lives in
+ * `SandboxLineage.fork` behind the capability probe, surfaced only if it returns).
+ * It is also distinct from `runLoop`: `runLoop` is the multi-round, driver-driven
+ * kernel (fresh box per round, events deliverable); this is a SINGLE rollout +
+ * artifact-or-events deliverable + resume over ONE persistent box.
+ */
+
+/**
+ * @experimental
+ * How a typed deliverable `Out` is materialized from a finished turn.
+ * - `events`   — pure parse over the event array (identical to `OutputAdapter`).
+ * - `artifact` — read a file off the box AFTER the turn drains, then map it (+ the
+ *                events). For diffs/codebases/documents that don't fit the chat
+ *                stream. `path` relative ⇒ workspace root; absolute ⇒ container FS.
+ */
+type Deliverable<Out> = {
+    kind: 'events';
+    fromEvents: (events: SandboxEvent[]) => Out;
+} | {
+    kind: 'artifact';
+    path: string;
+    fromArtifact: (raw: string, events: SandboxEvent[]) => Out;
+};
+/**
+ * @experimental
+ * One finished turn over the artifact. A failed FS read is surfaced in `readError`
+ * (never masked as an empty deliverable) so a caller distinguishes "agent produced
+ * nothing" from a transport/FS fault.
+ */
+interface TurnResult<Out> {
+    out: Out;
+    events: SandboxEvent[];
+    readError?: string;
+}
+/** @experimental A live run over ONE persistent artifact (box + session). Close it
+ *  when done — `close()` tears the box down. */
+interface SandboxRun<Out> {
+    readonly box: SandboxInstance;
+    readonly sessionId: string;
+    /** First turn over the fresh box (mints the session). Throws if already started. */
+    start(prompt: string): Promise<TurnResult<Out>>;
+    /** Continue THE SAME session over THE SAME artifact — a resumed turn/rollout. */
+    resume(prompt: string): Promise<TurnResult<Out>>;
+    close(): Promise<void>;
+}
+/** @experimental */
+interface OpenSandboxRunOptions {
+    /** Profile + sandbox env/overrides. `sandboxOverrides.backend.type` is the harness. */
+    agentRun: AgentRunSpec<string>;
+    signal: AbortSignal;
+    /** Optional execution-scoped observers. Hook failures never fail the run. */
+    hooks?: RuntimeHooks;
+    /** Stable run id for trace joins. Defaults to a short runtime-minted id. */
+    runId?: string;
+    /** Optional benchmark/scenario id carried into emitted hook events. */
+    scenarioId?: string;
+    /** Test seam for deterministic hook timestamps. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Bounds box-creation bursts inside lineage fanout. Default from lineage. */
+    maxConcurrency?: number;
+    /** Base backoff (ms) for retrying a transient artifact `fs.read` failure; the i-th
+     *  retry waits `readRetryDelayMs * i`. Default 1000. Set 0 to disable the wait (tests). */
+    readRetryDelayMs?: number;
+}
+/**
+ * @experimental
+ * Open a sandbox run. Harness-agnostic: the harness lives in
+ * `options.agentRun.sandboxOverrides.backend.type`, so opencode/codex/claude-code/
+ * kimi-code all flow through this one entrypoint with identical env/auth wiring.
+ */
+declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandboxRunOptions, deliverable: Deliverable<Out>): Promise<SandboxRun<Out>>;
+
+/**
+ * authorStrategy — the agent-authored layer as a package primitive (software-3.0): an
+ * LLM reads a benchmark's per-task LOSSES + the defineStrategy contract and writes a NEW
+ * optimization strategy as code; the caller gates it like any human-built candidate
+ * (runBenchmark + a frozen holdout).
+ *
+ * Structurally safe by construction: the authored body composes shot()/critique() and
+ * spends through the Supervisor's conserved pool — it can be wrong, but it cannot
+ * Goodhart the check (it never sees the verifiers) and it cannot win by overspending.
+ *
+ * The authored module is written to `outDir` and dynamically imported — run under a
+ * TS-capable loader (tsx) since models often emit type annotations.
+ */
+
+/** The compressed consumable a skill carries: everything an author needs to emit a loop. */
+declare const strategyAuthorContract = "\nYou author an OPTIMIZATION STRATEGY for an agentic loop system. A strategy decides how to\nspend a compute budget to beat a task's deployable check. You compose exactly two steps:\n\n  shot(spec?: { handle?, messages?, steer?, persona?, tools? }): Promise<ShotResult | null>\n    Runs ONE worker attempt (a bounded tool loop) over an artifact.\n    - omit handle  => the shot opens its OWN fresh artifact and closes it after (a sample).\n    - pass handle  => the shot CONTINUES that artifact (state accumulates across shots).\n    - messages     => the carried conversation (pass the previous ShotResult.messages to continue).\n    - steer        => a corrective instruction injected before the shot.\n    - persona      => { systemPrompt?, model? } \u2014 give THIS shot its own role and/or model\n      (multi-agent strategies: a researcher shot then an engineer shot, a panel of k\n      personas over one budget). On a fresh shot the systemPrompt replaces the task's; on\n      a carried conversation it arrives as a hand-off message. Same conserved budget.\n    - tools        => string[] \u2014 restrict THIS shot to a subset of the task's tools by\n      name (focus an explore shot on read-only tools, an execute shot on write tools).\n      Restriction-only; unknown names make the shot fail. ALWAYS select from\n      await listTools(handle) \u2014 never hardcode. Omitted => the shot sees every tool.\n    ShotResult = { messages, score (0..1 on the task's check), passes, total, completions, toolErrors }\n    Returns null if the attempt failed infra-wise.\n\n  critique(messages): Promise<string | null>\n    A firewalled trace-analyst reads the attempt's trajectory and returns ONE corrective\n    instruction (or null when it judges the work complete). Costs ~1 completion.\n\n  consult(messages, instruction): Promise<string | null>\n    The RAW analyst channel: the same firewalled critic answers YOUR instruction over the\n    trajectory verbatim (no reformatting) \u2014 use it when you need a specific reply format\n    (a decision, a prediction). Costs ~1 completion.\n\n  surface.open(task) / surface.close(handle)\n    Open a persistent artifact you manage yourself (remember to close in a finally).\n    close is idempotent \u2014 closing an already-closed handle is a safe no-op.\n\n  listTools(handle): Promise<Array<{ name, description? }>>\n    The tools THIS task actually offers. TOOL SETS VARY PER TASK \u2014 if you restrict a\n    shot with `tools`, you MUST pick names from await listTools(handle); hardcoding\n    names from an example kills your shots on every task whose tools differ.\n\nRules:\n- ALWAYS await every shot/critique/surface call \u2014 a floating promise that rejects\n  crashes the whole benchmark run.\n- Stay within ~budget total shots; every shot/critique spends from a conserved pool.\n- For a FRESH attempt OMIT `messages` entirely (never pass `[]` \u2014 an empty array is a\n  fresh conversation too, but be explicit). To CONTINUE, pass the previous\n  ShotResult.messages unchanged.\n- Return { score, resolved, completions, progression, shots } \u2014 score = the BEST checkpoint\n  you reached (keep-best, never final-state), progression = score after each shot.\n- The module must be EXACTLY this shape (no other imports, no commentary outside code):\n\nimport { defineStrategy } from '@tangle-network/agent-runtime/loops'\nexport default defineStrategy('your-strategy-name', async ({ surface, task, budget, shot, critique, listTools }) => {\n  // your composition (listTools comes from the destructured context \u2014 it is NOT a global)\n})\n";
+interface AuthorStrategyOptions {
+    /** The model-call seam (agent-eval `createChatClient`). */
+    chat: ChatClient;
+    model?: string;
+    /** A NAMED fallback author tried once when the primary call fails or returns no code
+     *  block (thinking models time out at the edge on long authoring prompts, or return
+     *  empty content without `maxTokens`). Opt-in — absent means the primary's failure
+     *  propagates. */
+    fallbackModel?: string;
+    /** The contract text shown to the author. Default `strategyAuthorContract`. The
+     *  meta-optimization coordinate: a GEPA/skill loop can evolve this text and gate each
+     *  variant on the same frozen holdout as any strategy. */
+    contract?: string;
+    /** The environment the losses came from (orientation only — never the verifiers). */
+    environmentName: string;
+    /** The per-task losses table (e.g. JSON.stringify(report.perTask)) — the gradient. */
+    lossesJson: string;
+    /** The budget the strategy must respect (shots/width). */
+    budget: number;
+    /** Where the authored module file is written (created if missing). */
+    outDir: string;
+    temperature?: number;
+    /** Completion cap — required by thinking-model authors that stream reasoning first. */
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+/** Static CONTRACT lint over an authored strategy module — the module-boundary
+ *  enforcement of the harness's two measurement invariants:
+ *    - author blindness: the only import allowed is the loops surface. A body that could
+ *      reach the filesystem, network, or process could read or mutate verifier/artifact
+ *      state outside the brokered shots, and the harness-verified score would stop
+ *      meaning "what the shots achieved".
+ *    - conserved dose: no out-of-band compute (fetch/require/eval) — every unit a
+ *      strategy spends is metered by the Supervisor's pool, which is what makes
+ *      equal-budget comparisons between strategies valid.
+ *  A lint, not a sandbox: its job is keeping the benchmark numbers interpretable. */
+declare function assertStrategyContract(code: string): void;
+interface AuthoredStrategy {
+    strategy: Strategy;
+    file: string;
+    code: string;
+}
+/** Author + load a strategy from losses. Throws when the author emits no loadable module;
+ *  with `fallbackModel` set, the named fallback gets one attempt first. */
+declare function authorStrategy(opts: AuthorStrategyOptions): Promise<AuthoredStrategy>;
+
+/**
+ * runStrategyEvolution — the multi-generation strategy search: per generation the system
+ * authors a POPULATION of candidate strategies from the current tournament's losses,
+ * plays them against the incumbent at equal budget, and advances a champion; one final
+ * promotion decision runs on a NEVER-BEFORE-USED holdout slice through `promotionGate`.
+ *
+ * Measurement invariants (the reasons this design is shaped the way it is):
+ *  - The author sees TRAIN losses only. The holdout slice is drawn fresh (disjoint task
+ *    offsets) after all authoring is done — one promotion decision, one untouched slice,
+ *    so adaptive reuse of evaluation data never enters the verdict.
+ *  - Every tournament runs at the same per-strategy budget through the conserved pool;
+ *    candidates cannot win by overspending.
+ *  - Champion selection within the search is a SEARCH policy (configurable, default
+ *    cost-aware: ties on score go to the cheapest strategy — a scalar hides a strategy
+ *    that ties at half the cost). The promotion verdict never comes from search
+ *    selection; it comes from the gate on the fresh slice.
+ *  - Every authored artifact's description length (gzip bits) is recorded, so the
+ *    artifact-complexity-vs-holdout-gap relation is analyzable from any run's report.
+ *
+ * Lineage fields (`parent`, `generation`) are recorded on every archive node so a
+ * descendant-productivity parent-selection policy can be added without changing the
+ * report schema; the v1 search authors from the latest tournament's losses.
+ */
+
+interface EvolutionAuthor {
+    /** The model-call seam (agent-eval `createChatClient`). */
+    chat: ChatClient;
+    model?: string;
+    fallbackModel?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+type ChampionPolicy = 'score' | 'costAware';
+interface StrategyEvolutionConfig {
+    environment: Environment;
+    /** Task supply by DISJOINT slice: `(offset, n)` must return n tasks unique to that
+     *  offset range. Train draws [0, trainN); the holdout draws [trainN + holdoutOffset,
+     *  …) — tasks the search never touched. */
+    tasks: (offset: number, n: number) => Promise<AgenticTask[]>;
+    trainN: number;
+    holdoutN: number;
+    /** Extra offset past the train slice for the holdout draw (rotate across runs). */
+    holdoutOffset?: number;
+    worker: AgenticOptions;
+    author: EvolutionAuthor;
+    /** Rollouts (sample) / shots (refine) per strategy per task. Default 3. */
+    budget?: number;
+    concurrency?: number;
+    /** Author→tournament rounds after gen0. Default 2. */
+    generations?: number;
+    /** Authored candidates per generation. Default 2. */
+    populationSize?: number;
+    /** The gen0 field. Default [sample, refine, sampleThenRefine]. */
+    baselines?: Strategy[];
+    /** What "better" means for PROMOTION. 'score' (default): the candidate must beat the
+     *  incumbent's score (superiority gate). 'cost': the candidate must prove score
+     *  NON-INFERIORITY (not worse by more than `scoreTolerance`) plus significant cost
+     *  savings — the "same quality, cheaper" objective. The author is told the objective
+     *  and sees per-task spend either way. */
+    objective?: 'score' | 'cost';
+    /** Cost objective: the score CI lower bound must clear −scoreTolerance. Default 0.05. */
+    scoreTolerance?: number;
+    /** Search-side champion selection. Default 'costAware'. */
+    champion?: ChampionPolicy;
+    /** Score band treated as a tie under 'costAware'. Default 0.01. */
+    championEpsilon?: number;
+    /** Where authored modules are written. */
+    outDir: string;
+    /** Promotion-gate evidence floor (paired holdout tasks). */
+    minPairedTasks?: number;
+    /** BAND-AWARE scoring — concentrate the measurement where lift is possible.
+     *  Holdout: draw `holdoutPoolN` candidate tasks and run `baselines[0]` once at the run
+     *  budget as an INDEPENDENT reference screen; keep tasks scoring ≤ `maxRefScore`
+     *  (headroom exists) and take the first `holdoutN`. Band membership is decided before
+     *  either finalist touches a task and both finalists then face the SAME tasks — the
+     *  estimand becomes "paired lift on headroom tasks", pre-registered by this config.
+     *  Train: champion selection ignores zero-spread tasks (every field strategy scored
+     *  identically — zero selection information, pure noise dilution). */
+    band?: {
+        holdoutPoolN: number;
+        /** Keep holdout tasks where the reference scores ≤ this. Default 0.99 — drop only
+         *  tasks the reference already solves fully (no headroom, a candidate can only tie). */
+        maxRefScore?: number;
+    };
+    /** What the author learns from a tournament. 'exact' (default) = scores + progressions
+     *  per task; 'binary' = pass/fail only — the leakage-bounded channel (one bit per cell
+     *  per generation reaches the author from the evaluation data). */
+    lossesDetail?: 'exact' | 'binary';
+    /** Reproducer certification (arXiv:2606.11045): when the final champion is AUTHORED,
+     *  compress it to a short natural-language summary, have a fresh author re-implement
+     *  from the summary alone (no losses, no code), and score the reproduction on the same
+     *  holdout. A reproduction gap is an overfitting signal (their detector: 100%
+     *  sensitivity / 91% specificity in the ML-agent setting) — recorded on the report,
+     *  never gate-blocking in v1. */
+    reproducerCheck?: {
+        /** Word budget for the strategy summary. Default 64. */
+        summaryMaxWords?: number;
+        /** Reproduction counts as faithful when reproducedScore ≥ championScore − tolerance.
+         *  Default 0.05. */
+        tolerance?: number;
+    };
+    /** Endurance: write the run state after every completed phase; with `resume`, a
+     *  restart skips completed phases (authored modules re-imported from their files).
+     *  Worst case after a mid-run death is re-paying ONE phase, never the run. */
+    checkpoint?: {
+        path: string;
+        resume?: boolean;
+    };
+    /** Called before each benchmark phase (gen0, gen1…, band-screen, holdout, reproduce).
+     *  The seam for environment recycling — no artifacts span phases, so a runner may
+     *  recreate a wedge-prone environment container here. */
+    onPhase?: (phase: string) => Promise<void>;
+    onTask?: (phase: string, row: BenchmarkTaskRow, done: number, total: number) => void;
+    hooks?: RuntimeHooks;
+}
+interface ChampionPick {
+    name: string;
+    score: number;
+    usd: number;
+}
+interface EvolutionCandidate {
+    name: string;
+    file?: string;
+    gzipBits?: number;
+    codeChars?: number;
+    /** Present when this author attempt failed (recorded, never silent). */
+    error?: string;
+}
+interface EvolutionGeneration {
+    generation: number;
+    candidates: EvolutionCandidate[];
+    report: BenchmarkReport;
+    champion: ChampionPick;
+}
+interface EvolutionArchiveNode {
+    name: string;
+    source: 'baseline' | 'authored';
+    generation: number;
+    /** The champion whose tournament losses this candidate was authored from. */
+    parent?: string;
+    gzipBits?: number;
+    file?: string;
+    /** Latest measured tournament result — 0 until the node's first tournament settles
+     *  (an authored node is created before its generation's benchmark runs). */
+    score: number;
+    usd: number;
+}
+interface ReproductionCheck {
+    /** The compressed strategy description the reproducer implemented from. */
+    summary: string;
+    reproducedName: string;
+    file?: string;
+    championHoldoutScore: number;
+    reproducedHoldoutScore: number;
+    /** champion − reproduced (positive = the reproduction fell short). */
+    gap: number;
+    /** reproducedScore ≥ championScore − tolerance. A failed reproduction is an
+     *  overfitting signal: the champion's win did not fit through the summary. */
+    reproducible: boolean;
+    /** Infra failure during reproduction (distinct from a semantic reproduction failure). */
+    error?: string;
+}
+interface EvolutionBandInfo {
+    /** Tasks screened by the reference on the holdout pool. */
+    screened: number;
+    /** Tasks kept (reference score ≤ maxRefScore) before truncating to holdoutN. */
+    inBand: number;
+    /** Reference scores per screened task (the screening record). */
+    refScores: Array<{
+        taskId: string;
+        score: number;
+    }>;
+}
+interface EvolutionReport {
+    gen0: BenchmarkReport;
+    gen0Champion: ChampionPick;
+    generations: EvolutionGeneration[];
+    archive: EvolutionArchiveNode[];
+    finalChampion: ChampionPick;
+    holdout: BenchmarkReport;
+    verdict: PromotionVerdict;
+    /** Present when band screening ran — the verdict's estimand is then "paired lift on
+     *  headroom tasks" (band membership fixed by the reference screen, pre-registered). */
+    band?: EvolutionBandInfo;
+    /** Present when reproducerCheck ran (final champion was authored). */
+    reproduction?: ReproductionCheck;
+    /** SEARCH TELEMETRY, not evidence: each entry is that generation's own train-slice
+     *  re-measurement, so cross-generation deltas mix true drift with run-to-run variance
+     *  (entries are unpaired across generations). The only evidence-grade comparison in
+     *  this report is `verdict` — both finalists measured fresh, paired, on the holdout. */
+    trajectory: Array<{
+        generation: number;
+        champion: string;
+        score: number;
+        usd: number;
+    }>;
+}
+/** Strategy means recomputed over the DISCRIMINATING tasks only — tasks where the field
+ *  strategies did not all score identically. Zero-spread tasks (everyone 1.0, everyone
+ *  0.0, everyone tied) carry no selection information; averaging over them dilutes real
+ *  differences toward zero. Search-side denoising only — the gate never uses this. */
+declare function discriminatingMeans(report: BenchmarkReport, fieldOrder: string[]): Record<string, {
+    score: number;
+    usd: number;
+}> | null;
+/** The champion pick over a means table. 'score' takes the best mean score (ties →
+ *  field order). 'costAware' treats scores within `epsilon` of the best as tied and
+ *  takes the cheapest — the (score, $) Pareto rule collapsed to one pick. */
+declare function pickChampion(means: Record<string, {
+    score: number;
+    usd: number;
+}>, fieldOrder: string[], policy: ChampionPolicy, epsilon: number): ChampionPick;
+/** Search-side champion selection over a tournament report. */
+declare function selectChampion(report: BenchmarkReport, fieldOrder: string[], policy: ChampionPolicy, epsilon: number): ChampionPick;
+declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<EvolutionReport>;
+
+/**
+ * @experimental
+ *
+ * The supervisor's intelligence is AUTHORING the agents it spawns — not pressing buttons.
+ *
+ * Every agent here is three things: instructions (system prompt), tools, and a model — its
+ * `AgentProfile`. The supervisor's job is to WRITE those profiles: read the task, decompose it,
+ * and for each sub-task author a tailored worker recipe. `supervisorInstructions` is the how-to the
+ * supervisor reads (its system prompt); `authoredWorker` builds a worker AGENT from a profile the
+ * supervisor authored — the authored systemPrompt + model shape the worker's call.
+ *
+ * The skill is the single OPTIMIZABLE surface: edit it → the supervisor designs better agents.
+ * That is the self-improvement lever (the prompt/skill lever), not the execution plumbing.
+ */
+
+/** What the supervisor AUTHORS per sub-task — a worker recipe (a partial `AgentProfile`). */
+interface AuthoredProfile {
+    name: string;
+    /** The rich, task-specific instructions the supervisor wrote for THIS worker. */
+    systemPrompt: string;
+    /** The model the supervisor chose for this sub-task (falls back to the run default). */
+    model?: string;
+}
+/** Narrow an untyped `spawn_agent` profile argument to an `AuthoredProfile`, or null if the
+ *  supervisor failed to author one (empty/placeholder profile — a skill violation worth catching). */
+declare function asAuthoredProfile(raw: unknown): AuthoredProfile | null;
+/** The supervisor SKILL — the how-to the supervisor reads (its system prompt). THE optimizable
+ *  surface: editing this changes how the supervisor designs every agent it spawns. */
+declare function supervisorInstructions(opts?: {
+    goal?: string;
+}): string;
+/** Build a worker AGENT from a profile the supervisor authored: the authored `systemPrompt` +
+ *  `model` shape the worker's one model call; the deliverable gates settlement (valid ⟺ delivered). */
+declare function authoredWorker(profile: AuthoredProfile, opts: {
+    cfg: RouterConfig;
+    taskPrompt: string;
+    deliverable: DeliverableSpec;
+    temperature?: number;
+}): Agent<unknown, unknown>;
+/** Thresholds below which a system prompt is treated as a thin stub. Tunable per call. */
+interface ProfileRichnessThresholds {
+    /** A prompt shorter than this many characters is thin (default 600). */
+    readonly minSystemPromptChars: number;
+    /** A prompt with fewer than this many non-blank lines is thin (default 6). */
+    readonly minSystemPromptLines: number;
+}
+declare const defaultProfileRichnessThresholds: ProfileRichnessThresholds;
+/** Per-field verdict on one authored profile — the raw material the bench renders + scores. */
+interface ProfileRichness {
+    readonly name: string;
+    /** The resolved system prompt (canonical `prompt.systemPrompt`, the sandbox `prompt.system`
+     *  convention, or a bare-string prompt — whichever the author used). */
+    readonly systemPrompt: string;
+    readonly systemPromptChars: number;
+    readonly systemPromptLines: number;
+    readonly sentenceCount: number;
+    readonly hasDescription: boolean;
+    readonly hasTools: boolean;
+    readonly hasSkills: boolean;
+    readonly hasMcp: boolean;
+    readonly hasSubagents: boolean;
+    /** 0..1 — fraction of richness signals present (prompt-depth + the four levers). */
+    readonly richness: number;
+    /** True when the supervisor authored a stub instead of a real profile. */
+    readonly thin: boolean;
+    /** The specific reasons it is thin (empty when rich) — used in the finding's action. */
+    readonly reasons: string[];
+}
+/** OBSERVE one authored `AgentProfile` and score its richness (no judge verdict is read). The task
+ *  context (`needsMcp`) lets a domain say "this work needs a data/tool MCP" so a missing MCP counts. */
+declare function assessAuthoredProfile(profile: AgentProfile$1, opts?: {
+    needsMcp?: boolean;
+    thresholds?: Partial<ProfileRichnessThresholds>;
+}): ProfileRichness;
+/** Turn a {@link ProfileRichness} verdict into a bus-routable `AnalystFinding` (area `profile-quality`).
+ *  Severity scales with thinness; the recommended action names the MISSING lever so the supervisor can
+ *  re-author. `subject` = the worker name so per-worker findings diff cleanly across re-authors. */
+declare function profileRichnessFinding(richness: ProfileRichness, opts?: {
+    analystId?: string;
+    runId?: string;
+}): AnalystFinding;
+
+/**
+ * @experimental
+ *
+ * The conserved budget reservation pool — the invariant the whole instrument
+ * rests on (critique M5/B3). One root `Budget` becomes a conserved pool of three
+ * quantities (tokens, usd, iterations) plus an absolute deadline. Children reserve
+ * atomically at spawn and reconcile at settle:
+ *
+ *   total ≡ free + reserved + committed          (invariant, always)
+ *
+ * `reserve` moves a child's whole ceiling from `free` → `reserved` and fails closed
+ * when `free` can't cover it (never read-then-spawn overcommit, so `Σk(treatment) ≡
+ * Σk(blind)` by construction). `reconcile` releases the reservation, commits ACTUAL
+ * spend, and refunds the unspent remainder to `free`. Tokens and usd are separate
+ * channels (`LoopTokenUsage` has no `usd`); iterations are conserved alongside them.
+ *
+ * Pure and deterministic: `now()` is injected, there is no I/O, and no wall-clock or
+ * RNG read. A `reserve`/`reconcile` ticket is single-use (fail-loud on double or
+ * unknown reconcile) so a child can never refund twice.
+ */
+
+/** Opaque, single-use reservation handle returned by `reserve` and consumed by
+ *  `reconcile`. Carries the reserved ceilings so reconciliation needs no lookup. */
+interface ReservationTicket {
+    readonly id: number;
+    readonly reserved: {
+        readonly tokens: number;
+        readonly usd: number;
+        readonly iterations: number;
+    };
+}
+/** Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`,
+ *  `usdLeft`, and `reservedTokens` reflect committed-but-unsettled reservations;
+ *  `deadlineMs` is the ABSOLUTE wall-clock deadline (0 when the root set none).
+ *  `usdCapped` distinguishes a real `usdLeft <= 0` exhaustion from an uncapped pool (which always
+ *  reads `usdLeft: 0`) — the in-loop guard needs it to bound a usd-capped driver. */
+type BudgetReadout = Readonly<{
+    tokensLeft: number;
+    usdLeft: number;
+    usdCapped: boolean;
+    deadlineMs: number;
+    reservedTokens: number;
+}>;
+interface BudgetPool {
+    /**
+     * Atomically reserve a child's full ceiling from the free balance. Fails closed
+     * ({ ok: false }) when the pool can't cover tokens, usd, or iterations — the
+     * caller inspects `ok` before `ticket`.
+     */
+    reserve(b: Budget): {
+        ok: true;
+        ticket: ReservationTicket;
+    } | {
+        ok: false;
+        reason: 'budget-exhausted';
+    };
+    /**
+     * Release a reservation: commit the actual `spent`, refund the unspent remainder
+     * to the free pool. Throws on an unknown or already-reconciled ticket (fail loud —
+     * a double refund would silently break conservation).
+     */
+    reconcile(ticket: ReservationTicket, spent: Spend): void;
+    /** Fold a normalized `UsageEvent` stream (or array) into a `Spend`. Tokens via
+     *  `addTokenUsage`, usd on its own channel, iterations from `'iteration'` events.
+     *  `ms` is left zero — wall-clock duration is the caller's to record, not the pool's. */
+    spendFrom(events: AsyncIterable<UsageEvent> | UsageEvent[]): Promise<Spend>;
+    /** The current readout, reflecting all outstanding reservations. */
+    readout(): BudgetReadout;
+    /**
+     * Record OBSERVED spend that did NOT go through reserve/reconcile — the driver's OWN inference
+     * (its chat turns), which is real compute but not a spawned child. A direct `free → committed`
+     * debit, so `total ≡ free + reserved + committed` is preserved: equal-k counts the driver's
+     * tokens and the in-loop budget guard (`readout().tokensLeft`) sees them. `free` may go negative
+     * when a run overspends — that is honest (the readout then signals exhaustion). It never throws:
+     * the spend already happened, so accounting records reality; the in-loop guard prevents MORE.
+     * The DURABLE record is the journal's `metered` event (written by `Scope.meter`); this debit
+     * only makes the live `readout()` reflect driver inference for the in-loop guard.
+     */
+    observe(spend: Spend): void;
+    /** Fail loud if any reservation is still open — the conserved-pool leak detector. Called at the
+     *  supervisor's join barrier: once every child has settled, no ticket may remain (a leaked
+     *  reservation would silently break `total ≡ free + reserved + committed`). */
+    assertNoOpenTickets(): void;
+}
+/** Fold a normalized `UsageEvent` array into a `Spend`. Tokens and usd are separate
+ *  channels; iterations come from `'iteration'` events. Pure; `ms` stays zero (the
+ *  pool does not read wall-clock). */
+declare function spendFromUsageEvents(events: UsageEvent[]): Spend;
+/**
+ * Create a conserved reservation pool from a root `Budget`. `now()` is injected so the
+ * deadline readout is deterministic; defaults to `Date.now` for non-test callers. The
+ * absolute deadline is fixed at construction (`now() + budget.deadlineMs`) so the
+ * readout's `deadlineMs` is a stable wall-clock instant, not a shrinking remainder.
+ */
+declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
+
+/**
+ * @experimental
+ *
+ * `driverAgent` — the driver's BRAIN.
+ *
+ * The recursive driver-executor (`driver-executor.ts`) runs a driver `Agent.act` inside a
+ * nested `Scope`; this is the intelligent `act`: it mounts the coordination MCP verbs
+ * (`createCoordinationTools`) over that scope and runs an LLM tool-loop, so the driver
+ * REASONS — spawn / observe / steer / await / stop — about how to drive its children,
+ * instead of running a fixed script. Each turn: ask the driver LLM for tool calls, run them
+ * against the live scope, fold the results back, repeat until the driver stops (no tool
+ * calls) or the turn cap forces a keep-best finalize.
+ *
+ * Recursion composes through `makeWorkerAgent`: `spawn_agent` resolves a `profile` to a
+ * worker LEAF or — when the profile is a driver — a `driverChild` wrapping ANOTHER
+ * `driverAgent` over its own nested scope (see `driver-executor.ts`). So an agent
+ * drives an agent that drives an agent, each an LLM tool-loop, all on one conserved-budget
+ * tree.
+ *
+ * Two seams are INJECTED so the loop runs offline with no creds and stays decoupled:
+ *  - `brain` (`ToolLoopChat`) — one driver-LLM turn over the canonical tool-loop seam; a test
+ *    drives a scripted mock, production passes the router's tool-calling (`routerBrain`), a
+ *    sandboxed harness drives the verbs as MCP tools. The same seam every tool-loop uses.
+ *  - `systemPrompt` — the driver's stance (the agent-eval worker-driver prompt / the prompt
+ *    generator). Injected, never hardcoded — the prompt is a pluggable role.
+ */
+
+interface DriverAgentOptions {
+    readonly name: string;
+    /** The driver-LLM seam — ONE inference turn over the conversation + the coordination tool specs
+     *  (the canonical `ToolLoopChat`): a scripted mock offline, the router's tool-calling in
+     *  production, or a sandboxed harness. The same seam every tool-loop uses; no bespoke shape. */
+    readonly brain: ToolLoopChat;
+    /** Shared blob store — `observe_agent` reads settled outputs through it. */
+    readonly blobs: ResultBlobStore;
+    /** Resolve a spawned `profile` to a worker LEAF or a driver child (the recursion seam). */
+    readonly makeWorkerAgent: MakeWorkerAgent;
+    /** Per-child budget reserved from the conserved pool on each spawn. */
+    readonly perWorker: Budget;
+    /** The driver's stance — a string, or built from the task (the worker-driver prompt /
+     *  the generator). INJECTED so the prompt is a pluggable, optimizable role. */
+    readonly systemPrompt: string | ((task: unknown) => string);
+    /** WORK tools the driver may call DIRECTLY (alongside the coordination verbs) — so the driver is
+     *  not a pure manager but a full agent that can ACT (do simple work itself) OR SPAWN (delegate).
+     *  Each is a router tool spec; their names must not collide with the coordination verbs. Pair with
+     *  `executeExtraTool`. Unset → coordination-only (the prior behavior). */
+    readonly extraTools?: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters: Record<string, unknown>;
+    }>;
+    /** Runs an `extraTools` call. Returns a string result, or null/undefined to signal "not handled"
+     *  so the call falls through to the coordination dispatch. Required iff `extraTools` is set. */
+    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
+    /** Max driver turns before the loop force-finalizes on the best settled child. Default 16.
+     *  `0` lifts the turn-COUNT cap: the loop is bounded instead by the conserved budget pool,
+     *  an absolute deadline, the driver's own stop, and abort (checked in-loop). A finite
+     *  anti-runaway tripwire still guards a degenerate driver that loops on a no-spawn tool. */
+    readonly maxTurns?: number;
+    /** Injected clock for the in-loop absolute-deadline guard — keeps the deadline check
+     *  deterministic in tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Build the intelligent recursive driver. Its `act` is the LLM tool-loop; spawn it as a
+ * `driverChild` (`driver-executor.ts`) to run it inside a nested scope, recursively.
+ */
+declare function driverAgent(opts: DriverAgentOptions): Agent<unknown, unknown>;
+/** Keep-best finalize under the completion-oracle: return the highest-scoring DELIVERED child's
+ *  output (settled `done` AND `valid` — its deliverable check passed). Returns undefined when no
+ *  child delivered — an honest "the driver produced nothing", never a high-scoring result that
+ *  ran without passing its check (Foreman's 0/18 lesson). `valid` is the single delivery signal,
+ *  matching `defaultSelectWinner`'s valid-first rule; the oracle just doesn't fall back to an
+ *  unchecked best-effort. */
+declare function finalizeBestDelivered(settled: ReadonlyArray<{
+    status: string;
+    score?: number;
+    valid?: boolean;
+    outRef?: string;
+}>, blobs: ResultBlobStore): Promise<unknown>;
+
+/**
+ * @experimental
+ *
+ * Serve the coordination verbs (spawn_agent / await_event / observe_agent / steer_agent / stop)
+ * as a real HTTP MCP server over a LIVE `Scope`. This is the keystone that lets a coding-harness
+ * agent (opencode via the cli-bridge, claude-code, codex) BE the supervisor: it mounts this MCP
+ * (`mcp.mcpServers.coordination`) and calls `spawn_agent` as a native tool, which lands on
+ * `Scope.spawn` — a real box driving real boxes, not emulated function-tools.
+ *
+ * Coordination vs DELEGATION (`../../mcp/delegates.ts`): coordination SPAWNS workers in a CHOSEN
+ * backend (`createExecutor({ backend })` — sandbox OR cli-bridge) and live-drives them — observe /
+ * steer / resume, recursive sub-drivers, one conserved budget. To instead delegate a coding task
+ * INSIDE the agent's OWN sandbox (a durable fire-and-poll job that survives an MCP restart), use the
+ * delegation MCP. Coordination is the live, cross-backend supervisor; delegation is own-sandbox async.
+ *
+ * Transport: JSON-RPC over HTTP POST (the MCP streamable-HTTP shape — `application/json` for a
+ * single response). The server is created INSIDE an agent's `act(task, scope)` so it fronts that
+ * agent's live scope; tear it down when the act returns.
+ */
+
+interface CoordinationMcpHandle {
+    /** The URL an in-box harness mounts as `mcp.mcpServers.coordination.url`. */
+    readonly url: string;
+    readonly port: number;
+    /** The coordination tools' settled-worker ledger (for the driver's finalize). */
+    settled(): ReadonlyArray<{
+        status: string;
+        score?: number;
+        valid?: boolean;
+        outRef?: string;
+    }>;
+    isStopped(): boolean;
+    /** The full ordered bus-event log — observability audit + replay trail. */
+    history: CoordinationTools['history'];
+    /** Bus throughput counters for live dashboards. */
+    stats: CoordinationTools['stats'];
+    /** Raise a `finding` on the bus from an online detector watching a worker's live pipe. */
+    raiseFinding: CoordinationTools['raiseFinding'];
+    close(): Promise<void>;
+}
+/** Stand up the coordination MCP over a live scope. The HOST address is `127.0.0.1` (the bridge runs
+ *  opencode locally, same host); pass `host` to bind elsewhere when the harness is remote. */
+declare function serveCoordinationMcp(opts: {
+    scope: Scope<unknown>;
+    blobs: ResultBlobStore;
+    makeWorkerAgent: MakeWorkerAgent;
+    perWorker: Budget;
+    port?: number;
+    host?: string;
+    /** Trace-analyst lenses the driver can run (`run_analyst`) or auto-fire on settle. */
+    analysts?: AnalystRegistry;
+    /** Analyst kinds to auto-run when a worker settles `done` — findings flow up the bus. */
+    analyzeOnSettle?: ReadonlyArray<string>;
+    /** Pass-through subscriber for every bus event (settled / question / finding). */
+    onEvent?: (event: CoordinationEvent) => void | Promise<void>;
+    questionPolicy?: QuestionPolicy;
+}): Promise<CoordinationMcpHandle>;
+
+/**
+ * @experimental
+ *
+ * `TraceSource` — the ONE substrate-agnostic source of a worker's tool-call trace. The online
+ * detectors and the settle-time analyzers consume agent-eval `ToolSpan`s from here, regardless of
+ * whether the worker is:
+ *   - an OWNED tool loop (router-tools, cli-bridge tool dispatch) → push spans as we dispatch them;
+ *   - a SANDBOX / fleet box → read the harness's tool calls off the session (`streamPrompt` parts
+ *     live, `session.messages()` / `findCompletedTurn` at settle).
+ *
+ * The common currency is agent-eval's `ToolSpan` (so the same detectors + `buildTrajectory`/
+ * `stuckLoopView`/`toolWasteView` run over any source). A source exposes two lanes:
+ *   - `onSpan` — live spans for ONLINE detection (best-effort; a black-box box may only collect).
+ *   - `collect` — the full span set at settle for the BATCH analyzers (always available).
+ *
+ * This module imports NO substrate SDK — it decodes generic message parts / OpenAI tool-call shapes.
+ * The sandbox wiring (`sandboxSessionTraceSource`) is the thin adapter that feeds box session parts in.
+ */
+
+interface ToolStepInput {
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly status?: 'ok' | 'error';
+    readonly result?: unknown;
+    /** Stable id of the tool call — used to de-duplicate the repeated state transitions a harness
+     *  streams for one call (opencode emits pending→running→completed, plus a `raw`-wrapped copy). */
+    readonly callId?: string;
+    /** Real per-call wall-clock when the source has it (owned tool-loop; opencode parts with `time`).
+     *  When omitted the span collapses to a single instant (`at`) — order + counts only, no duration. */
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+}
+interface TraceSource {
+    /** Subscribe to tool spans as they are produced (ONLINE). Returns an unsubscribe. A source that
+     *  only exposes its trace at the end registers nothing and returns a no-op. */
+    onSpan(handler: (span: ToolSpan) => void): () => void;
+    /** The full set of tool spans for the run (SETTLE / batch). Always available. */
+    collect(): Promise<ToolSpan[]>;
+}
+/** Decode a part with a specific harness's adapter when known, else try every registered adapter
+ *  (the composite — robust to mixed/unknown streams). Never throws. */
+declare function decodeToolPart(part: unknown, harness?: string): ToolStepInput | undefined;
+/** A push source for OWNED tool loops (router-tools / cli-bridge tool dispatch): the loop calls
+ *  `record(step)` for each tool call; it becomes a span, fan-out to live subscribers + buffered for
+ *  `collect`. */
+declare function createPushTraceSource(opts?: {
+    runId?: string;
+    now?: () => number;
+}): {
+    source: TraceSource;
+    record: (input: ToolStepInput) => ToolSpan;
+};
+/** A harness session message carrying parts (the shape `box.messages()` returns). Structurally typed
+ *  so this works with the real `@tangle-network/sandbox` box AND a test double, no SDK import. */
+interface SessionMessageLike {
+    readonly parts?: ReadonlyArray<unknown>;
+}
+/** The minimal box surface this needs: list a session's messages (incl. mid-turn partials). */
+interface SessionTraceBox {
+    messages(opts: {
+        sessionId: string;
+    }): Promise<ReadonlyArray<SessionMessageLike>>;
+}
+/** The SANDBOX / fleet trace source: read a box session's message parts and decode the harness's tool
+ *  calls into spans. `collect` (settle) is the solid path — `box.messages({sessionId})` → parts → spans;
+ *  black-box harnesses aren't mid-step interruptible, so online steering is the owned-loop's job and a
+ *  live `subscribe` is opt-in (pass `subscribeParts` from `streamPrompt` when the harness streams parts). */
+declare function sandboxSessionTraceSource(box: SessionTraceBox, sessionId: string, opts?: {
+    /** The box's harness (e.g. 'opencode', 'claude-code') → selects its decoder adapter. */
+    harness?: string;
+    subscribeParts?: (onPart: (part: unknown) => void) => () => void;
+    runId?: string;
+    now?: () => number;
+}): TraceSource;
+
+/**
+ * @experimental
+ *
+ * The ONLINE analyst: watch a `TraceSource` and fold each tool span through agent-eval's published
+ * streaming detector kernel (`repeatedActionDetector`/`errorStreakDetector` — the SAME kernel the
+ * control loop folds), firing `onSignal` the moment a worker loops or error-storms. Substrate-
+ * agnostic: it consumes spans from any source (owned router/bridge loop OR a sandbox box session),
+ * never the raw tool seam. Detection logic + the failure taxonomy live in agent-eval; not reimplemented.
+ */
+
+interface WatchTraceOptions {
+    /** The detectors to run online. Defaults to a stuck-loop + error-streak panel. */
+    readonly detectors?: ReadonlyArray<StreamingDetector>;
+    /** Fired for each signal a detector raises — the seam that raises a `finding` on the bus. */
+    readonly onSignal?: (signal: DetectorSignal, span: ToolSpan) => void | Promise<void>;
+}
+/** The default online panel for a tool-call pipe: a worker repeating the same call, or hammering
+ *  consecutive errors. (No-progress needs a domain progress-probe, so it is opt-in, not default.)
+ *
+ *  Coverage note: `repeated-action` works for EVERY harness (it needs only tool name + args, which
+ *  every adapter provides). `error-streak` needs per-call status — opencode carries it inline
+ *  (`state.status`, VALIDATED live), but claude-code/codex tool-call parts do NOT (their errors live
+ *  in separate result blocks not yet decoded), so error-streak is silent for those until result-block
+ *  decoding is added + live-validated. It is in the panel because it is correct where status exists. */
+declare function defaultToolDetectors(): StreamingDetector[];
+/** Subscribe to a `TraceSource` and run the streaming detectors over its live spans. Returns an
+ *  unsubscribe. A defensive `argHash` failure (circular args) never throws out of the side-channel. */
+declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () => void;
+
+/**
+ * @experimental
+ *
+ * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
+ * `Executor.deliver`. The driver's `steer_agent` / `answer_question` land here,
+ * and the worker's agent loop drains them at two points (Drew's two delivery modes):
+ *
+ *   - QUEUED (default): the message accumulates and is FLUSHED at the next step boundary — folded
+ *     into the conversation before the next think. A worker is also forced to flush BEFORE it may
+ *     settle, so it can never finish while a steer/answer it never read is still pending.
+ *   - FORCEFUL (`interrupt: true`): trips `freshInterrupt()`'s signal so the loop can abort its
+ *     in-flight turn immediately, then re-plan with the message folded in — breaking the worker out
+ *     of a wrong path mid-task instead of waiting for it to finish the step.
+ *
+ * `deliver` never throws — a malformed message is ignored, per the `Executor.deliver` contract.
+ */
+interface InboxMessage {
+    readonly kind: 'steer' | 'answer';
+    readonly text: string;
+    /** Forceful messages abort the in-flight turn; queued ones wait for the boundary flush. */
+    readonly interrupt: boolean;
+    /** Present for an `answer` — the question id it resolves. */
+    readonly questionId?: string;
+}
+interface Inbox {
+    /** The `Executor.deliver` implementation — accept a raw down-message from `Scope.send`. */
+    deliver(msg: unknown): void;
+    /** Remove and return all pending messages (the flush). */
+    drain(): InboxMessage[];
+    pending(): number;
+    /** Open a fresh per-turn interrupt signal; a later forceful `deliver` aborts it. The loop links
+     *  this into the signal it passes to its inference call, then re-plans when it fires. */
+    freshInterrupt(): AbortSignal;
+    /** Render drained messages as ONE operator turn to fold into the worker's conversation. */
+    fold(messages: ReadonlyArray<InboxMessage>): string;
+}
+declare function createInbox(): Inbox;
+
+/**
+ * Throw a `ConfigError` when `allowed` is set, `model` is defined, and `model` is not a
+ * member of `allowed`. No-op when `allowed` is unset (the unrestricted default) or when
+ * `model` is undefined (nothing was configured to check).
+ */
+declare function assertModelAllowed(model: string | undefined, allowed: readonly string[] | undefined): void;
+
+/**
+ * @experimental
+ *
+ * `createInMemoryRunContext` — the one-call bundle of the in-memory stores a
+ * `createSupervisor().run(root, task, opts)` needs: a fresh `InMemorySpawnJournal`
+ * (the event-sourced spawn log), a fresh `InMemoryResultBlobStore` (the
+ * content-addressed `outRef` payload store the driver's `observe`/`finalize` reads
+ * settled outputs through), and a fresh `createExecutorRegistry()` (the open
+ * `AgentSpec → Executor` resolver).
+ *
+ * It exists to kill the boilerplate every offline/local supervised run repeats by
+ * hand — three constructors threaded into `SupervisorOpts` — and to single-source the
+ * ONE wiring invariant that is easy to get wrong: when the root is the recursive
+ * `driverAgent` LLM-driver brain AND it may spawn DRIVER children (agents
+ * driving agents), the registry MUST be wrapped with `withDriverExecutor` so a
+ * `role: 'driver'` child resolves to the nested-scope executor — and that SAME blob
+ * store MUST be the one passed to `driverAgent({ blobs })`, or the driver
+ * reads from a different store than the scope writes to. Pass `{ withDriver: true }`
+ * and reuse the returned `blobs` for both.
+ *
+ * The spread shape matches `SupervisorOpts` exactly, so the call site reads:
+ *   const run = createInMemoryRunContext()
+ *   await createSupervisor().run(root, task, { budget, runId, ...run })
+ */
+
+/** Options for the in-memory run context. */
+interface InMemoryRunContextOptions {
+    /**
+     * Wrap the executor registry with `withDriverExecutor` so a spawned child marked
+     * `role: 'driver'` resolves to the recursive driver-executor (agents driving agents
+     * over a nested `Scope` on the same conserved pool). Leave `false` for a flat tree of
+     * leaf workers. Default `false`.
+     */
+    readonly withDriver?: boolean;
+}
+/**
+ * The bundle of stores a supervised run needs, shaped to spread into `SupervisorOpts`.
+ * The fields are exactly `SupervisorOpts`' `journal` / `blobs` / `executors`.
+ */
+interface InMemoryRunContext {
+    readonly journal: SpawnJournal;
+    readonly blobs: ResultBlobStore;
+    readonly executors: ExecutorRegistry;
+}
+/**
+ * Build a fresh in-memory run context. Every call returns NEW stores (no shared global
+ * state between runs), so two runs never cross-contaminate their journals/blobs.
+ */
+declare function createInMemoryRunContext(opts?: InMemoryRunContextOptions): InMemoryRunContext;
+
+/**
+ * @experimental
+ *
+ * The leaf runtime — the built-in `Executor` IMPLEMENTATIONS behind the ONE
+ * open interface frozen in `./types`, plus the open resolver/registry that maps
+ * an `AgentSpec` to one of them OR accepts a bring-your-own executor verbatim.
+ *
+ * The interface is the extension point, not a closed `inline|sandbox|cli` union:
+ *   - router/inline : a direct OpenAI-compatible Router call, no box (one-shot).
+ *   - sandbox       : COMPOSES the existing `runLoop` kernel as a single-task
+ *                     leaf and surfaces its token/cost usage as `UsageEvent`s;
+ *                     forwards PR #150's optional `lineage` passthrough WITHOUT
+ *                     reinventing checkpoint/fork (streaming).
+ *   - cli           : a Halo/RLM subprocess; `budgetExempt` (no token accounting),
+ *                     excluded from the equal-k arms by construction (streaming).
+ * Every metered runtime reports through the SAME normalized `UsageEvent` channel
+ * so the conserved budget pool meters them identically. A user's own agent is
+ * first-class the moment it implements `Executor` — register it by name or
+ * pass it as `AgentSpec.executor`.
+ *
+ * Layering: `estimateCost`/`isModelPriced` are substrate primitives from
+ * `@tangle-network/agent-eval`; `runLoop`/`acquireSandbox` are runtime kernels
+ * from this package. No per-vendor adapters live here.
+ */
+
+/**
+ * Router/inline connection seam. A direct OpenAI-compatible Router endpoint —
+ * the cheapest leaf, no box, no tools. `model` overrides the profile's model
+ * hint when present; otherwise the profile's `model.default` is required.
+ */
+interface RouterSeam {
+    routerBaseUrl: string;
+    routerKey: string;
+    model?: string;
+}
+/**
+ * Sandbox executor seam. The `sandboxClient` the composed `runLoop` creates
+ * boxes through, plus the optional trace/run/lineage wiring forwarded into the
+ * loop. `lineage` is opaque here (PR #150's `RunLoopOptions.lineage`): forwarded
+ * forward-compatibly, never inspected — this executor does NOT reinvent
+ * checkpoint/fork.
+ */
+interface SandboxSeam {
+    sandboxClient: SandboxClient;
+    /** Forwarded into the composed `runLoop`'s `ctx` (trace emitter, run handle, etc.). */
+    loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
+    /** PR #150 `RunLoopOptions.lineage` passthrough — opaque; forwarded, not parsed. */
+    lineage?: unknown;
+    /** Hard cap on the composed loop's iterations. The budget pool reserves against
+     *  the spawn `Budget.maxIterations`; this is the leaf's own ceiling. Default 1. */
+    maxIterations?: number;
+}
+/** CLI subprocess seam. `bin` + `args` describe the Halo/RLM process to spawn. */
+interface CliSeam {
+    bin: string;
+    args?: string[];
+    /** Extra environment for the subprocess (merged over `process.env`). */
+    env?: Record<string, string>;
+    /** Working directory for the subprocess. */
+    cwd?: string;
+}
+/**
+ * cli-worktree seam. A supervisor-authored `AgentProfile` driving a local coding-harness CLI
+ * (claude / codex / opencode) on its own git worktree — the leaf `createWorktreeCliExecutor`
+ * named as data. `harness` + `repoRoot` + `taskPrompt` are required; the authored
+ * `profile.prompt.systemPrompt` + `profile.model.default` reach the harness via the §1.5
+ * `harnessInvocation` mapper. Everything else mirrors `WorktreeCliExecutorOptions`.
+ */
+interface CliWorktreeSeam {
+    repoRoot: string;
+    harness: LocalHarness;
+    taskPrompt: string;
+    runId?: string;
+    baseRef?: string;
+    harnessTimeoutMs?: number;
+}
+/**
+ * cli-bridge seam. A local OpenAI-compatible bridge that fronts harness CLIs
+ * (claude-code / opencode / kimi / pi) behind one HTTP surface; `model` doubles
+ * as the harness selector (e.g. `claude-code/sonnet`, `opencode/<provider>/<model>`).
+ * `agentProfile` is the bridge-dialect profile (metadata.disallowedTools, mcp)
+ * forwarded verbatim per request — how an arm disables native tools or injects
+ * a provider search MCP.
+ *
+ * The executor opens a RESUMABLE cli-bridge session — structurally identical to the
+ * sandbox executor's persistent box, just local. `sessionId` is the stable
+ * caller-owned id cli-bridge maps to the harness's internal conversation id; a
+ * follow-up steer/resume on the SAME id continues the SAME harness session (opencode
+ * `-s`, claude `--resume`, …). Omit it and the executor mints a stable one per spawn.
+ */
+interface BridgeSeam {
+    bridgeUrl: string;
+    bridgeBearer: string;
+    model: string;
+    agentProfile?: Record<string, unknown>;
+    timeoutMs?: number;
+    /** Stable, caller-owned cli-bridge session id for harness-side resume. Defaults
+     *  to a freshly minted per-spawn id so each worker is its own resumable session. */
+    sessionId?: string;
+    /** Per-resume-turn inference cap before the worker settles on its last output.
+     *  Mirrors `routerToolsInlineExecutor.maxTurns`; default 200 (runaway backstop). */
+    maxTurns?: number;
+}
+/**
+ * Router seam WITH tool use — the tool-using router backend. Same direct
+ * OpenAI-compatible endpoint as `RouterSeam`, but each turn passes `tools`; when
+ * the model emits tool_calls they run via `executeToolCall` ON THIS HOST and the
+ * results fold back as `tool` messages, repeating until the model answers without
+ * a tool or `maxTurns` is hit. A real agentic loop, OFF-BOX — no sandbox, so it
+ * is unaffected by a box's egress allowlist. One turn = one completion = the
+ * equal-compute unit. `executeToolCall` receives the task so per-task tool
+ * surfaces (e.g. a gym keyed by task) can dispatch correctly.
+ */
+interface RouterToolsSeam {
+    routerBaseUrl: string;
+    routerKey: string;
+    model?: string;
+    tools: ReadonlyArray<ToolSpec>;
+    executeToolCall: (name: string, args: Record<string, unknown>, task: unknown) => Promise<string>;
+    /** Online observer of each tool step — the seam a `DetectorMonitor` taps to watch the live pipe
+     *  (raise a `finding` when the worker loops/errors). Called after every tool call resolves, with
+     *  real per-call wall-clock (`startedAt`/`endedAt`/`durationMs`) so a push `TraceSource` can carry
+     *  non-zero span durations onto the unified timeline. */
+    onToolStep?: (step: {
+        toolName: string;
+        args: Record<string, unknown>;
+        status: 'ok' | 'error';
+        startedAt?: number;
+        endedAt?: number;
+        durationMs?: number;
+    }) => void;
+    /** Max inference turns. Default 200 (runaway backstop — set far above any
+     *  legitimate workflow). For tighter per-workflow limits use a cost budget
+     *  or wall-clock deadline at the call site. */
+    maxTurns?: number;
+}
+/**
+ * The leaf `createWorktreeCliExecutor` as a backend-as-data factory: a supervisor-authored
+ * `AgentProfile` driving claude / codex / opencode on its own worktree. `budgetExempt` like
+ * the other CLI leaves; the authored systemPrompt + model reach the harness via §1.5.
+ */
+declare const cliWorktreeExecutor: ExecutorFactory<unknown>;
+/**
+ * Config for {@link createExecutor}: the backend is DATA — the cost dial a profile,
+ * an experiment config, or a replay journal can name — not an import choice. Each
+ * variant carries its backend's seam (router/router-tools/bridge/cli/cli-worktree/sandbox).
+ */
+type ExecutorConfig = ({
+    backend: 'router';
+} & RouterSeam) | ({
+    backend: 'router-tools';
+} & RouterToolsSeam) | ({
+    backend: 'bridge';
+} & BridgeSeam) | ({
+    backend: 'cli';
+} & CliSeam) | ({
+    backend: 'cli-worktree';
+} & CliWorktreeSeam) | ({
+    backend: 'sandbox';
+    harness?: BackendType;
+} & SandboxSeam);
+/**
+ * The single built-in executor factory. Picks a leaf backend by data (`config.backend`),
+ * injects the matching seam, and delegates to that backend's built-in implementation.
+ * The `Executor` port stays OPEN: bring-your-own agents implement `Executor` directly
+ * and never pass through here. Use this (or `createExecutorRegistry`) instead of a
+ * per-vendor adapter or a closed `inline|sandbox|cli` switch — those bypass the
+ * `UsageEvent` reporting channel.
+ */
+declare function createExecutor(config: ExecutorConfig): ExecutorFactory<unknown>;
+/**
+ * The open resolver/registry. Pre-registers the three built-ins under their
+ * runtime tags (`'router'`, `'sandbox'`, `'cli'`) and accepts `register(name,
+ * factory)` for any additional runtime — and a BYO `AgentSpec.executor` resolves
+ * without touching the registry at all. NOT a closed switch; registration + BYO
+ * ARE the extension points.
+ *
+ * `resolve` precedence (frozen in `ExecutorRegistry`): a BYO `spec.executor` →
+ * `harness === null` → the `'router'` factory; else a registered factory for the
+ * harness-derived runtime (`'sandbox'` for any `BackendType`); else fail loud.
+ */
+declare function createExecutorRegistry(): ExecutorRegistry;
+
+/**
+ * @experimental
+ *
+ * The reactive `Scope` impl (KEYSTONE, build step 4 + the step-8 adapter).
+ *
+ * An `Agent.act` runs inside a `Scope`. It `spawn`s children dynamically and reacts to
+ * them via `next()`. The scope owns ONE in-memory nursery — the authoritative live set —
+ * and is the single place that drives a child's lifecycle: reserve budget atomically,
+ * resolve a `Executor` through the open registry, run it (one-shot OR streaming),
+ * fold its normalized `UsageEvent`s into a conserved `Spend`, reconcile the reservation
+ * (refunding the unspent remainder), persist the result blob + journal records, and
+ * deliver the `Settled` through the `next()` cursor.
+ *
+ * Three invariants this impl enforces by construction:
+ *  - `next()` is a ray.wait n=1 cursor over THIS scope's live set; it assigns the
+ *    monotonic `seq` (the recorded cursor order) at the moment it yields a settlement, so
+ *    replay re-delivers in the identical order — `seq` is never wall-clock.
+ *  - Budget is reserved at spawn and reconciled at settle through the shared `BudgetPool`,
+ *    so `spawn` fails CLOSED on an exhausted pool and total ≡ free + reserved + committed.
+ *  - `view` reads the in-memory nursery, never the journal — O(live), synchronous.
+ *
+ * The settle path is the only writer of journal `settled` events; the spawn path the only
+ * writer of `spawned` events. The result blob is `put` BEFORE the journal `settled` record
+ * references its `outRef`, so a crash can never leave a journaled ref with no blob.
+ */
+
+/** Construction args for `createScope`. The supervisor threads the shared pool, journal,
+ *  blob store, and executor registry through; `depth`/`maxDepth` pair the runtime
+ *  recursion ceiling with the conserved pool (R3). */
+interface ScopeArgs {
+    /** This scope's owning node id — children get `${parentId}:s${seq}` ids. */
+    readonly parentId: NodeId;
+    /** Journal/blob root key the supervisor `beginTree`'d. */
+    readonly root: NodeId;
+    /** The shared conserved reservation pool (one per supervised run). */
+    readonly pool: BudgetPool;
+    /** Append-only spawn journal; this scope writes `spawned` + `settled` records. */
+    readonly journal: SpawnJournal;
+    /** Content-addressed result store backing `outRef` rehydration. */
+    readonly blobs: ResultBlobStore;
+    /** The open executor resolver (BYO → router/inline → registered harness factory). */
+    readonly executors: ExecutorRegistry;
+    /** Per-spawn executor-construction seams (sandbox client, router config, cli bin). */
+    readonly seams: Readonly<Record<string, unknown>>;
+    /** This scope's recursion depth (root = 0). */
+    readonly depth: number;
+    /** Runtime recursion-depth ceiling — a spawn past it fails closed `depth-exceeded`. */
+    readonly maxDepth?: number;
+    /** Abort signal for this scope; an abort cascades into every live child's executor. */
+    readonly signal: AbortSignal;
+    /** Injected clock — keeps the journal `at` timestamp deterministic in tests. */
+    readonly now?: () => number;
+    /** Lifecycle stream sink. `spawn` emits `agent.spawn`, `next` emits `agent.child` — the
+     *  SAME stream `runLoop`/`tool-loop` feed, so the recursive tree is ONE observable stream
+     *  (the topology viewer reads it). Undefined ⇒ the journal stays the only record. */
+    readonly hooks?: RuntimeHooks;
+}
+declare function createScope<Out>(args: ScopeArgs): Scope<Out>;
+/**
+ * The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's
+ * `Iteration` shape so `defaultSelectWinner` stays single-sourced — the supervisor selects
+ * across settled children with the SAME argmax the loop kernel uses, not a forked copy.
+ *
+ * `index` is the cursor `seq` (the recorded, replay-stable order); `output`/`verdict`/
+ * `tokenUsage`/`costUsd` are read straight off the settlement (already rehydrated from the
+ * `outRef` blob by `next()`). Events are empty — a settled child is an opaque leaf result,
+ * not a sandbox event stream — and the timing/cost fields project its conserved `Spend`.
+ * Fail loud on a `down` settlement: only a `done` child is an iteration.
+ */
+declare function settledToIteration<Out>(settled: Settled<Out>): Iteration<unknown, Out>;
+
+/** The supervisor's profile — the subset of an `AgentProfile` that selects + shapes its brain.
+ *  `harness` is the backend-as-data discriminant; `systemPrompt` is the standing instruction. */
+interface SupervisorProfile {
+    readonly name?: string;
+    /** null/undefined → router brain (in-process tool-loop); a coding-CLI harness → sandboxed brain. */
+    readonly harness?: string | null;
+    /** The router model when the brain is router-driven (falls back to the deps router config). */
+    readonly model?: string;
+    /** The standing instructions ("you delegate, you do not solve"). */
+    readonly systemPrompt?: string;
+}
+/** How to run a sandboxed harness as the DRIVER, with the coordination verbs mounted — the substrate
+ *  seam the caller supplies (mirrors `makeWorkerAgent` for spawned children). It runs `profile` on
+ *  `task` in its backend (sandbox / cli-bridge) with `coordinationMcpUrl` mounted as an MCP server,
+ *  so the harness calls spawn_agent / await_event / stop as native tools over the live scope. */
+type DriveHarness = (args: {
+    readonly profile: SupervisorProfile;
+    readonly task: unknown;
+    readonly scope: Scope<unknown>;
+    readonly coordinationMcpUrl: string;
+}) => Promise<void>;
+interface SupervisorAgentDeps {
+    readonly blobs: ResultBlobStore;
+    /** Resolve a spawned worker `profile` to a leaf agent — the recursion seam (same for both arms). */
+    readonly makeWorkerAgent: MakeWorkerAgent;
+    /** Per-child budget reserved from the conserved pool on each spawn. */
+    readonly perWorker: Budget;
+    /** Router substrate for a router-brained supervisor (`harness` null). The profile's model wins. */
+    readonly router?: RouterConfig;
+    /** Inject the brain directly (tests / advanced) instead of resolving `routerBrain` from the profile. */
+    readonly brain?: ToolLoopChat;
+    /** Required for a sandboxed-harness supervisor (`harness` set): runs the harness as the driver. */
+    readonly driveHarness?: DriveHarness;
+    /** WORK tools the supervisor may call DIRECTLY (router arm) — so it can do simple work ITSELF and
+     *  only delegate when it needs parallelism. Pair with `executeExtraTool`. */
+    readonly extraTools?: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters: Record<string, unknown>;
+    }>;
+    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
+    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
+    readonly maxTurns?: number;
+}
+declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAgentDeps): Agent<unknown, unknown>;
+
+/** Build the worker seam from a backend (WHERE workers run) + an optional completion oracle (the
+ *  deliverable check that makes "settled ⟺ delivered" true — the guard against "ran but didn't
+ *  deliver"). The ONE place a backend becomes a spawnable worker. */
+declare function workerFromBackend(backend: ExecutorConfig, deliverable?: DeliverableSpec<unknown>): MakeWorkerAgent;
+interface SuperviseOptions {
+    /** The conserved compute pool for the whole run. */
+    readonly budget: Budget;
+    /** WHERE workers run — derives the worker seam. Provide this OR an explicit `makeWorkerAgent`. */
+    readonly backend?: ExecutorConfig;
+    /** The completion oracle for backend-derived workers (settled ⟺ delivered). Strongly recommended:
+     *  without it the supervisor trusts a worker's self-report — exactly the "ran but didn't deliver"
+     *  failure mode of a static orchestrator. */
+    readonly deliverable?: DeliverableSpec<unknown>;
+    /** Override the worker seam directly (tests / advanced) instead of deriving it from `backend`. */
+    readonly makeWorkerAgent?: MakeWorkerAgent;
+    /** The supervisor's router substrate (`harness` null). The profile's model wins. */
+    readonly router?: RouterConfig;
+    /** Inject the supervisor brain directly (tests / advanced). */
+    readonly brain?: ToolLoopChat;
+    /** Run a sandboxed-harness supervisor (`harness` set). */
+    readonly driveHarness?: DriveHarness;
+    /** 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 (`harness` null). */
+    readonly extraTools?: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters: Record<string, unknown>;
+    }>;
+    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
+    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
+    /** Per-child budget reserved on each spawn. Defaults to a quarter of the pool's tokens. */
+    readonly perWorker?: Budget;
+    /** Worker output store. Defaults to in-memory. */
+    readonly blobs?: ResultBlobStore;
+    readonly maxDepth?: number;
+    readonly maxTurns?: number;
+    readonly runId?: string;
+    readonly now?: () => number;
+    /** 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. */
+    readonly allowedModels?: readonly string[];
+}
+declare function supervise(profile: SupervisorProfile, task: unknown, opts: SuperviseOptions): Promise<SupervisedResult<unknown>>;
+
+/**
+ * @experimental
+ *
+ * The `Supervisor` impl (KEYSTONE, build step 5).
+ *
+ * Owns the four things a free-running recursive `act` cannot own itself: the GLOBAL
+ * conserved budget pool, the event-sourced spawn log, the abort cascade over the whole
+ * live tree, and the OTP intensity breaker. `run` builds the root `Scope` over those,
+ * runs the root `Agent.act`, and returns a TYPED `SupervisedResult` — a no-winner is
+ * never coerced into a best-effort `Out`.
+ *
+ * Three lifecycle invariants this impl enforces by construction:
+ *  - Join barrier: when `act()` settles (resolve OR reject), every still-live child is
+ *    torn down before `run` returns — the generalization of the kernel's
+ *    `finally{ Promise.allSettled(destroy) }` barrier (run-loop.ts) from boxes to the
+ *    whole sub-tree. A teardown failure is `allSettled`'d and journaled as a
+ *    `cancelled` event; it NEVER masks act()'s own outcome. act()'s rejection is the
+ *    PRIMARY error (the kernel's firstError precedence), so a teardown throw during the
+ *    barrier can never overwrite the real failure.
+ *  - Abort cascade: a root abort (caller signal, `RootHandle.abort`, a tripped breaker,
+ *    or pool exhaustion) aborts ONE internal controller whose signal is the root scope's
+ *    signal. The scope cascades that into every live child's executor abort — which, for
+ *    an `acquiring` child, chains into the `acquireSandbox` signal and reaps the
+ *    find-by-name orphan box (M1). The supervisor never reaps children directly.
+ *  - The supervisor NEVER re-enters a child (m3): the kernel/`acquireSandbox` already
+ *    retried at the leaf, and a driver re-spawns through `scope.spawn`. The breaker only
+ *    COUNTS `down` settlements within the intensity window and trips to a typed
+ *    no-winner; it does not restart anything.
+ *
+ * Selection lives in the driver, not here (selector≠judge): `act` returns the synthesized
+ * winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`, reads
+ * `spentTotal` off the journal (`settled` child work + `metered` driver inference), and wraps
+ * it as a typed `winner` — it does not re-rank children behind the driver's back.
+ */
+
+declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
+
+/**
+ * @experimental
+ *
+ * The SETTLE-time analyst: when a worker finishes, collect its tool spans from a `TraceSource` and run
+ * agent-eval's PUBLISHED batch analyzers over them — `buildTrajectory` (structured run summary),
+ * `stuckLoopView` (full-run repeated-call view, complementing the online consecutive detector), and
+ * `toolWasteView`. Substrate-agnostic: the spans come from any source (an owned loop's buffer OR a
+ * sandbox box session). No analysis reimplemented — this is the thin bridge into agent-eval's analyzers.
+ */
+
+interface TrajectoryAnalysis {
+    /** Structured run summary (tool-call count, step order). Steps carry a single timestamp, so per-span
+     *  duration is 0; loop/waste detection keys on call PATTERNS + cross-span windows, not durations. */
+    readonly trajectory: Awaited<ReturnType<typeof buildTrajectory>>;
+    /** Full-run repeated-call view (total occurrences + window) — catches a loop the online consecutive
+     *  detector interleaves past. */
+    readonly stuckLoop: Awaited<ReturnType<typeof stuckLoopView>>;
+    /** Wasted-vs-total tool-call ratio for the run. */
+    readonly toolWaste: Awaited<ReturnType<typeof toolWasteView>>;
+}
+/** Collect the source's spans and run the agent-eval batch analyzers over them under one `runId`. */
+declare function analyzeTrace(source: TraceSource, runId?: string): Promise<TrajectoryAnalysis>;
+
+/**
+ * createVerifierEnvironment — ANY checkable task as an `Environment`, no tool surface
+ * required. The generalization piece: EOPS/commit0-style domains have tools that mutate
+ * an external artifact, but math problems, legal drafts, creative briefs, GTM copy, and
+ * QA tasks have a different shape — the artifact IS the worker's answer, and the domain
+ * is defined by one function: the deployable check over that answer.
+ *
+ *   const gsm8k = createVerifierEnvironment({
+ *     name: 'gsm8k',
+ *     check: (task, answer) => ({
+ *       passes: extractFinalNumber(answer) === task.meta?.answer ? 1 : 0,
+ *       total: 1,
+ *       errored: 0,
+ *     }),
+ *   })
+ *   await runBenchmark({ environment: gsm8k, tasks, worker })   // sample vs refine on math
+ *
+ * The worker gets one built-in tool — `submit_answer` — plus any read-only domain tools
+ * the caller adds (a calculator, a retrieval call, a style guide lookup). Every
+ * submission is kept; `score()` checks the BEST submission (keep-best is the measured
+ * law: workers reach correct answers then revise past them). The refine strategy's
+ * critic reads the submission trajectory like any other trace, so iterate-with-feedback
+ * works unchanged on answer domains.
+ *
+ * The check can be graded (passes/total expresses partial credit — rubric points,
+ * sub-answers, unit-test counts), and MUST be deployable (computable without an oracle
+ * at serve time): exact/numeric match, schema validation, a compiled rubric — not a
+ * peek at held-out labels the production system wouldn't have.
+ */
+
+interface VerifierEnvironmentOptions {
+    name: string;
+    /** The deployable check over a submitted answer. Graded via passes/total. */
+    check(task: AgenticTask, answer: string): Promise<SurfaceScore> | SurfaceScore;
+    /** Extra domain tools (read-only helpers: calculator, retrieval, style lookup). */
+    extraTools?: AgenticTool[];
+    /** Executes the extra tools. Required when `extraTools` is set. */
+    callExtra?(task: AgenticTask, name: string, args: Record<string, unknown>): Promise<string> | string;
+}
+declare function createVerifierEnvironment(opts: VerifierEnvironmentOptions): Environment;
+
+/** Command runner seam. Host code can use `localShell`; sandbox code can wrap `box.exec`. */
+type Shell = (args: ReadonlyArray<string>, cwd?: string) => Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+type WorkspaceCommit = {
+    readonly ok: true;
+    readonly rev: string;
+} | {
+    readonly ok: false;
+    readonly conflict: string;
+};
+interface Workspace {
+    readonly ref: string;
+    materialize(dir: string): Promise<void>;
+    commit(dir: string, message: string): Promise<WorkspaceCommit>;
+    head(): Promise<string>;
+}
+declare function localShell(): Shell;
+interface GitWorkspaceOptions {
+    readonly ref: string;
+    readonly shell?: Shell;
+    readonly branch?: string;
+    readonly noHooks?: boolean;
+}
+declare function gitWorkspace(opts: GitWorkspaceOptions): Workspace;
+/** A jj-backed `Workspace` (Jujutsu, colocated with git for the durable remote).
+ *  Same port, same `Shell` — a drop-in for `gitWorkspace`. jj suits agent loops:
+ *  no staging area, and a first-class operation log (native resume/undo). Live use
+ *  requires `jj` on the `Shell`'s host. */
+declare function jjWorkspace(opts: GitWorkspaceOptions): Workspace;
+interface WorkspaceRun<T> {
+    readonly valid: boolean;
+    readonly value: T;
+    /** Present when a commit was attempted (valid, or `commitOnInvalid`). */
+    readonly commit?: WorkspaceCommit;
+}
+/**
+ * Run a worker `body` inside a FRESH clone of a shared `Workspace`, then commit its work back
+ * so the next worker (or the supervisor) builds on it. This is the seam that turns isolated
+ * per-worker cwds into one compounding artifact — `body` gets a real materialized dir, its
+ * delivery is committed to the shared ref iff it's valid (a conflict is returned, never thrown).
+ * The clone is removed after; durable state lives only in the ref.
+ */
+declare function runInWorkspace<T>(ws: Workspace, body: (cwd: string) => Promise<{
+    valid: boolean;
+    value: T;
+    message?: string;
+}>, opts?: {
+    tmpPrefix?: string;
+    commitOnInvalid?: boolean;
+}): Promise<WorkspaceRun<T>>;
+
+export { Agent, AgentRunSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ArtifactHandle, AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type Deliverable, DeliverableSpec, type DriveHarness, Driver, type DriverAgentOptions, type Environment, EqualKArm, EqualKOnCostOptions, EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, type ExecutorConfig, FanoutOptions, FanoutWinnerSelector, FileCorpus, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, type InMemoryRunContext, type InMemoryRunContextOptions, InMemorySpawnJournal, type Inbox, type InboxMessage, type IntentAudit, Iteration, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, type McpEndpoint, type McpEnvironmentOptions, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, Outcome, OutputAdapter, PanelSpec, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RouterConfig, type RunAgenticOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, type SessionTraceBox, Settled, ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, Spend, SteerContext, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, type SuperviseOptions, SupervisedResult, Supervisor, type SupervisorAgentDeps, type SupervisorProfile, type SurfaceScore, ToolLoopChat, ToolSpec, type TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, breadthStrategy, buildSteerContext, builtinShapes, cliWorktreeExecutor, completionAuthorizes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createInMemoryRunContext, createInbox, createMcpEnvironment, createPushTraceSource, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultProfileRichnessThresholds, defaultSelectWinner, defaultToolDetectors, definePersona, defineStrategy, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, equalKOnCost, extractLlmCallEvent, fanout, finalizeBestDelivered, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, reportLoopUsage, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, supervise, supervisorAgent, supervisorInstructions, trajectoryReport, verify, watchTrace, widen, workerFromBackend };