@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/loops.d.ts

@@ -1,4164 +1,5 @@
-import { ChatClient, RunRecord, HarnessType, AgentProfile, MaximumCharge, AnalystFinding, AnalystRunInputs, buildTrajectory } from '@tangle-network/agent-eval';
-export { AnalystFinding, DefaultVerdict, computeFindingId, makeFinding } from '@tangle-network/agent-eval';
-import { SandboxEvent, SandboxInstance, CreateSandboxOptions, PromptOptions, TaskOptions } from '@tangle-network/sandbox';
-export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { b as ResultBlobStore, c as SpawnJournal, N as NodeId, l as SpawnEvent, m as TreeView, P as PendingWait, a as Settled, E as ExecutorFactory, A as Agent, B as Budget, S as Scope, e as SupervisedResult, g as Spend, U as UsageEvent, n as SpawnOpts, i as ExecutorRegistry, d as WaitProbeRegistry, o as Supervisor, T as TraceSource } from './types-CvNwMzQt.js';
-export { p as ActivityLog, q as ActivityNote, h as AgentSpec, D as DEFAULT_STALL_AFTER_MS, f as Executor, r as ExecutorContext, k as ExecutorProgress, s as ExecutorResult, t as ResumedWork, R as Runtime, u as ScopeProgressInput, v as SessionTraceBox, w as SupervisorOpts, x as WaitOutcome, y as WaitProbe, z as WaitRejection, C as WaitSpec, F as WidenGate, W as WorkerProgress, G as createActivityLog, H as createPushTraceSource, I as createWaitProbes, J as decodeToolPart, K as isWaitOutcome, L as pollFor, M as readWorkerProgress, O as sandboxSessionTraceSource, Q as timerAt, V as validateWaitSpec, X as waitUntil } from './types-CvNwMzQt.js';
-import { M as MakeWorkerAgent, A as AnalystRegistry, W as WorkerWatchOptions, o as CoordinationTools, n as CoordinationEvent, at as QuestionPolicy, E as ExecutorConfig } from './coordination-BZZSVYpZ.js';
-export { bi as BusEvent, bj as BusRecord, bk as BusStats, bl as DEFAULT_SANDBOX_STEERING_MAX_TURNS, bm as EventBus, bn as Inbox, bo as InboxMessage, bp as PI_RUNTIME, bq as PiSeam, br as ProviderSeam, bs as PublishOptions, bt as SandboxSteeringOptions, bu as SteerableSandboxSession, bv as WatchTraceOptions, bw as cliWorktreeExecutor, bx as createEventBus, by as createExecutor, bz as createExecutorRegistry, bA as createInbox, bB as createSteerableSandboxSession, bC as defaultToolDetectors, bD as piExecutor, bE as piSeamKey, bF as watchTrace } from './coordination-BZZSVYpZ.js';
-import { R as RuntimeHooks, I as Iteration, a as SandboxClient, D as Driver, A as AgentRunSpec, O as OutputAdapter, V as Validator, E as ExecCtx, u as LoopWinner, v as LoopLineageOptions, w as LoopResult, L as LoopTokenUsage, M as MountRecorder } from './types-BCoemcXU.js';
-export { x as LoopDecisionPayload, y as LoopEndedPayload, z as LoopIterationDispatchPayload, B as LoopIterationEndedPayload, C as LoopIterationStartedPayload, F as LoopPlanDescription, G as LoopPlanPayload, b as LoopSandboxPlacement, H as LoopStartedPayload, J as LoopTeardownFailedPayload, t as LoopTraceEmitter, c as LoopTraceEvent, K as MountManifestEntry, N as RunProvenance, S as SelectionReceipt, P as ValidationCtx } from './types-BCoemcXU.js';
-import { RunProfileMatrixResult, Scenario, ProfileDispatchFn, JudgeConfig, RunProfileMatrixOptions, DispatchFn } from '@tangle-network/agent-eval/campaign';
-export { AgentEnvironmentProviderRef, AgentEnvironmentProviderRegistry, CreateTangleSandboxExactProcessProviderOptions, ProviderAsSandboxClientOptions, ProviderExecutorOptions, SandboxClientProviderOptions, createAgentEnvironmentProviderRegistry, createTangleSandboxExactProcessProvider, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider } from './environment-provider.js';
-import { c as CorpusRecord, C as Corpus, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, O as Outcome, 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 } from './worktree-fanout-DxhAWr5Z.js';
-export { A as AuthoredHarness, t as DefinePersona, u as EqualKOnCost, v as Fanout, w as FanoutSynthesis, x as FlatWidenGate, y as LoopUntil, z as LoopUntilState, B as Panel, G as PanelJudge, H as PanelVerdict, I as PatchDeliverableOptions, J as PersonaContext, K as PersonaExecutors, M as Pipeline, N as RenderCorpusToInstructions, Q as RunPersonified, U as ShapeBudget, X as ShapeContext, Y as TrajectoryNode, Z as TrajectoryReportFn, _ as Verify, $ as Widen, a0 as WidenDecision, a1 as WidenLineage, a2 as WorktreeCliExecutorOptions, a as WorktreeFanoutOptions, b as WorktreePatchArtifact, a3 as createWorktreeCliExecutor, a4 as patchDelivered, a5 as worktreeFanout } from './worktree-fanout-DxhAWr5Z.js';
-import { AgentProfileMcpServer, AgentProfile as AgentProfile$1, AgentProfileSecurityPolicy } from '@tangle-network/agent-interface';
-import { A as AgenticSurface, a as AgenticTask, b as AgenticOptions, c as Strategy, d as ArtifactHandle, e as SurfaceScore, f as AgenticTool } from './structural-rollout-DEh6CEsa.js';
-export { g as AgenticRunResult, C as CheckExecChannel, h as CheckOutcome, i as CheckRunContext, j as CheckRunner, k as CheckSource, l as CheckSourceCtx, m as CorpusReadbackOptions, R as RepairStop, n as RunAgenticOptions, o as ShotPersona, p as ShotSpec, q as StrategyCtx, r as StrategyResult, s as StructuralRolloutConfig, S as StructuralRolloutPolicy, t as StructuralRolloutResult, V as VisibleCheck, u as adaptiveRefine, v as breadthStrategy, w as canDisplace, x as compareCheckOutcomes, y as composeCheckSources, z as defaultExtractCandidate, B as defaultStructuralRolloutPolicy, D as defineStrategy, E as depthStrategy, F as filterAuthoredAsserts, G as modelAuthoredChecks, H as officialChecksFromMeta, I as refine, J as resolveEntrySymbol, K as runAgentic, L as sample, M as sampleThenRefine, N as sandboxCheckRunner, O as selectBestIndex, P as structuralRollout, Q as visibleCheckScore } from './structural-rollout-DEh6CEsa.js';
-import { b as AnalystRegistryLike } from './types-CmYCMbFT.js';
-import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-DEbPNtyI.js';
-export { j as RouterChatResult, k as RouterChatToolsResult, l as RouterToolCall, m as RouterToolLoopResult, n as ToolLoopCompaction, b as ToolSpec, r as routerBrain, o as routerChatWithTools, p as routerChatWithUsage, q as routerToolLoop } from './sanitize-DEbPNtyI.js';
-import { R as RuntimeStreamEvent, c as AgentExecutionBackend, f as AgentTaskStatus, B as BackendErrorDetail } from './types-BwoZWq-i.js';
-import { D as DeliverableSpec } from './completion-gate-BMy5LGoP.js';
-export { g as WorktreeCommandResult, h as WorktreeProfileMaterializationReceipt, i as gateOnDeliverable } from './completion-gate-BMy5LGoP.js';
-import { S as StopRule, a as SupervisorProfile } from './supervise-4_48wwvy.js';
-export { A as AllWorkersStalledOptions, D as DriveHarness, N as NoProgressForOptions, P as PlateauOptions, b as ProgressSample, c as ProgressTracker, d as ProgressTrackerOptions, e as ProgressView, f as StopDecision, g as SuperviseOptions, h as SupervisorAgentDeps, i as allOf, j as allWorkersStalled, k as anyOf, l as createProgressTracker, n as noProgressFor, p as plateau, s as sampleFromSettled, m as supervise, o as supervisorAgent, w as workerFromBackend } from './supervise-4_48wwvy.js';
-import { stuckLoopView, toolWasteView } from '@tangle-network/agent-eval/pipelines';
-export { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from '@tangle-network/agent-interface/environment-provider';
-import './substrate-Dyiqmd3o.js';
-import './local-harness-BDNcl6jI.js';
-import 'node:child_process';
-import '@tangle-network/agent-profile-materialize';
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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>;
-}
-/**
- * FS `ResultBlobStore`. One JSON file per artifact under `dir`, named by a
- * filesystem-safe encoding of the `outRef` (`sha256:<hex>` → `sha256-<hex>.json`).
- * `put` fsyncs so a crash between writes never loses an acknowledged blob.
- */
-declare class FileResultBlobStore implements ResultBlobStore {
-    private readonly dir;
-    constructor(dir: string);
-    put(outRef: string, artifact: unknown): Promise<void>;
-    get(outRef: string): Promise<unknown | undefined>;
-    private blobPath;
-}
-/**
- * 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>;
-}
-/**
- * JSONL on disk. One line per record: the first record is `begin`, subsequent records
- * are `event` envelopes wrapping a `SpawnEvent`. `loadTree` replays the whole file,
- * filtering by `root`, and applies the same begin-precedes-events + unique-seq
- * corruption guards as the in-memory impl. Each append fsyncs so a crash between
- * writes never loses an acknowledged event.
- */
-declare class FileSpawnJournal implements SpawnJournal {
-    private readonly path;
-    constructor(path: string);
-    loadTree(root: NodeId): Promise<SpawnEvent[] | undefined>;
-    beginTree(root: NodeId, at: string): Promise<void>;
-    appendEvent(root: NodeId, ev: SpawnEvent): Promise<void>;
-    private loadTreeBegin;
-    private appendRecord;
-}
-/**
- * Re-feed a journaled spawn tree in strict `seq` order, rehydrating each settled
- * child's `out` from the blob store by `outRef`, and return the `Settled[]` exactly
- * as `scope.next()` originally delivered them.
- *
- * Determinism (B2): the events are sorted by `seq` BEFORE any blob `get`, so the
- * replay order is the recorded cursor order regardless of how fast each rehydration
- * resolves. `at` (wall-clock) is never a replay input. Fail loud on a tree that was
- * never begun, a settled-done event missing its `outRef`, or a blob the store can't
- * rehydrate — a silent gap would let `act` branch on the wrong evidence.
- */
-declare function replaySpawnTree(journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId): Promise<Settled<unknown>[]>;
-/**
- * Materialize a recorded `TreeView` from a journaled event list for inspection. Folds
- * `spawned`/`settled`/`cancelled` into a per-node snapshot in `seq` order, then adds each
- * `metered` event's driver-inference spend onto its node in a separate additive pass so the view
- * matches the recorded cursor. It does not recover live executors or driver state after restart.
- */
-declare function materializeTreeView(events: SpawnEvent[]): TreeView;
-/**
- * The waits a journaled tree shows as ARMED but never woken — what a resumed run re-arms with the
- * ORIGINAL absolute deadline. Reading it from the journal (rather than from any live state) is
- * what makes "SIGKILL a waiting tree, a new process keeps waiting to the same instant" true.
- */
-declare function pendingWaits(events: SpawnEvent[]): PendingWait[];
-
-/**
- * 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;
-}
-/** Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. */
-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[];
-}
-/**
- * The best-so-far fold — the ONE definition of "how good was the run after k results", shared by
- * the post-run anytime report below and by the LIVE progress-based stop rules
- * (`supervise/stop-rules.ts`). Given the observed objective per settled result in order, it returns
- * the running maximum. A result with no objective (`undefined` — it failed, or it was never
- * scored) carries the previous best forward rather than resetting it.
- *
- * It is extracted rather than duplicated on purpose: a stop rule that decides a run has plateaued
- * must agree, number for number, with the report that later says whether stopping was right.
- */
-declare function bestSoFar(values: ReadonlyArray<number | undefined>): number[];
-/** Mean of a best-so-far curve — the anytime AUC when the curve is normalized to [0,1]. Higher =
- *  the run climbed earlier. Shared with the stop rules so "improving" means one thing. */
-declare function areaUnderCurve(curve: ReadonlyArray<number>): number;
-/**
- * How many trailing entries of a best-so-far curve are within `minDelta` of the curve's value
- * `window` steps back — i.e. the length of the current PLATEAU, in settles. `0` means the most
- * recent settle improved the best by more than `minDelta`.
- *
- * The plateau math the live stop rules read. Defined here, beside the report that measures whether
- * the plateau was real, so there is exactly one notion of "not improving".
- */
-declare function plateauLength(curve: ReadonlyArray<number>, minDelta: number): number;
-/** 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;
-}
-/** Default system instruction for intent-auditor agents: diagnose diverged/drifting trajectories. */
-declare const defaultAuditorInstruction: string;
-/** The route-rigor analyst: compare declared vs revealed vs user intent over a trajectory and return aligned / drifting / diverged with evidence and one recommended intervention. */
-declare function auditIntent(input: AuditIntentInput, opts: AuditIntentOptions): Promise<IntentAudit>;
-
-/**
- * benchmark-report — turn a fleet of `RunRecord`s into a publishable, multi-axis benchmark report:
- * a ranked leaderboard, the full profile×axis score matrix, the cost/latency/token columns, and
- * embeddable charts (SVG) + a self-contained HTML page. Domain-agnostic by construction — it reads ONLY
- * the universal `RunRecord` currency (model, scenario, score, cost, tokens, latency, the `outcome.raw`
- * metric bag), so the SAME engine reports any benchmark in any domain: coding, search, agents, multimodal.
- *
- * This is the surface a hosted leaderboard (à la vals.ai) renders: for every harness×model profile, its
- * score on every axis, not a curated subset. It pairs with `runProfileMatrix` (whose `result.records`
- * feed straight in) but takes the records directly, so it is independent of how they were produced.
- *
- * An AXIS is any way to slice the score into columns — by default one column per scenario group
- * (`groupOf`, default = the scenario id), so the matrix is profile × scenario. Pass `axisScoresOf` to
- * score along judge dimensions or any custom decomposition instead. The reporter never invents a number:
- * a missing cell renders blank, never zero.
- */
-
-/** Pull the headline score in [0,1] from a record. Default: the held-out split, else the search split,
- *  else a `composite`/`passed`/`score` entry in the raw bag. Override to score a domain differently. */
-type ScoreOf = (record: RunRecord) => number | undefined;
-/** The profile (matrix row) a record belongs to — default `harness·model` from the record's profile cell,
- *  falling back to the model. This is the leaderboard's unit of comparison. */
-type ProfileKeyOf = (record: RunRecord) => string;
-/** The axis (matrix column) a record contributes to — default the scenario group. */
-type GroupOf = (record: RunRecord) => string;
-/** Decompose ONE record into per-axis scores (e.g. judge dimensions). When set, it REPLACES the
- *  scenario-group axes: the column set is the union of returned keys. */
-type AxisScoresOf = (record: RunRecord) => Record<string, number>;
-interface LeaderboardOptions {
-    readonly title?: string;
-    readonly scoreOf?: ScoreOf;
-    readonly profileKeyOf?: ProfileKeyOf;
-    readonly groupOf?: GroupOf;
-    readonly axisScoresOf?: AxisScoresOf;
-    /** Display label for a profile key (default: the key itself). */
-    readonly labelOf?: (profileKey: string) => string;
-    /** Commit SHA / dataset / dates surfaced in the provenance block. */
-    readonly meta?: Record<string, string>;
-    /** Compute per-row confidence intervals (bootstrap on score, Wilson on pass rate). Needs a
-     *  `scenarioId` on every record (reps are collapsed per scenario for the honest n). Default off. */
-    readonly stats?: boolean;
-    /** A score ≥ this counts as a "pass" for the pass-rate proportion + its Wilson CI. Default 0.999
-     *  (fully solved). Lower it (e.g. 0.6) for a partial-credit domain. */
-    readonly passThreshold?: number;
-}
-/** A 95%-by-default confidence interval. */
-interface Interval {
-    readonly lower: number;
-    readonly upper: number;
-}
-/** One leaderboard row — a harness×model profile, every measured column. */
-interface LeaderboardRow {
-    readonly profileKey: string;
-    readonly label: string;
-    readonly model: string;
-    readonly n: number;
-    readonly meanScore: number;
-    /** Fraction of records scoring ≥ `passThreshold` (default 0.999) — the binary pass rate. */
-    readonly solveRate: number;
-    /** axis → mean score for this profile (blank in render when the profile never ran that axis). */
-    readonly perAxis: Record<string, number>;
-    readonly costUsd: number;
-    readonly tokensIn: number;
-    readonly tokensOut: number;
-    readonly latencyP50Ms: number;
-    readonly latencyP90Ms: number;
-    /** Bootstrap CI on the mean score — present only when `opts.stats` is set. Computed over
-     *  per-scenario means (reps collapsed first), so identical reps can't fake a narrow interval. */
-    readonly scoreCi?: Interval;
-    /** Wilson CI on the pass rate — present only when `opts.stats` is set. */
-    readonly passCi?: Interval;
-}
-interface Leaderboard {
-    readonly title: string;
-    /** Column order — scenario groups (default) or dimension keys (`axisScoresOf`). */
-    readonly axes: readonly string[];
-    /** Rows ranked by `meanScore` desc (ties → lower cost, then label). */
-    readonly profiles: readonly LeaderboardRow[];
-    readonly meta: Record<string, string>;
-    /** Provenance counts — the denominators every honest report leads with. */
-    readonly provenance: {
-        readonly records: number;
-        readonly profiles: number;
-        readonly axes: number;
-        readonly models: readonly string[];
-        readonly totalCostUsd: number;
-    };
-}
-/** Aggregate a fleet of records into the ranked, multi-axis report. Pure — no IO, deterministic. */
-declare function leaderboard(records: readonly RunRecord[], opts?: LeaderboardOptions): Leaderboard;
-/** One profile pair compared on the scenarios they BOTH ran — the "who actually beat whom" verdict. */
-interface PairwiseVerdict {
-    readonly a: string;
-    readonly b: string;
-    /** Paired unit count (shared scenarios). The significance is suppressed below `minPairs`. */
-    readonly pairs: number;
-    /** Median paired delta (b − a) and its bootstrap CI. */
-    readonly delta: number;
-    readonly ciLow: number;
-    readonly ciHigh: number;
-    /** Paired-test p-value (before correction). */
-    readonly p: number;
-    /** BH-significant across ALL pairs AND above the `minPairs` power floor. */
-    readonly significant: boolean;
-}
-interface PairwiseOptions {
-    readonly scoreOf?: ScoreOf;
-    readonly profileKeyOf?: ProfileKeyOf;
-    readonly labelOf?: (profileKey: string) => string;
-    /** False-discovery rate for the Benjamini–Hochberg correction. Default 0.05. */
-    readonly fdr?: number;
-    /** Below this many shared scenarios a paired test can't defensibly separate two profiles, so the
-     *  `significant` tag is suppressed regardless of p (small-n mirage protection). Default 12. */
-    readonly minPairs?: number;
-}
-/** Compare EVERY profile pair on the scenarios they both ran — paired-bootstrap effect + CI, a real
- *  paired-test p-value, BH-corrected across all pairs. This is the honest "did A beat B" table the
- *  leaderboard's point ranking cannot answer. Reuses the agent-eval statistics substrate. */
-declare function pairwiseSignificance(records: readonly RunRecord[], opts?: PairwiseOptions): PairwiseVerdict[];
-/** Render the report as a publishable Markdown document: provenance → leaderboard → the full profile×axis
- *  matrix → cost/latency/token columns. Every axis is shown — a curated subset is a reporting failure. */
-declare function renderLeaderboardMarkdown(report: Leaderboard): string;
-/** Render the pairwise-significance table — every profile pair's paired delta, CI, and BH-corrected
- *  verdict. Feed it `pairwiseSignificance(records)`. This is the "did A really beat B" evidence the point
- *  ranking cannot give. */
-declare function renderPairwiseMarkdown(verdicts: readonly PairwiseVerdict[], title?: string): string;
-/** Render a self-contained SVG: a ranked score bar chart on top, the profile×axis heatmap below. No deps,
- *  embeddable anywhere (README, HTML page, hosted leaderboard). */
-declare function renderLeaderboardSvg(report: Leaderboard): string;
-/** Render a self-contained HTML leaderboard page (the hosted surface): the SVG charts + the full Markdown
- *  matrix as a table. Single file, no assets, opens in any browser. */
-declare function renderLeaderboardHtml(report: Leaderboard): string;
-
-/**
- *
- * 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).
- *
- * @experimental
- */
-
-/** 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;
-}
-/** Decide whether a `CompletionVerdict` may end the node under the policy: authority scales with the verdict's determinism, and probabilistic verdicts must clear `minConfidence`. */
-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>;
-
-/** Structured per-case verdict a `score` function may return (a bare number is
- *  shorthand for `{ composite }`). `composite` is the [0,1] leaderboard score;
- *  `dimensions` are recorded as extra judge dimensions. */
-interface LeaderboardScore {
-    composite: number;
-    dimensions?: Record<string, number>;
-    notes?: string;
-}
-/** The campaign scenario a case is wrapped into: the case rides along so
- *  judges and hooks can reach the full domain payload, not just its id. */
-interface LeaderboardScenario<TCase> extends Scenario {
-    case: TCase;
-}
-/** One extra CLI flag a spec declares. Parsed by `run()` as `--<name> <value>`
- *  and surfaced to every hook via `ctx.args`. */
-interface LeaderboardFlagSpec {
-    default?: string;
-    description: string;
-}
-/** Resolved run configuration handed to `setup` / `teardown` / `export`. */
-interface LeaderboardRunContext {
-    name: string;
-    /** Execution backend name (`--backend`), a key of `backends`. */
-    backend: string;
-    runDir: string;
-    exportDir: string;
-    /** Every parsed flag (standard + `spec.flags`), by name without `--`. */
-    args: Record<string, string | undefined>;
-    harnesses: readonly HarnessType[];
-    /** Snapshot-stamped model ids (`name@snapshot`) — the eval identity models. */
-    models: readonly string[];
-    caseIds: readonly string[];
-    shots: number;
-    reps: number;
-}
-/** Structurally `BenchTask` (bench registry shape) — declared locally so this
- *  module adds no dependency on a benchmark package. */
-interface LeaderboardBenchTask {
-    id: string;
-    prompt: string;
-    split?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Structurally `BenchScore` (bench registry shape). */
-interface LeaderboardBenchScore {
-    resolved: boolean;
-    score: number;
-    detail?: string;
-}
-/** Structurally `BenchmarkAdapter` (bench registry shape): `name`,
- *  `preflight()`, `loadTasks()`, deterministic `judge()`, `goldArtifact()`.
- *  Generic over the artifact channel; the `string` default IS the registry
- *  shape, so a default-artifact adapter registers unchanged. */
-interface LeaderboardBenchmarkAdapter<TArtifact = string> {
-    readonly name: string;
-    preflight(): Promise<void>;
-    loadTasks(opts?: {
-        limit?: number;
-        split?: string;
-        ids?: string[];
-    }): Promise<LeaderboardBenchTask[]>;
-    judge(task: LeaderboardBenchTask, artifact: TArtifact): Promise<LeaderboardBenchScore>;
-    goldArtifact(task: LeaderboardBenchTask): Promise<string | undefined>;
-}
-/** Per-shot outcome context passed as `onCellEvents`'s third argument — how a
- *  thrown shot (which never reaches `parseOutput`) stays visible through the
- *  facade instead of surfacing only as an empty zero-token cell. */
-interface LeaderboardIterationInfo {
-    /** 0-based shot index within the cell. */
-    index: number;
-    /** The shot's thrown error message, when the shot failed before scoring. */
-    error?: string;
-    /** The shot's validator verdict, when the shot reached scoring. */
-    verdict?: {
-        score?: number;
-    };
-}
-/**
- * The declarative leaderboard spec. `TArtifact` is the artifact channel the
- * dispatch produces and the judges score — `string` (the default) is the plain
- * agent-response-text path; a structured artifact type flows natively once the
- * spec supplies `parseOutput` (or a LEVEL-2 `dispatch`) producing it.
- */
-interface LeaderboardSpec<TCase, TArtifact = string> {
-    /** Leaderboard name — the scenario `kind`, default profile name, and report title. */
-    name: string;
-    /** The case corpus. Every case needs a stable string id (see `caseId`). */
-    cases: TCase[];
-    /** Stable id extractor. Default: the case's own `id` property (fail-loud
-     *  when absent or not a string). */
-    caseId?: (c: TCase) => string;
-    /** The per-case task prompt. May be async (e.g. built by shelling out to a
-     *  reference implementation); resolved ONCE per case before dispatch. */
-    prompt: (c: TCase) => string | Promise<string>;
-    /** The domain grader: agent output artifact → score. Used BOTH as the
-     *  per-shot validator (a shot with `composite > 0` stops the naive retry
-     *  loop) and, wrapped as a campaign judge, as the recorded leaderboard score. */
-    score: (output: TArtifact, c: TCase) => number | LeaderboardScore;
-    /** Harness × model axes for `expandProfileAxes`. Defaults: the canonical
-     *  `CODING_HARNESSES` × the base profile's `model.default`. `--harnesses` /
-     *  `--models` override per run. */
-    axis?: {
-        harnesses?: readonly HarnessType[];
-        models?: readonly string[];
-    };
-    /** Base profile the axes expand over (prompt/tools/skills held fixed).
-     *  Default: a minimal `{ name, model: { default: <first model> } }`. */
-    baseProfile?: AgentProfile;
-    /**
-     * Execution-backend registry: `--backend <name>` picks the factory that
-     * yields the `SandboxClient` every cell runs on. Merged over the defaults:
-     *   - `sandbox` — throws with guidance (a product must supply its real
-     *     Sandbox-backed client; the facade has no credentials).
-     *   - `cli-bridge` — `resolveSandboxClient({ backend: 'bridge' })` reading
-     *     `CLI_BRIDGE_URL` + `BRIDGE_BEARER`/`CLI_BRIDGE_BEARER`; the per-cell
-     *     harness/model ride in via `sandboxOverrides.backend`.
-     */
-    backends?: Record<string, (() => SandboxClient) | undefined>;
-    /** Extra `--flag value` CLI args `run()` parses and surfaces via `ctx.args`. */
-    flags?: Record<string, LeaderboardFlagSpec>;
-    /** Extra fields merged into each cell's `backend.model` create override —
-     *  e.g. `{ provider: 'openai-compat', apiKey, baseUrl }` for a router-backed
-     *  sandbox. The cell's bare model id is set by the facade from the axis. */
-    modelBackend?: Record<string, unknown>;
-    /** Runs once before the matrix (fetch fixtures, warm caches). */
-    setup?: (ctx: LeaderboardRunContext) => Promise<void> | void;
-    /** Runs once after the matrix, even on failure (reap boxes, close handles). */
-    teardown?: (ctx: LeaderboardRunContext) => Promise<void> | void;
-    /** Per-cell event tap: the raw sandbox events of EVERY shot, with the case —
-     *  the seam for domain metric capture (search counts, citations) without a
-     *  substrate change. Fires once per shot after the cell's loop settles, in
-     *  shot order, including thrown shots (whose events may be partial or empty);
-     *  the third argument carries the shot's index + error/verdict outcome. */
-    onCellEvents?: (events: readonly SandboxEvent[], c: TCase, iteration?: LeaderboardIterationInfo) => void;
-    /** Output decode override: raw events → the scored artifact. Default: the
-     *  sandbox SDK's `collectAgentResponseText` (final answer text; empty string
-     *  when the stream carried none — which then scores 0). The default only
-     *  produces `string`, so a spec with a structured `TArtifact` MUST supply
-     *  this (or a LEVEL-2 `dispatch`). */
-    parseOutput?: (events: readonly SandboxEvent[], c: TCase) => TArtifact;
-    /**
-     * Resolve the model the backend ACTUALLY served off a shot's raw events.
-     * Required for HARNESS_NATIVE_MODEL-snapped cells (a vendor-locked harness ×
-     * an out-of-family model expands to the `default` sentinel): the RunRecord
-     * must pin a real snapshot-bearing model id, which only the dispatch —
-     * reading the backend's usage/terminal events — can know. When this returns
-     * a value the default dispatch records it on the paid-call receipt;
-     * in-family cells (concrete declared model) never need it.
-     */
-    resolveModel?: (events: readonly SandboxEvent[]) => string | undefined;
-    /** Result export. Default: write `matrix-result.json` under the run dir and
-     *  print (+ write) the ranked leaderboard markdown under the export dir. */
-    export?: (result: RunProfileMatrixResult<TArtifact, LeaderboardScenario<TCase>>, ctx: LeaderboardRunContext) => Promise<void> | void;
-    /** LEVEL 2 — full dispatch replacement (in-process products bring their own).
-     *  The default is `loopDispatch` + `naiveDriver` over the resolved backend. */
-    dispatch?: ProfileDispatchFn<LeaderboardScenario<TCase>, TArtifact>;
-    /** LEVEL 2 — full judge replacement. Default: `score` wrapped as one judge. */
-    judges?: JudgeConfig<TArtifact, LeaderboardScenario<TCase>>[];
-    /** Naive-retry shot cap per cell (`--shots`). Default 1. */
-    shots?: number;
-    /** Replicates per cell (`--reps`). Default 1. */
-    reps?: number;
-    /** Provider- or executor-enforced maximum for one cell dispatch. Required
-     * before execution when `matrix.costCeiling` is configured. */
-    maximumCharge?: MaximumCharge | ((profile: AgentProfile, scenario: LeaderboardScenario<TCase>) => MaximumCharge | undefined);
-    /** Passthrough overrides spread onto the final `runProfileMatrix` call
-     *  (e.g. `maxConcurrency`, `costCeiling`, `integrity`, `storage`) — spread
-     *  LAST, so anything the facade wired can be overridden. */
-    matrix?: Partial<RunProfileMatrixOptions<LeaderboardScenario<TCase>, TArtifact>>;
-}
-interface DefinedLeaderboard<TCase, TArtifact = string> {
-    /**
-     * Parse flags, run the matrix, export, and return the raw result.
-     *
-     * Standard flags: `--backend <name>` (default `sandbox`), `--harnesses a,b`,
-     * `--models m1,m2`, `--cases id1,id2`, `--shots N`, `--reps N`,
-     * `--model-snapshot <tag>`, `--run-dir <path>`, `--export-dir <path>`,
-     * plus every `spec.flags` entry. `argv` defaults to `process.argv.slice(2)`.
-     *
-     * The default run dir is FRESH per invocation (timestamp+pid under the OS
-     * tmpdir). `runProfileMatrix` caches cells by run dir, and a stable default
-     * would silently reuse a prior FAILED zero-token cell and skip dispatch —
-     * only an explicit `--run-dir` opts into that resume behavior.
-     */
-    run(argv?: string[]): Promise<RunProfileMatrixResult<TArtifact, LeaderboardScenario<TCase>>>;
-    /** The same domain surface in the structural `BenchmarkAdapter` shape. */
-    toBenchmarkAdapter(): LeaderboardBenchmarkAdapter<TArtifact>;
-}
-/**
- * Assemble a declarative spec (`cases` + `prompt` + `score`) into a runnable
- * harness×model leaderboard — `run()` executes the matrix, `toBenchmarkAdapter()`
- * exposes the same domain as a structural `BenchmarkAdapter`.
- */
-declare function defineLeaderboard<TCase, TArtifact = string>(spec: LeaderboardSpec<TCase, TArtifact>): DefinedLeaderboard<TCase, TArtifact>;
-
-/**
- * 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;
-}
-/** The third-person trace analyst: read a worker's trace and produce steer findings for the next attempt plus durable `learned` facts for the cross-run corpus. */
-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[];
-}
-/** Batch the firewalled `observe()` analyst over completed runs and accrete the trace-derived facts into the durable corpus — the production-traces→corpus write side of the flywheel. */
-declare function harvestCorpus(opts: HarvestCorpusOptions): Promise<HarvestReport>;
-
-/** Context handed to each `onPrompt` / `onTask` call. */
-interface InProcessPromptCtx {
-    /** 0-based round index — increments per `streamPrompt`/`streamTask` on the
-     *  SAME box (so a refine driver's round N can differ from round N-1). Fresh
-     *  boxes start at 0. */
-    round: number;
-    /** Absolute path of this box's workspace, when a `workdir` was configured.
-     *  Write the deliverable / fixtures here; `fs.read`/`fs.write`/`exec` operate
-     *  over it. `undefined` for pure event-only boxes. */
-    workdir?: string;
-    /** Cooperative cancellation channel for this turn. */
-    signal: AbortSignal;
-    /** Which box verb produced this call: `prompt` = `streamPrompt`,
-     *  `task` = `streamTask`. */
-    mode: 'prompt' | 'task';
-    /** The verbatim per-call options the caller passed to the box verb (minus
-     *  `signal`, surfaced above) — lets an offline test assert an options
-     *  passthrough (`model`, `sessionId`, `maxTurns`, …) actually arrived. */
-    options?: Record<string, unknown>;
-}
-/**
- * The user callback: given a prompt and its round, produce the box's event
- * stream for that turn. Return a plain `SandboxEvent[]` (the common case) or an
- * async iterable for streaming. The callback may also write files into
- * `ctx.workdir` (read back via `fs.read` or graded by `exec`).
- */
-type InProcessOnPrompt = (prompt: string, ctx: InProcessPromptCtx) => SandboxEvent[] | AsyncIterable<SandboxEvent> | Promise<SandboxEvent[]>;
-/** @experimental */
-interface InProcessSandboxClientOptions {
-    /** The per-turn behavior — see {@link InProcessOnPrompt}. */
-    onPrompt: InProcessOnPrompt;
-    /**
-     * Task-mode behavior, driven by `box.streamTask` (the verb `streamAgentTurn`'s
-     * `box-task` backend calls). When omitted, `streamTask` drives `onPrompt` —
-     * the pseudo-box has ONE behavior callback and both verbs exercise it
-     * (`ctx.mode` tells them apart). Provide `onTask` when a test must
-     * discriminate the verbs or script different task-mode behavior.
-     */
-    onTask?: InProcessOnPrompt;
-    /**
-     * Opt in to a REAL filesystem-backed box. When set, each `create()` mints a
-     * fresh temp directory (prefixed `<workdir>-`) and the box exposes
-     * `fs.read`/`fs.write` and `exec` over it; `delete()` removes the dir. Omit
-     * for a pure event-only box (no `fs`/`exec` members), which is all a driver
-     * or fanout loop needs.
-     */
-    workdir?: string;
-    /**
-     * Override the box `id`. A string is used verbatim; a function receives the
-     * 0-based create-sequence and returns the id (e.g. machine-keyed placement
-     * demos). Default `in-process-<seq>`. The id is the value `describePlacement`
-     * tags, so set it when a demo's output reads on a meaningful sandbox id.
-     */
-    id?: string | ((seq: number) => string);
-}
-/**
- * Adapt a single `onPrompt(prompt, ctx)` callback into a `SandboxClient` for
- * `runAgentRounds` / `openSandboxRun`. Returns a PROPERLY-TYPED `SandboxClient`: the
- * lone `SandboxInstance` cast (object literal → `declare class`) lives inside
- * this function, so call sites stay cast-free.
- *
- * @experimental
- */
-declare function inProcessSandboxClient(options: InProcessSandboxClientOptions): SandboxClient;
-
-/**
- * Adapt an `ExecutorFactory` into a `SandboxClient` for `runAgentRounds`. 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;
-
-/**
- * `KeyProvider` — API-key provisioning for adopted external MCP servers.
- *
- * An adopted server (a `connection` artifact, or a `buildableGenerator` remote
- * emit) usually needs a credential. The credential must never ride the profile
- * or the artifact — both are logged, diffed, and stored as audit records — so
- * the profile carries only a DECLARATIVE reference:
- *
- *   `profile.mcp[key].metadata[mcpSecretEnvMetadataKey]`
- *     = { ENV_VAR_NAME: 'PROVIDER_KEY_NAME', … }
- *
- * and the VALUE is resolved at materialize time (`materializeLocalMcp`'s
- * `keys` option) and injected straight into the spawned server child's env.
- * Values exist only in the child process env — never in the profile, the
- * artifact registry, an error message, or a log line (errors name the KEY
- * NAME only).
- *
- * Fail-closed at every hop: a declared secret with no provider, or a provider
- * that does not hold the named key, THROWS — booting an external server
- * keyless would fail opaquely mid-eval or silently score a broken candidate.
- *
- * `envKeyProvider` is the same-host default: it reads the process env, which
- * the operator loads via dotenvx (the secrets files never touch the repo).
- *
- * >>> REAL SECRET STORES PLUG IN HERE (flagged): the sandbox SDK's
- * `client.secrets` (`SecretsManager.get(name)`) and the platform hub's
- * short-lived capability tokens (`PlatformHubClient.mintToken` →
- * `{ ENV: token }`) both satisfy `KeyProvider` with a one-line adapter; both
- * need a live service, so neither is constructed here.
- */
-
-/** Resolve named secrets. The ONE seam every secret store adapts to. */
-interface KeyProvider {
-    /** The value for `name`, or `undefined` when this provider does not hold it. */
-    get(name: string): Promise<string | undefined>;
-}
-/** The env-backed provider: reads the (dotenvx-loaded) process env. Empty /
- *  whitespace-only values count as absent — fail loud, not with a blank key. */
-declare function envKeyProvider(env?: Record<string, string | undefined>): KeyProvider;
-/** The `AgentProfileMcpServer.metadata` key the declarative secret-env map
- *  rides under: `{ ENV_VAR_NAME: 'PROVIDER_KEY_NAME' }`. Names only — values
- *  are resolved at materialize time and never stored. */
-declare const mcpSecretEnvMetadataKey = "secretEnv";
-/** Read (and validate) a server entry's declared secret-env map, if any.
- *  Malformed metadata throws — a half-declared secret must never half-boot. */
-declare function secretEnvOfMcpServer(server: AgentProfileMcpServer): Record<string, string> | undefined;
-/**
- * Resolve a declared secret-env map into the real env entries for a server
- * spawn. Fail-closed: no provider or a missing key throws, naming the KEY
- * NAME only (the value never appears in any message). `label` names the
- * server for the error (e.g. `profile.mcp['exa']`).
- */
-declare function resolveSecretEnv(secretEnv: Record<string, string>, keys: KeyProvider | undefined, label: string): Promise<Record<string, string>>;
-
-/**
- * `localSandboxClient` — the SAME-HOST pseudo-box: a `SandboxClient` whose
- * `create()` MATERIALIZES the profile's stdio MCP servers as local child
- * processes (`materializeLocalMcp`) and whose `streamPrompt` drives a real
- * tool loop (`runBrainLoop` over the router brain) with those live tools.
- *
- * Despite the interface name, this does NOT isolate processes. It is only for
- * author-controlled profiles whose local MCP commands a caller explicitly
- * trusts; user- or model-authored code belongs in a real sandbox. `delete()`
- * kills the children.
- *
- * A per-create profile may change the prompt surface. Permission to start a
- * local MCP process applies only when its full canonical bytes match the fixed
- * constructor profile; a different generated profile is refused.
- *
- * Event protocol matches `inlineSandboxClient`: one `llm_call` metering event
- * + one terminal `result` event with finalText/tokenUsage/costUsd.
- */
-
-interface LocalSandboxClientOptions {
-    /** The worker brain: router chat-completions with tool-calling. All three required. */
-    router: {
-        baseUrl: string;
-        key: string;
-        model: string;
-    };
-    /** Tool-loop turns per prompt. Default 8. */
-    maxTurns?: number;
-    /** Brain sampling temperature. Default: `routerBrain`'s (0.4). */
-    temperature?: number;
-    /** Fallback profile when `create(options)` carries none on `backend.profile`. */
-    profile?: AgentProfile$1;
-    /** Resolves profile-declared MCP secret names at child-process spawn time. */
-    keys?: KeyProvider;
-    /** Explicit trust decision for the exact `profile` bytes supplied here.
-     * Omit to refuse local processes. A permissive policy never transfers to a
-     * different per-create profile and provides no host isolation. */
-    profileSecurityPolicy?: AgentProfileSecurityPolicy;
-}
-/** A same-host `SandboxClient` adapter with no process isolation. Local MCP is
- * refused unless the caller explicitly supplies a policy that allows it. */
-declare function localSandboxClient(opts: LocalSandboxClientOptions): SandboxClient;
-
-/**
- *
- * `runAgentRounds` — 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
- */
-
-/** @experimental */
-interface RunAgentRoundsOptions<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;
-}
-/**
- * The round-synchronous MULTI-AGENT kernel: each round `driver.plan()` fans N tasks
- * out to N sandboxes (bounded concurrency), parses + validates each output, and folds
- * the round's results through `driver.decide` — fanout → validate → vote/select →
- * refine, repeated until the driver says stop. One call spans many agent sessions.
- *
- * Not to be confused with `runToolLoop` / `streamToolLoop` (package root entry): those
- * run ONE chat turn against ONE model, dispatching the tool calls that turn emits and
- * folding the results back in until the model stops calling tools. No sandboxes, no
- * rounds, no winner selection.
- *
- * @experimental
- */
-declare function runAgentRounds<Task, Output, Decision>(options: RunAgentRoundsOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
-/**
- * Pre-rename name for {@link runAgentRounds}; identical function, kept so existing
- * call sites keep working.
- *
- * @deprecated Use {@link runAgentRounds}. The clearer name says what it is: the
- * multi-agent fanout/vote/refine kernel over sandboxes, NOT the one-turn tool loop
- * (`runToolLoop` / `streamToolLoop`, package root entry). `runLoop` shipped on `/loops`
- * next to `routerToolLoop`, which made the two read as variants of one thing. The alias
- * is removed in the next major.
- */
-declare const runLoop: typeof runAgentRounds;
-/**
- * Pre-rename name for {@link RunAgentRoundsOptions}.
- *
- * @deprecated Use {@link RunAgentRoundsOptions}. Removed in the next major.
- */
-type RunLoopOptions<Task, Output, Decision> = RunAgentRoundsOptions<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 `runAgentRounds` into an agent-eval campaign dispatch.
- *
- * Without this adapter a consumer wiring `runAgentRounds` 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.
- */
-
-/** runAgentRounds options minus the `ctx` (loopDispatch builds the ctx). */
-type LoopOptionsForDispatch<Task, Output, Decision> = Omit<RunAgentRoundsOptions<Task, Output, Decision>, 'ctx'>;
-interface LoopDispatchOptions<Task, Output, Decision, TScenario extends Scenario, TArtifact> {
-    /** Sandbox client used for every cell's `runAgentRounds`. Supplied once. */
-    sandboxClient: SandboxClient;
-    /** Build the per-cell runAgentRounds 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;
-    /** Provider- or executor-enforced maximum for this whole cell dispatch.
-     * Required by agent-eval before execution when the campaign is cost-capped. */
-    maximumCharge?: MaximumCharge | ((scenario: TScenario, profile: AgentProfile) => MaximumCharge | undefined);
-    /** Resolve the model actually served from the completed loop. */
-    resolveCostModel?: (result: LoopResult<Task, Output, Decision>, scenario: TScenario, profile: AgentProfile) => string | undefined;
-}
-/** Options for adapting plain agent-eval campaign scenarios into runtime `runAgentRounds` cells. */
-interface LoopCampaignDispatchOptions<Task, Output, Decision, TScenario extends Scenario, TArtifact> {
-    /** Sandbox client used for every campaign cell's `runAgentRounds`. */
-    sandboxClient: SandboxClient;
-    /** Build the per-cell runAgentRounds options from the campaign scenario. */
-    toLoopOptions: (scenario: TScenario) => LoopOptionsForDispatch<Task, Output, Decision>;
-    /** Map the finished loop to the artifact the campaign judges score. */
-    toArtifact?: (result: LoopResult<Task, Output, Decision>) => TArtifact;
-    /** Forward `loop.*` trace events into the campaign's scoped trace. Default true. */
-    forwardTrace?: boolean;
-    /** Cost-meter source label for the loop's spend. Default `'loop'`. */
-    costSource?: string;
-    /** Provider- or executor-enforced maximum for this whole cell dispatch. */
-    maximumCharge?: MaximumCharge | ((scenario: TScenario) => MaximumCharge | undefined);
-    /** Resolve the model actually served from the completed loop. */
-    resolveCostModel?: (result: LoopResult<Task, Output, Decision>, scenario: TScenario) => string | undefined;
-}
-/**
- * Adapter for plain `runCampaign` scenarios. This is the runtime-side pair for
- * agent-eval fixture scenarios: load fixtures in `agent-eval/campaign`, build
- * the runtime loop here, and keep cost + token + trace reporting automatic.
- */
-declare function loopCampaignDispatch<Task, Output, Decision, TScenario extends Scenario, TArtifact>(opts: LoopCampaignDispatchOptions<Task, Output, Decision, TScenario, TArtifact>): DispatchFn<TScenario, TArtifact>;
-/**
- * Adapter for `runProfileMatrix` (profile is an axis). Returns a
- * `ProfileDispatchFn` that runs `runAgentRounds` 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>;
-
-/**
- * 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;
-}
-/** Benchmark output: per-strategy means plus the full per-task × per-strategy losses table an optimizer mines. */
-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;
-}
-/** Coerce an MCP inputSchema to an OpenAI-tool-valid top-level object schema.
- *  Shared with the same-host stdio client (`materializeLocalMcp`) — one coercion
- *  rule for every MCP tool a worker sees, regardless of transport. */
-declare function sanitizeMcpToolSchema(s: unknown): Record<string, unknown>;
-/** Wrap any MCP server as an `Environment`: `tools/list` becomes `AgenticTool[]` with provider-safe schemas; the domain supplies only the artifact lifecycle hooks. */
-declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-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>;
-
-/**
- *
- * 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).
- *
- * @experimental
- */
-
-/**
- * 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.
- *
- * `opts.width` swaps the single round for `rollingDispatch`: at most `width` items live at once,
- * refilled the instant one settles. Selection, blockers, and the conserved pool are unchanged —
- * the refill behavior lives in the existing combinator rather than in a rival primitive.
- */
-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>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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>>>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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;
-    };
-}
-/** Statistical promotion decision over a holdout benchmark: a seeded paired bootstrap (`heldoutSignificance`) whose CI lower bound must clear `deltaThreshold`. */
-declare function promotionGate(opts: PromotionGateOptions): PromotionVerdict;
-
-/**
- * Bridge a finished `runAgentRounds` 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
- * `runAgentRounds` 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 runAgentRounds({ ...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;
-
-/**
- * The product-facing backend selector: one call picks the execution transport a
- * `runAgentRounds` (or any consumer that drives a `SandboxClient`) runs on, from the
- * package a product already depends on. It is pure sugar over the existing
- * primitives — `createExecutor({ backend })` + `inlineSandboxClient` — and adds
- * ZERO transport code (the node:http cli-bridge transport lives in `bridgeExecutor`).
- *
- * The heavy `resolveBenchClient` in `@tangle-network/agent-bench` is the bench-side
- * sibling: it layers router/search specifics a product should not have to depend on.
- * This is the generic, dep-light core products call to switch backends:
- *
- *   - `backend: 'sandbox'` → IN-BOX: return the caller's real Sandbox-backed
- *                            `sandboxClient` unchanged. Fail loud if absent — a
- *                            product on the sandbox backend already holds its box.
- *   - `backend: 'bridge'`  → OFF-BOX: a local cli-bridge fronting a harness CLI
- *                            (opencode / kimi-code / …) as the leaf executor, wired
- *                            through the resumable `bridgeExecutor`.
- *   - `backend: 'router'`  → OFF-BOX: a router chat-completion as the leaf executor,
- *                            presented as a `SandboxClient` (no sandbox dependency).
- *   - `backend: 'local'`   → SAME-HOST: a router-brain tool loop with the
- *                            profile's stdio MCP servers spawned as LOCAL child
- *                            processes — the only backend that can reach an MCP
- *                            server built into a host worktree.
- */
-
-interface ResolveSandboxClientOptions {
-    /** The execution transport for the driven loop. */
-    backend: 'sandbox' | 'bridge' | 'router' | 'local';
-    /** `sandbox` backend: the caller's real Sandbox-backed client. Required for that backend. */
-    sandboxClient?: SandboxClient;
-    /** `bridge` backend: local cli-bridge transport. `bearer` + `model` required. */
-    bridge?: {
-        /** cli-bridge base URL. Defaults to `http://127.0.0.1:3355`. */
-        url?: string;
-        bearer: string;
-        /** Bridge model id, doubling as the harness selector (e.g. `claude-code/sonnet`). */
-        model: string;
-        /** Per-turn deadline (ms). */
-        timeoutMs?: number;
-    };
-    /** `router` backend: router chat-completion transport. All three fields required. */
-    router?: {
-        baseUrl: string;
-        key: string;
-        model: string;
-    };
-    /** `local` backend: same-host pseudo-box — the router brain drives a tool loop
-     *  with the profile's stdio MCP servers spawned as local children. */
-    local?: LocalSandboxClientOptions;
-}
-/**
- * Resolve a `SandboxClient` for the chosen backend. The generic, dep-light core
- * that `resolveBenchClient` builds on — reuse this instead of hand-rolling the
- * `createExecutor`/`inlineSandboxClient` branch in each product.
- */
-declare function resolveSandboxClient(opts: ResolveSandboxClientOptions): SandboxClient;
-
-/**
- *
- * `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
- */
-
-/** @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>;
-}
-/**
- * Cold-start-resilient sandbox acquisition: create by name, observe readiness from the sandbox's own status (not the create call), and re-attach after gateway timeouts.
- *
- * @experimental
- */
-declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOptions, acquire?: AcquireOptions): Promise<SandboxInstance>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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;
-/**
- * Sum the token usage + USD cost of a sandbox turn's events — the one honest way to meter an
- * `openSandboxRun` cell. Folds `extractLlmCallEvent` over the stream (which reads usage off EVERY backend
- * event shape), so a `runProfileMatrix` dispatch can report it to `ctx.cost`:
- *
- *     receipt: (turn) => {
- *       const u = sumSandboxUsage(turn.events)
- *       return { model, inputTokens: u.input, outputTokens: u.output,
- *         ...(u.costUsd > 0 ? { actualCostUsd: u.costUsd } : {}) }
- *     }
- *
- * Without this a cell reads `{tokens:0, cost:0}` and the backend-integrity guard correctly aborts the
- * matrix as a stub. `agentRunName` is the fallback model label for cost-only events (default `'agent'`).
- */
-declare function sumSandboxUsage(events: readonly SandboxEvent[], agentRunName?: string): {
-    input: number;
-    output: number;
-    costUsd: number;
-};
-/**
- * Cross-event state for {@link mapSandboxToolEvent}. Sandbox backends emit a
- * tool invocation as MANY `message.part.updated` frames on the same call id
- * (pending → running → completed), so faithful projection needs per-call
- * status memory: one `tool_call` on first sighting, at most one `tool_result`
- * on the terminal transition, nothing on intermediate re-frames. Create one
- * state per turn via {@link createSandboxToolPartState}.
- *
- * @experimental
- */
-interface SandboxToolPartState {
-    /** Last seen status per tool call id. A terminal status is sticky — later
-     *  frames on a settled call project to nothing. */
-    statusByCall: Map<string, string>;
-    /** Sequence for synthesized call ids when an event carries none. */
-    seq: number;
-}
-/**
- * Fresh per-turn {@link SandboxToolPartState} for {@link mapSandboxToolEvent} — an
- * empty call-status map so each turn projects tool frames independently.
- *
- * @experimental
- */
-declare function createSandboxToolPartState(): SandboxToolPartState;
-/**
- * Project one `SandboxEvent` onto the `tool_call` / `tool_result` variants of
- * `RuntimeStreamEvent` — the tool-part projection `mapSandboxEvent`
- * deliberately does NOT perform. Opt-in and additive: `mapSandboxEvent`'s
- * default vocabulary (text/reasoning deltas + `llm_call`) is unchanged;
- * consumers that need the tool surface (chat UIs rendering tool activity)
- * compose this projector alongside it — `streamAgentTurn` does exactly that
- * under its `preserveToolParts` option.
- *
- * Handled shapes (observed on the opencode / claude-code sandbox backends):
- *   - `message.part.updated` with `part.type === 'tool'` — stateful: a
- *     `tool_call` on the call id's first frame (args from `state.input` or
- *     `state.metadata.input`), a `tool_result` when the status transitions to
- *     `completed` (result from `state.output` / `metadata.output`) or to a
- *     terminal failure (result is `{ error, status, output? }` — the error
- *     surfaced in-band, never dropped).
- *   - bare `tool*` event types (`tool.call`, `tool_result`, …) — stateless:
- *     `*result*` types project to `tool_result`, the rest to `tool_call`.
- *
- * Returns `[]` for every non-tool event.
- *
- * @experimental
- */
-declare function mapSandboxToolEvent(event: SandboxEvent, state: SandboxToolPartState): (RuntimeStreamEvent & {
-    type: 'tool_call' | 'tool_result';
-})[];
-/**
- * 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)
- *
- * Tool parts are deliberately NOT mapped here (unchanged default) — compose
- * {@link mapSandboxToolEvent} alongside when a consumer needs them.
- *
- * 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;
-
-/**
- *
- * `SandboxLineage` — the backend-blind owner of box + session handles for a
- * single `runAgentRounds` 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.
- *
- * @experimental
- */
-
-/**
- * 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, promptOptions?: Omit<PromptOptions, 'signal' | 'sessionId'>): 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, promptOptions?: Omit<PromptOptions, 'signal' | 'sessionId'>): 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';
-    /** Run provenance recorder forwarded to every `prepareBox` the lineage runs
-     *  (fresh start, continue, and fork branches). Absent ⇒ mounts go unrecorded
-     *  (a no-op recorder stands in so the ctx shape is always satisfied). */
-    recordMount?: MountRecorder;
-}): 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 `runAgentRounds`: `runAgentRounds` 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.
- */
-
-/**
- * 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.
- *
- * @experimental
- */
-type Deliverable<Out> = {
-    kind: 'events';
-    fromEvents: (events: SandboxEvent[]) => Out;
-} | {
-    kind: 'artifact';
-    path: string;
-    fromArtifact: (raw: string, events: SandboxEvent[]) => Out;
-};
-/**
- * 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.
- *
- * @experimental
- */
-interface TurnResult<Out> {
-    out: Out;
-    events: SandboxEvent[];
-    readError?: string;
-}
-/**
- * Thrown when a turn is aborted/timed-out mid-settle. Carries the events drained
- * BEFORE the abort fired (and any in-progress `readError`) so an aborted run is
- * DIAGNOSABLE — the caller can tell never-started (`events: []`) from looped
- * (many events, no terminal `result`) from produced-nothing-then-cancelled.
- *
- * `name === 'AbortError'`, so existing `err.name === 'AbortError'` callers (the
- * loop kernel, scope, supervise runtime) keep matching it unchanged.
- *
- * @experimental
- */
-declare class SandboxRunAbortError extends Error {
-    readonly name = "AbortError";
-    /** Events drained from the stream before the abort interrupted the turn. */
-    readonly events: SandboxEvent[];
-    /** The last artifact read error, if the abort fired during the retry loop. */
-    readonly readError?: string;
-    constructor(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>;
-}
-/** Prompt options forwarded to every sandbox prompt turn in this run. The
- * runtime owns `sessionId` and `signal` so callers cannot accidentally break
- * resume or cancellation semantics while still setting backend-level prompt
- * controls such as `timeoutMs`.
- *
- * @experimental
- */
-type OpenSandboxRunPromptOptions = Omit<PromptOptions, 'signal' | 'sessionId'>;
-/** Context available after the box/session exists and before the first prompt is
- * drained. Intended for benchmark-owned workspace setup such as cloning a repo
- * into a fixed path. */
-interface OpenSandboxRunBeforeStartContext {
-    readonly box: SandboxInstance;
-    readonly sessionId: string;
-    readonly signal: AbortSignal;
-}
-/** @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;
-    /** Per-prompt sandbox SDK options forwarded to both `start()` and `resume()`.
-     *  The runtime still owns the session id and abort signal for each turn. */
-    promptOptions?: OpenSandboxRunPromptOptions;
-    /** Optional pre-start workspace setup. Runs after `lineage.start()` creates the
-     * box/session and before the first prompt stream is consumed. A thrown error
-     * fails the turn before the agent spends tokens. */
-    beforeStart?: (ctx: OpenSandboxRunBeforeStartContext) => Promise<void> | void;
-    /** 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;
-}
-/**
- * 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.
- *
- * @experimental
- */
-declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandboxRunOptions, deliverable: Deliverable<Out>): Promise<SandboxRun<Out>>;
-
-/**
- * Same-host stdio MCP: the ONE persistent newline-delimited JSON-RPC 2.0
- * connection to a spawned MCP server child process. This is the handshake
- * `mcpServeVerifier` boots for its probe (`initialize` →
- * `notifications/initialized` → `tools/list`), extracted so a trusted
- * same-host consumer can keep the server running and route `tools/call` to it.
- * This module does not isolate the child: callers must use a real sandbox for
- * user- or model-authored code.
- *
- * Two layers:
- *   - `connectStdioMcp`     — spawn ONE server at its cwd, run the real MCP
- *     handshake, return a live connection: the listed tools, `callTool`, `close`.
- *   - `materializeLocalMcp` — spawn EVERY enabled stdio server in
- *     `profile.mcp`, namespace each server's tools as `<server>__<tool>` so
- *     they can share a worker's tool list with a domain surface's tools, and
- *     expose one route/close facade over the set. Fail-CLOSED: a declared
- *     server that cannot boot throws — silently scoring the profile as if it
- *     had no MCP surface would fake the with/without ablation.
- *
- * Failure taxonomy (mirrors `commandVerifier`/`mcpServeVerifier`): a missing
- * start binary or spawn fault is a SETUP bug (`McpSpawnFault` — candidate
- * graders must rethrow it, never score it); a server that crashes, errors the
- * handshake, or times out is an ordinary `Error` carrying the stderr tail; a
- * JSON-RPC error on `tools/call` is the AGENT's outcome — returned as an
- * `ERROR: …` string, never thrown (the `createMcpEnvironment` convention).
- *
- * Protocol matches the runtime's own stdio MCP server (src/mcp/server.ts):
- * newline-delimited JSON-RPC 2.0, protocol version 2024-11-05.
- */
-
-interface StdioMcpServerSpec {
-    /** Command that starts the MCP server (stdio transport). */
-    command: string;
-    args?: string[];
-    /** Working directory the server starts in (a built candidate's worktree, typically). */
-    cwd?: string;
-    /** Declared public env for the server process. Only a minimal non-sensitive
-     * subset of the parent env is inherited. */
-    env?: Record<string, string>;
-    /** Sensitive env for the server process. These values override `env` and are
-     * redacted from child-supplied errors, tool metadata, and tool results. */
-    protectedEnv?: Record<string, string>;
-    /** Handshake AND per-request timeout (ms). Default 30s. */
-    timeoutMs?: number;
-}
-/** A missing start binary / spawn fault: a SETUP bug, never a failed candidate.
- *  Graders (the serve verifier) must rethrow this instead of scoring it. */
-declare class McpSpawnFault extends Error {
-}
-interface McpToolDescriptor {
-    name: string;
-    description?: string;
-    inputSchema?: unknown;
-}
-interface StdioMcpConnection {
-    /** The tools the server exposed at connect time (`tools/list`). */
-    readonly tools: readonly McpToolDescriptor[];
-    /** `tools/call` → the result's text content. A JSON-RPC error / `isError`
-     *  result becomes an `ERROR: …` string (the agent's outcome); a dead
-     *  transport or timeout throws (an infra fault). */
-    callTool(name: string, args: Record<string, unknown>): Promise<string>;
-    /** Kill the server child. Idempotent. */
-    close(): Promise<void>;
-}
-/** Spawn a trusted host command, complete the stdio MCP handshake, and return
- * the live connection. This low-level function provides no process isolation. */
-declare function connectStdioMcp(spec: StdioMcpServerSpec): Promise<StdioMcpConnection>;
-interface MaterializeLocalMcpOptions {
-    /** Handshake / per-request timeout per server (ms). Default 30s. */
-    timeoutMs?: number;
-    /** Cap on a tool result's text fed back to the worker. Default 2000 chars. */
-    maxResultChars?: number;
-    /** Resolves a server's DECLARED secrets (`metadata.secretEnv`: env var name →
-     *  provider key name) at spawn time. The resolved values reach ONLY the child
-     *  process env — never the profile, the logs, or an error message. Fail-closed:
-     *  a server declaring secrets without a provider (or with a missing key)
-     *  throws instead of booting keyless. */
-    keys?: KeyProvider;
-    /** Required trust decision for profiles that declare local MCP processes.
-     * Omit to refuse all profile-controlled host execution. Passing
-     * `allowLocalMcp: true` is only safe for an author-controlled profile: the
-     * process receives this Runtime's filesystem and network privileges. */
-    profileSecurityPolicy?: AgentProfileSecurityPolicy;
-}
-/** The live same-host materialization of a profile's `mcp` surface. */
-interface LocalMcpMaterialization {
-    /** Worker-facing tool specs: namespaced `<server>__<tool>`, provider-safe schemas. */
-    tools: AgenticTool[];
-    /** Whether `name` is one of this materialization's namespaced tools. */
-    owns(name: string): boolean;
-    /** Route a namespaced call to its server's live stdio child. */
-    call(name: string, args: Record<string, unknown>): Promise<string>;
-    /** Kill every spawned server. Idempotent. */
-    close(): Promise<void>;
-}
-/**
- * Spawn every explicitly trusted stdio server in `profile.mcp` as a same-host
- * child and expose its tools under `<server>__<tool>` names. The default policy
- * refuses local processes. A profile with no MCP surface returns zero tools.
- */
-declare function materializeLocalMcp(profile: AgentProfile$1, opts?: MaterializeLocalMcpOptions): Promise<LocalMcpMaterialization>;
-
-/**
- *
- * Leak-free steering drivers — the non-LLM controls for the driven loop.
- *
- * These are the two sibling `Driver`s of the `refine` reference driver
- * (examples/driver-loop/driver-loop.ts), differing ONLY in how much of the
- * prior `verdict` their `plan()` is allowed to read. The amount of the verdict
- * a driver reads IS the experimental axis:
- *
- *   • refine  — reads `verdict.notes` (and/or `verdict.scores`): the grader's
- *               findings. A reviewer/judge LLM turns those findings into the
- *               next prompt. This is the "coached" condition.
- *   • dumb    — reads ONLY `verdict.valid` (the pass/fail boolean). No findings,
- *               no scores, no LLM. The next prompt is one of two fixed strings
- *               keyed on pass/fail. This is the leak-free pass/fail control.
- *   • naive   — reads NOTHING from the verdict. The next prompt is one fixed
- *               continuation string every round. This is the leak-free
- *               no-signal control.
- *
- * The `dumb → refine` gap measured on the same task therefore isolates how much
- * the grader's findings (its notes/scores) inflate the result beyond a bare
- * pass/fail signal: it is exactly the delta between reading `verdict.valid` and
- * reading `verdict.notes`. The `naive → dumb` gap isolates the value of the
- * pass/fail bit alone. Run all three against one task to attribute a loop's
- * lift to its actual source instead of crediting it to the grader for free.
- *
- * GENERALITY CONTRACT
- * -------------------
- * These builders carry ZERO domain coupling:
- *   • The continuation strings are PARAMETERS. The caller passes its own text;
- *     the substrate hardcodes none.
- *   • The Task shape is OPAQUE. The builder never assumes a `prompt` field (or
- *     any field). The caller supplies `applyContinuation(task, text) → Task`,
- *     which folds a steering string into the caller's own Task shape — exactly
- *     symmetric with the caller-supplied `AgentRunSpec.taskToPrompt`. For a Task
- *     that is `{ prompt: string; … }`, the fold is the one-liner
- *     `(task, text) => ({ ...task, prompt: text })`.
- *
- * They consume nothing the loop kernel does not already give `plan()`/`decide()`
- * — `runAgentRounds` requires no change. A benchmark picks a driver by name and the
- * kernel does the rest.
- *
- * @experimental
- */
-
-/**
- * Terminal-or-continue decision shared by all three steering drivers. The
- * non-terminal `'refine'` keeps the loop running another shot; the terminal
- * `'pick-winner'`/`'fail'` stop it (`isTerminalDecision` in run-loop.ts treats
- * `'pick-winner'` and `'fail'` as terminal and any other string as a request
- * for another round). Identical to the reference refine driver's decision set.
- */
-type SteeringDecision = 'refine' | 'pick-winner' | 'fail';
-/**
- * Fold a steering string into the caller's Task shape, producing the Task for
- * the next shot. The substrate never assumes how a Task carries its prompt, so
- * the caller supplies this — the same way it supplies `taskToPrompt`. The
- * original `task` is passed so the fold can preserve task-level fields (ids,
- * fixtures, feature names) and replace only the instruction.
- */
-type ApplyContinuation<Task> = (task: Task, continuation: string) => Task;
-/** Options for {@link naiveDriver}. */
-interface NaiveDriverOptions<Task> {
-    /**
-     * The fixed continuation issued every round after shot 0. The same string is
-     * sent whether the prior shot passed inspection or not — the naive driver
-     * reads no part of the verdict. Domain text is the caller's; the substrate
-     * supplies none.
-     */
-    continuation: string;
-    /** Folds `continuation` into the caller's Task shape for the next shot. */
-    applyContinuation: ApplyContinuation<Task>;
-    /** Hard shot cap. The loop stops refining once history reaches this length. */
-    maxIterations: number;
-    /** Trace-event identifier. Default `'naive'`. */
-    name?: string;
-}
-/**
- * `naiveDriver` — the no-signal steering control.
- *
- * `plan()` runs the initial `task` at shot 0, then issues the SAME fixed
- * `continuation` every subsequent round until a shot is valid or the cap is
- * hit. It reads NOTHING from `history[last].verdict` — not `.valid`, not
- * `.notes`, not `.scores`. It is the floor a coached loop must beat to earn its
- * coaching: any lift over naive that is not also present in `dumb` is
- * attributable to the pass/fail bit, and any lift of `refine` over `dumb` is
- * attributable to the grader's findings.
- */
-declare function naiveDriver<Task, Output>(options: NaiveDriverOptions<Task>): Driver<Task, Output, SteeringDecision>;
-/** Options for {@link dumbDriver}. */
-interface DumbDriverOptions<Task> {
-    /**
-     * Continuation issued when the prior shot's verdict is valid. In a
-     * stop-on-pass loop this is rarely reached (a valid shot ends the loop), but
-     * it is required so the driver is total over the pass/fail bit; pass a
-     * confirmation/keep-going string.
-     */
-    onPass: string;
-    /** Continuation issued when the prior shot's verdict is NOT valid. */
-    onFail: string;
-    /** Folds the chosen continuation into the caller's Task shape. */
-    applyContinuation: ApplyContinuation<Task>;
-    /** Hard shot cap. The loop stops refining once history reaches this length. */
-    maxIterations: number;
-    /** Trace-event identifier. Default `'dumb'`. */
-    name?: string;
-}
-/**
- * `dumbDriver` — the pass/fail-only steering control.
- *
- * `plan()` runs the initial `task` at shot 0, then reads ONLY
- * `history[last].verdict.valid` (the boolean) and issues `onPass` or `onFail`
- * accordingly. It MUST NOT read `.notes` or `.scores` — that boundary is the
- * leak-free firewall. A `verdict` with no `valid` set (or no verdict) is
- * treated as not-valid, so the driver is total and never throws on a
- * grader/transport gap.
- *
- * The `dumb → refine` gap is the headline measurement: refine reads the
- * grader's `notes`, dumb reads only the pass/fail bit, so the difference is
- * exactly the value the findings add over a bare boolean.
- */
-declare function dumbDriver<Task, Output>(options: DumbDriverOptions<Task>): Driver<Task, Output, SteeringDecision>;
-
-/**
- * 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;
-/** Multi-generation strategy search: author candidates from tournament losses, play them against the incumbent at equal budget, promote via `promotionGate` on an untouched holdout slice. */
-declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<EvolutionReport>;
-
-/**
- * `streamAgentTurn` — the ONE run-a-turn event-stream contract over every
- * execution substrate: a sandbox box (`SandboxInstance.streamPrompt`, or
- * `streamTask` via the `box-task` kind for autonomous-task semantics), a
- * one-shot `Executor` (cli-bridge / router / BYO, via `ExecutorFactory`), and
- * an in-process `AgentExecutionBackend` (the `resolveAgentBackend` output).
- *
- * One function, one vocabulary: every backend kind yields the existing
- * `RuntimeStreamEvent` union incrementally and ALWAYS terminates with a
- * `final` event whose `text` is the turn's final text and whose
- * `metadata.tokenUsage` / `metadata.costUsd` / `metadata.model` carry the
- * turn's metered usage. `collectAgentTurn` drains a stream into that terminal
- * summary plus the full event list.
- *
- * This is a UNIFICATION seam, not a new stream parser — each kind is a thin
- * adapter over code that already exists and is already hardened:
- *   - `box`      — `mapSandboxEvent` + `extractLlmCallEvent` (sandbox-events.ts)
- *                  project the sandbox event stream; nothing is re-mapped here.
- *   - `box-task` — the same projection over `box.streamTask` (the sandbox
- *                  SDK's autonomous-task verb: the agent works to completion,
- *                  multi-turn, session state maintained) with per-task
- *                  `TaskOptions` passthrough.
- *   - `executor` — `inlineSandboxClient` (the ONE executor→box adapter) turns
- *                  the factory into a box, then the box path drives it. The
- *                  executor's settle/teardown lifecycle stays in that adapter.
- *   - `chat`     — the backend's own `stream()` surface, normalized by
- *                  `normalizeBackendStreamEvent` (the same projection
- *                  `runAgentTaskStream` applies).
- *
- * Distinct from `openSandboxRun` (box-only, session resume over one persistent
- * artifact, raw `SandboxEvent` deliverables) and from `runAgentTaskStream`
- * (full task lifecycle: knowledge preflight, session store, resume). This is
- * the minimal turn primitive underneath both worlds: prompt in, one normalized
- * event stream out, terminal result+usage guaranteed on every non-thrown path.
- *
- * Stream envelope: `backend_start` → incremental events → (`backend_error` on
- * failure) → `final`. A caller-initiated abort terminates with
- * `final.status: 'aborted'`; an expired `timeoutMs` deadline with
- * `final.status: 'failed'` — so cancellation stays distinguishable from a
- * blown deadline.
- *
- * Mid-stream lifecycle work needs NO extra API: the generator is pull-based,
- * so the producer is suspended between yields and resumes only when the caller
- * pulls again. A consumer can therefore run arbitrary async work between
- * events — sync state on each `tool_result`, decide a no-op retry after
- * draining, run a pre-`done` flush when it receives `final` and BEFORE it
- * forwards its own terminal event downstream. The interleaving is guaranteed
- * (and locked by test): nothing is produced past the event the caller is
- * holding.
- *
- * @experimental
- */
-
-/**
- * The execution substrate one turn runs on — a closed discriminated union over
- * the three stream surfaces the runtime already owns.
- *
- * @experimental
- */
-type AgentTurnBackend = {
-    /** A live sandbox box: the turn is one `box.streamPrompt(prompt)` call. */
-    kind: 'box';
-    box: SandboxInstance;
-    /**
-     * Per-turn `PromptOptions` forwarded verbatim to `streamPrompt`
-     * (`sessionId`, `turnId`, `model`, `backend` profile, `timeoutMs`, …).
-     * The turn's derived abort signal (caller `signal` + `timeoutMs`
-     * deadline) is always installed as `signal` — pass cancellation through
-     * `StreamAgentTurnOptions`, not here.
-     */
-    options?: Omit<PromptOptions, 'signal'>;
-    /** Model label stamped on cost-only `llm_call` events. Default `'agent'`. */
-    agentRunName?: string;
-} | {
-    /**
-     * A live sandbox box in TASK mode: the turn is one
-     * `box.streamTask(prompt)` call — the sandbox SDK's autonomous-task
-     * verb. Unlike `streamPrompt` (one chat turn), the agent works until
-     * the task completes or errors, session state is maintained for
-     * continuity, and `options.maxTurns` bounds the agent's internal turns.
-     * Event projection, usage folding, and the terminal `final` contract
-     * are identical to the `box` kind.
-     */
-    kind: 'box-task';
-    box: SandboxInstance;
-    /**
-     * Per-task `TaskOptions` forwarded verbatim to `streamTask`
-     * (`maxTurns` plus every `PromptOptions` field). The turn's derived
-     * abort signal is always installed as `signal`.
-     */
-    options?: Omit<TaskOptions, 'signal'>;
-    /** Model label stamped on cost-only `llm_call` events. Default `'agent'`. */
-    agentRunName?: string;
-} | {
-    /**
-     * A one-shot `Executor` (cli-bridge / router / BYO): the factory is
-     * instantiated fresh for the turn via `inlineSandboxClient`, run once on
-     * the prompt, and torn down — the same per-spawn lifecycle the supervise
-     * runtime gives it.
-     */
-    kind: 'executor';
-    factory: ExecutorFactory<unknown>;
-    /** Model label stamped on cost-only `llm_call` events. Default `'agent'`. */
-    agentRunName?: string;
-} | {
-    /**
-     * An in-process `AgentExecutionBackend` (`resolveAgentBackend` output or
-     * any custom backend): the turn is one `backend.stream()` call.
-     */
-    kind: 'chat';
-    backend: AgentExecutionBackend;
-};
-/** @experimental */
-interface StreamAgentTurnOptions {
-    /** Caller-initiated cancellation. Terminates the stream with `final.status: 'aborted'`. */
-    signal?: AbortSignal;
-    /**
-     * Wall-clock deadline for the whole turn in ms. An expired deadline aborts
-     * the backend and terminates the stream with `final.status: 'failed'`
-     * (a blown deadline is a turn failure, not a caller cancellation).
-     */
-    timeoutMs?: number;
-    /**
-     * Opt-in tool-part projection for box-kind backends (`box`, `box-task`,
-     * `executor`): sandbox tool parts additionally surface in-stream as
-     * `tool_call` / `tool_result` events (`mapSandboxToolEvent`), so a consumer
-     * rendering tool activity needs no bespoke sandbox-event parser. Default
-     * off — the stream vocabulary existing consumers see is unchanged. No-op
-     * for the `chat` kind (its backend emits `RuntimeStreamEvent`s directly,
-     * tool events included when the backend produces them).
-     */
-    preserveToolParts?: boolean;
-    /**
-     * Raw-event tap for box-kind backends: called (and awaited) with every
-     * unmapped `SandboxEvent` BEFORE it is projected, so a consumer can read
-     * parts the chat-UX projection drops (part ids, step markers, custom
-     * backend events) without forking the mapper. Purely observational — it
-     * cannot alter the mapped stream. Never called for the `chat` kind, which
-     * has no sandbox events.
-     */
-    onRawEvent?: (event: SandboxEvent) => void | Promise<void>;
-}
-/**
- * Metered usage of one turn, summed over every cost-bearing event the backend
- * emitted. `input`/`output` are token counts (0 when the backend reported
- * none — the honest sum, never a fabricated estimate). `costUsd`/`model` are
- * present only when the backend actually reported them.
- *
- * @experimental
- */
-interface AgentTurnUsage {
-    input: number;
-    output: number;
-    costUsd?: number;
-    model?: string;
-}
-/**
- * A drained turn: the terminal summary plus every event the stream yielded.
- * `status`/`error` mirror the terminal `final` event so a failed or aborted
- * turn stays inspectable without re-scanning `events`.
- *
- * @experimental
- */
-interface CollectedAgentTurn {
-    finalText: string;
-    usage: AgentTurnUsage;
-    events: RuntimeStreamEvent[];
-    status: AgentTaskStatus;
-    error?: BackendErrorDetail;
-}
-/**
- * Run ONE agent turn on any backend kind and stream its events. Yields the
- * `RuntimeStreamEvent` vocabulary incrementally and always ends with a `final`
- * event carrying the turn's text and usage (`metadata.tokenUsage`,
- * `metadata.costUsd?`, `metadata.model?`) — on success, failure, abort, and
- * timeout alike. The generator never throws; failures surface in-band as
- * `backend_error` + `final` with a typed `error` detail.
- *
- * @experimental
- */
-declare function streamAgentTurn(backend: AgentTurnBackend, prompt: string, opts?: StreamAgentTurnOptions): AsyncGenerator<RuntimeStreamEvent>;
-/**
- * Drain a `streamAgentTurn` stream (or any `RuntimeStreamEvent` stream that
- * honors its terminal contract) into the turn summary plus the full event
- * list. Fail-loud: throws when the stream ends without a terminal `final`
- * event — a stream that violates the contract must not read as an empty turn.
- *
- * @experimental
- */
-declare function collectAgentTurn(stream: AsyncIterable<RuntimeStreamEvent>): Promise<CollectedAgentTurn>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/** 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;
-}
-/** Default thresholds for `ProfileRichnessThresholds` — 600 chars / 6 lines minimum system prompt. */
-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;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/** 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;
-
-/**
- *
- * `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.
- *
- * @experimental
- */
-
-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;
-    /** Hard cap on simultaneously-LIVE workers — `spawn_agent` fails closed once this many are in
-     *  flight (a concurrency fence on top of the conserved-pool fence). Omit/`<= 0` = no cap. */
-    readonly maxLiveWorkers?: number;
-    /** The analyst lenses available to the driver. Required for `analyzeOnSettle` (and `run_analyst`).
-     *  Unset → no analyst feed (status quo: the driver gets settled outputs, no findings). */
-    readonly analysts?: AnalystRegistry;
-    /** Analyst kind ids run AUTOMATICALLY when a worker settles `done` — each result re-enters as a
-     *  `finding` the driver pulls and composes its next steer from. The UP-leg of the self-improving
-     *  loop. Omit/empty = no auto-analysis (status quo). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-    /** Run the ONLINE detector panel over each worker's LIVE tool trace and raise a `finding` the
-     *  moment it loops/error-storms — mid-run evidence to steer on, not a settle-time post-mortem.
-     *  Omit = no online watching. */
-    readonly watchWorkers?: WorkerWatchOptions;
-    /** Idle time after which `observe_agent` reports a worker as stalled (a derived read; nothing is
-     *  killed). Omit = the runtime default. */
-    readonly stallAfterMs?: number;
-    /** 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;
-    /**
-     * PROGRESS-derived stop (mechanic D). Today a run ends on a ceiling — iterations, tokens,
-     * dollars, deadline, turn cap — which answers "may it continue?" and never "is it still getting
-     * anywhere?". A stop rule reads the run's own progress (best-so-far over settled work, time
-     * since the last settle, the live worker feed) and ends a run that has stopped learning BEFORE
-     * it exhausts a budget.
-     *
-     * Composes with, and can never override, the hard guards: `poolStarved` / `deadlinePassed` /
-     * abort / the driver's own stop are evaluated first, so a rule can only ADD a stop.
-     *
-     * THRESHOLDS are the caller's judgment, not this module's — build the rule with
-     * `plateau({window, minDelta})` / `noProgressFor({...})` / `allWorkersStalled({...})` from
-     * `supervise/stop-rules`. Omit ⇒ ceilings only (unchanged behavior).
-     */
-    readonly stopRule?: StopRule;
-    /** Called once with the rule's reason when a `stopRule` ends the run — so a caller can record
-     *  WHY a run stopped early instead of inferring it from an unexhausted budget. */
-    readonly onProgressStop?: (reason: string) => void;
-    /** Give the driver brain a chapter-lifecycle on its OWN context window. The LLM-brain front doors
-     *  lose to a dumb-Ralph respawn because the brain re-bills its whole coordination transcript every
-     *  turn — the same context overflow a single steered agent suffers, one level up. With this set,
-     *  once the brain's running conversation exceeds `thresholdTokens` it distills the accumulated
-     *  history to a compact progress note and continues fresh: the supervisor analog of respawning
-     *  against external tracking state, except the live `Scope` roster IS the durable state. Default
-     *  off (no behavior change). `distill` defaults to a self-summary authored by the brain combined
-     *  with the factual settled-worker roster; override to supply your own. */
-    readonly compaction?: ToolLoopCompactionOptions;
-}
-/**
- * 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>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-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;
-    }>;
-    /** Post-loop drain of already-settled, unpulled children into the ledger — call before reading
-     *  `settled()` for a finalize, so a delivered child the harness never awaited is not lost. */
-    drainResolved: CoordinationTools['drainResolved'];
-    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;
-    /** Hard cap on simultaneously-LIVE workers — `spawn_agent` fails closed once this many are in
-     *  flight (a concurrency fence on top of the conserved-pool fence). Omit/`<= 0` = no cap. */
-    maxLiveWorkers?: number;
-    /** Max wall-clock ms a single `await_event` may block before returning a re-pollable
-     *  `{ pending, live }` snapshot instead of erroring on the client's request timeout. Omit =
-     *  {@link DEFAULT_AWAIT_EVENT_TIMEOUT_MS}; `<= 0` = prior unbounded block (in-process only). */
-    awaitTimeoutMs?: number;
-    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>;
-    /** Run the ONLINE detector panel over each worker's live tool trace (raises `finding` events). */
-    watchWorkers?: WorkerWatchOptions;
-    /** Idle time after which `observe_agent` reports a worker as stalled. */
-    stallAfterMs?: number;
-    /** Pass-through subscriber for every bus event (settled / question / finding). */
-    onEvent?: (event: CoordinationEvent) => void | Promise<void>;
-    questionPolicy?: QuestionPolicy;
-}): Promise<CoordinationMcpHandle>;
-
-/**
- *
- * `delegate` — the one generic delegation verb. You hand it an INTENT (what you want done) and it
- * hands that intent to a default AUTHORING supervisor: a router-brained supervisor whose standing
- * instruction is `supervisorInstructions()` (the authoring-agent-profiles skill). The supervisor
- * DECOMPOSES the intent and AUTHORS the worker profile it needs per sub-task — there is NO hardcoded
- * coder/researcher profile here. That is the whole point: `delegate('fix the failing test', …)` and
- * `delegate('research X and cite sources', …)` route through the SAME front door; the supervisor
- * writes a code-shaped or research-shaped worker on its own.
- *
- * It is a thin wrapper over `supervise()` — the one front door — so the conserved-budget pool, the
- * completion oracle (`deliverable`), the coordination toolbox, and equal-compute accounting all come
- * for free; nothing is hand-rolled. The result is `supervise()`'s `SupervisedResult` returned
- * UNCHANGED, so its `spentTotal` (`{ iterations, tokens, usd, ms }`) rides straight back to the
- * caller on BOTH paths — a `winner` carries the delivered worker's spend, a `no-winner` carries the
- * spend incurred before it failed. That cost channel means a `delegate()` caller always learns what
- * the delegation actually spent.
- *
- * @experimental
- */
-
-/** The conserved pool a `delegate()` call applies when the caller does not pass its own `budget`.
- *  A modest token ceiling + a small iteration ceiling — generous enough for a few-worker decompose,
- *  bounded enough that an unsupervised intent cannot run away. Callers override via `opts.budget`. */
-declare const defaultDelegateBudget: Budget;
-/** Inputs to {@link delegate}. The intent is the first positional arg; everything here is optional
- *  with sensible defaults, so the common call is `delegate(intent, { backend, router })`. */
-interface DelegateOptions<Out = unknown> {
-    /** The completion oracle (settled ⟺ delivered) the authored workers settle against. Strongly
-     *  recommended — without it the supervisor trusts a worker's self-report. For a code intent,
-     *  `patchDelivered()` is the canonical example; for a free-form answer, a content check. */
-    readonly deliverable?: DeliverableSpec<Out>;
-    /** WHERE the authored workers run — the worker-execution backend (`router-tools` / `sandbox` /
-     *  `cli-worktree` / …). The supervisor authors the worker PROFILE; this is the substrate it runs
-     *  on. Provide this OR `makeWorkerAgent`-style wiring through `supervise()` is unavailable. */
-    readonly backend?: ExecutorConfig;
-    /** The conserved compute pool for the whole delegation. Defaults to {@link defaultDelegateBudget}. */
-    readonly budget?: Budget;
-    /** The model the supervisor BRAIN runs on (the router model). The brain must tool-call
-     *  (`spawn_agent` / `await_event`), so a delegator model, not a hidden-reasoning model. */
-    readonly model?: string;
-    /** The supervisor brain's router substrate. REQUIRED for the default router-brained supervisor
-     *  (the brain is resolved from this), unless a test injects `brain` directly. `model` overrides
-     *  `router.model`. (Design delta vs the bare `supervise()` profile: the brain needs a router.) */
-    readonly router?: RouterConfig;
-    /** Inject the supervisor brain directly (tests / advanced) instead of resolving it from `router`. */
-    readonly brain?: ToolLoopChat;
-    /** Override the default authoring-supervisor profile (name / extra system-prompt stance). The
-     *  default already carries the authoring skill; override only to add a goal or rename. */
-    readonly supervisor?: Partial<Pick<SupervisorProfile, 'name' | 'systemPrompt'>>;
-    /** Restrict the run to this subset of models (forwarded to `supervise()`). */
-    readonly allowedModels?: readonly string[];
-    readonly runId?: string;
-}
-/**
- * Delegate an INTENT to a default authoring supervisor and return its `SupervisedResult` unchanged.
- *
- * The supervisor authors + spawns whatever worker the intent needs over the conserved-budget pool;
- * `result.spentTotal` reports what the whole delegation actually cost. A `winner` result carries the
- * authored worker's delivered output; a `no-winner` result names why (never a fabricated success).
- */
-declare function delegate<Out = unknown>(intent: string, opts?: DelegateOptions<Out>): Promise<SupervisedResult<Out>>;
-
-/**
- *
- * `rollingDispatch` — the REFILLING dispatch policy over a `Scope`. It keeps `width` children in
- * flight and admits the next queued unit of work the instant one settles, instead of waiting for
- * a whole round to drain (`fanout`) or for a driver to decide again (`spawn → await → spawn`).
- *
- * The gap it closes: `fanout` opens every item at once and then drains — one round, no refill —
- * and a driver brain's manual loop opens one worker per model turn. Between those two there was
- * nothing that holds N slots full, which is why a 5-worker run can peak at 2 live workers and sit
- * ~50% idle. This is a policy over the EXISTING `Scope.spawn` / `Scope.next` primitives: it adds
- * no second admission path, so the conserved budget pool stays the only fence on total work and
- * `width` is only a fence on simultaneous work.
- *
- * Fail-closed by construction: an admission rejection (`budget-exhausted` / `depth-exceeded`) is
- * recorded and STOPS further admission — the loop then drains what is already live and returns.
- * It never retries a rejected spawn against the same pool, and it never spawns past `width`.
- *
- * ── The concurrency-cap ledger (read this before adding a fourth cap) ──────────────────────────
- *
- * Three unrelated caps bound "how much runs at once" in this stack, at three different layers.
- * They are NOT aware of each other, and the smallest one silently wins:
- *
- *   1. `CoordinationToolsOptions.maxLiveWorkers` (`src/mcp/tools/coordination.ts`) — supervisor
- *      level. How many workers may be spawned-but-not-settled at once; `spawn_agent` fails closed
- *      with `error: 'max-live-workers'` past it. Unset by default ⇒ NO cap at this layer.
- *   2. `SandboxLineage`'s `maxConcurrency` / `DEFAULT_FORK_CONCURRENCY = 4`
- *      (`src/runtime/sandbox-lineage.ts`) — kernel level. How many BOXES one `runAgentRounds` fork wave
- *      provisions at once. It bounds a single leaf's fanout, not the supervisor's worker count.
- *   3. A host's own live-box governor (e.g. loops' `ComputeGovernor`, `maxSandboxes = 4`) — fleet
- *      level. How many sandboxes may exist across the whole host process.
- *
- * The honest effective limit on simultaneous WORKERS is the minimum of the caps that apply to the
- * worker layer — (1) and (3). (2) is a different unit (boxes per fork wave inside one leaf) and
- * must not be min'd into it, or a 4-way fork inside one worker reads as a 4-worker ceiling.
- * `effectiveConcurrency` computes that minimum in one place so a host derives ONE number and
- * passes it to BOTH `maxLiveWorkers` and this dispatcher's `width`, instead of leaving a fleet
- * governor of 4 and an unset worker fence as unrelated numbers.
- *
- * ── Why this is not a copy of the kernel's batch loop ──────────────────────────────────────────
- *
- * `runBatch` (`src/runtime/run-loop.ts`) runs the same hold-N-slots-full shape over the KERNEL's
- * substrate: bare promises in a `Set`, raced with `Promise.race`, bounded by `maxConcurrency`.
- * This one runs it over the SUPERVISOR's substrate — `Scope.spawn`'s atomic reservation against
- * the conserved pool, `Scope.next`'s journaled settlement cursor, and the blob store behind each
- * result. Neither can be expressed in the other's terms without dragging its whole substrate
- * along: the kernel loop has no budget to reserve and no cursor to order settlements by, and this
- * one cannot race raw promises because a settlement is only real once it is journaled. The shape
- * repeating across the two deliberate layers is resonance, not duplication — do not "unify" them
- * into a shared helper that would have to know about both.
- *
- * @experimental
- */
-
-/** One unit of queued work: the agent to run, its task, and the spawn options (budget + label).
- *  `nextUnit` mints these lazily so a queue can be generated, re-ordered, or grown while the
- *  dispatcher runs. */
-interface DispatchUnit<Out> {
-    readonly agent: Agent<unknown, Out>;
-    readonly task: unknown;
-    readonly opts: SpawnOpts;
-}
-/** Why the dispatcher stopped admitting work. `drained` = the queue ran dry (the ordinary end);
- *  `not-admitted` = the conserved pool or the depth ceiling refused a spawn; `stopped` = the
- *  caller's `shouldStop` returned true; `aborted` = the scope's signal fired. */
-type DispatchStopReason = 'drained' | 'not-admitted' | 'stopped' | 'aborted';
-interface RollingDispatchOptions<Out> {
-    /**
-     * How many children to hold in flight. Must be a positive integer. This is a SIMULTANEITY fence
-     * only — the conserved pool still bounds total work, and a `width` larger than the pool can
-     * afford simply hits `not-admitted` sooner. Derive it with `effectiveConcurrency` when the host
-     * also runs a fleet-level box governor.
-     */
-    readonly width: number;
-    /**
-     * Produce the next unit of work, or `undefined` when the queue is dry. Called only when a slot
-     * is free, so a caller may compute the next unit from what has already settled (the point of a
-     * refilling dispatcher: the queue is allowed to react). Never called after a stop.
-     */
-    nextUnit(): DispatchUnit<Out> | undefined | Promise<DispatchUnit<Out> | undefined>;
-    /**
-     * Called once per settlement, in cursor order, BEFORE the freed slot is refilled — so an
-     * `onSettled` that appends to the caller's queue is visible to the very next `nextUnit`.
-     */
-    onSettled?(settled: Settled<Out>): void | Promise<void>;
-    /**
-     * Consulted before each admission. `true` stops admitting; the already-live children are still
-     * drained to completion (no orphan, no lost settlement). Use it for a progress/plateau rule.
-     */
-    shouldStop?(): boolean;
-}
-interface DispatchReport<Out> {
-    /** Every settlement, in the order `scope.next()` yielded them. */
-    readonly settled: ReadonlyArray<Settled<Out>>;
-    /** How many children this dispatcher admitted. */
-    readonly admitted: number;
-    /** Admission rejections, in order — `label: reason`. Non-empty ⇒ the pool or depth fenced. */
-    readonly rejected: ReadonlyArray<string>;
-    readonly stopReason: DispatchStopReason;
-    /** The highest simultaneous live count actually reached — the number to compare against
-     *  `width` when asking "did the slots really stay full?" */
-    readonly peakLive: number;
-}
-/**
- * Run the refilling dispatch loop over `scope` until the queue is dry (or a stop fires) and every
- * admitted child has settled. Returns the settlements in cursor order plus the admission ledger.
- *
- * The loop is: fill free slots from `nextUnit` → `await scope.next()` → deliver the settlement →
- * refill → repeat. Because the refill happens immediately after each settlement rather than after
- * a whole round, a slow child never idles the other slots.
- */
-declare function rollingDispatch<Out>(scope: Scope<Out>, opts: RollingDispatchOptions<Out>): Promise<DispatchReport<Out>>;
-/**
- * Free worker slots under a simultaneity cap: `cap - live`, floored at 0, or `null` when there is
- * no cap (the conserved pool is then the only fence and "free slots" is not a finite number).
- * The one place the answer is computed, so the driver-facing tool payload and a dispatcher agree.
- */
-declare function freeSlots(liveCount: number, cap: number | undefined): number | null;
-/** The caps a host can set on simultaneous work. See the ledger in this module's header for what
- *  each one actually bounds. */
-interface ConcurrencyCaps {
-    /** Supervisor level: max spawned-but-unsettled workers. */
-    readonly maxLiveWorkers?: number;
-    /** Fleet level: max live sandboxes/boxes across the host process (a `ComputeGovernor`-style
-     *  cap). Applies to the worker layer, so it participates in the minimum. */
-    readonly maxSandboxes?: number;
-}
-/**
- * The ONE honest effective limit on simultaneous workers: the minimum of the caps that actually
- * bound the worker layer. Ignores unset/non-positive caps; returns `undefined` when no cap applies
- * (uncapped — the conserved pool remains the only fence).
- *
- * Deliberately does NOT fold in `SandboxLineage`'s fork concurrency: that bounds boxes inside ONE
- * leaf's fork wave, a different unit. Folding it in would report a 4-worker ceiling for what is
- * really a 4-box fanout inside a single worker.
- *
- * Use it once, at the top of a run, and pass the result to BOTH `maxLiveWorkers` and a
- * dispatcher's `width` — that is what turns three unrelated numbers into one.
- */
-declare function effectiveConcurrency(caps: ConcurrencyCaps): number | undefined;
-/** Convenience: a `DispatchUnit` factory over a fixed array of tasks, for the common case where
- *  the queue is known up front and only the refill behavior is wanted. */
-declare function queueOf<Out>(units: ReadonlyArray<{
-    agent: Agent<unknown, Out>;
-    task: unknown;
-    label: string;
-}>, budget: Budget): () => DispatchUnit<Out> | undefined;
-
-/**
- * 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;
-
-/**
- *
- * `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 })
- *
- * @experimental
- */
-
-/** Options for a supervised 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;
-    /**
-     * Present (and `true`) only on a DURABLE context (`createFileRunContext`), so spreading the
-     * context into `SupervisorOpts` also opts the run into resume-first. An in-memory context
-     * leaves it undefined: there is never a prior tree to resume, and the default stays fresh-run.
-     */
-    readonly resume?: boolean;
-}
-/** The stores a supervised run needs, in-memory or file-backed. `InMemoryRunContext` is the
- *  historical name for the same shape. */
-type RunContext = InMemoryRunContext;
-/**
- * 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;
-/**
- * Build a DURABLE run context: the spawn journal and the result blobs are file-backed (fsynced
- * per append/write) under `dir`, and the context carries `resume: true` so spreading it into
- * `SupervisorOpts` makes the supervisor `loadTree`-first. A run that dies mid-flight therefore
- * resumes when it is re-run with the SAME `runId` and the SAME `dir`: the committed children come
- * back on `Scope.resume` (rehydrated by `replaySpawnTree`) instead of being re-executed.
- *
- * Layout: `${dir}/spawn-journal.jsonl` (one JSONL record per event) and `${dir}/blobs/` (one
- * content-addressed JSON file per settled result). The directory is created on first write.
- *
- * Opt-in by construction — `createInMemoryRunContext()` is unchanged and stays the default, so no
- * existing consumer writes to disk or resumes unless it asks for this.
- */
-declare function createFileRunContext(dir: string, opts?: InMemoryRunContextOptions): RunContext;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/** 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;
-    /** Predicate resolver for `poll` wait-states. Absent ⇒ `wait` refuses a `poll` with
-     *  `unknown-probe`; `timer` waits never touch it. */
-    readonly probes?: WaitProbeRegistry;
-    /** Injected sleeper for wait-states — a test drives a week-long timer in microseconds. */
-    readonly waitSleep?: (ms: number, signal: AbortSignal) => Promise<void>;
-    /** 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 `runAgentRounds`/`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;
-    /**
-     * Resume seam — set ONLY by the supervisor when `SupervisorOpts.resume` is on AND a non-empty
-     * journal tree exists for this root. It carries the replayed committed work (so `scope.resume`
-     * exposes it to a resume-aware `act`) and the recorded ordinal/cursor maxima the new counters
-     * continue past, so a freshly-spawned child never reuses a journaled `seq`. Absent ⇒ fresh run.
-     */
-    readonly resumeFrom?: {
-        readonly settled: ReadonlyArray<Settled<unknown>>;
-        readonly view: TreeView;
-        /** Highest `spawned` ordinal already journaled; new spawns start at `+1`. */
-        readonly maxSpawnOrdinal: number;
-        /** Highest cursor `seq` already journaled; new settlements start at `+1`. */
-        readonly maxCursorSeq: number;
-        /** Highest `waiting` ordinal already journaled; new waits start at `+1`. */
-        readonly maxWaitOrdinal: number;
-        /** Waits journaled as armed but never woken — re-armed (same node id, same absolute deadline)
-         *  when `wait` is called again with the SAME label. */
-        readonly waits: ReadonlyArray<PendingWait>;
-    };
-}
-/** Create the reactive `Scope` a driver's `Agent.act` runs inside: spawn children on an atomically reserved conserved budget, settle via the `next()` cursor, journal for replay. */
-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` 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.
- *
- * @experimental
- */
-
-declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-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) — allows one intervening call so it
-     * 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>;
-
-/** What a surface worker settles with — the surface verdict the driver + deliverable read. `resolved` is
- *  the surface check's pass/fail (settled ⟺ resolved); `score` is the partial-credit fraction; `failing`
- *  carries the tests this worker left red (so the analyst can target them). */
-interface SurfaceWorkerOut {
-    readonly resolved: boolean;
-    readonly score: number;
-    readonly shots: number;
-    readonly summary: string;
-    readonly failing?: readonly string[];
-}
-/** The default self-improvement LENS — authored content, not a code path. On each settled worker it hands
- *  the driver the still-FAILING tests (not just a score), so the next spawn targets the persistently-hard
- *  cases. Swap `analysts` to change what the driver improves from — that's the one knob. */
-declare function failuresAnalyst(): AnalystRegistry;
-/** How a worker runs the surface task (its router substrate + per-attempt bounds). */
-interface SurfaceWorkerConfig {
-    readonly routerBaseUrl: string;
-    readonly routerKey: string;
-    readonly model: string;
-    readonly maxTokens?: number;
-    readonly innerTurns?: number;
-    /** Refine-shot budget for ONE worker attempt (max steered shots). Default 1. */
-    readonly budget?: number;
-}
-interface SuperviseSurfaceOptions {
-    /** The graded surface workers solve (open/tools/call/score/close). */
-    readonly surface: AgenticSurface;
-    /** Where/how each worker runs the surface task. */
-    readonly worker: SurfaceWorkerConfig;
-    /** The conserved compute pool for the whole supervised run. Default: sized off the worker's inner-loop
-     *  bounds for a handful of worker spawns — raise it to let the driver try more. */
-    readonly budget?: Budget;
-    /** The driver brain's router substrate (its own inference). Default: the worker's router + model — the
-     *  driver and workers share one router unless you separate them (e.g. a stronger driver model). */
-    readonly router?: RouterConfig;
-    /** The self-improvement lens fed to the driver on each settled worker. Default `failuresAnalyst()`
-     *  (target the still-failing tests). Pass a custom registry to change it, or `null` to turn the
-     *  within-run self-improvement OFF (the driver sees raw settled outputs). */
-    readonly analysts?: AnalystRegistry | null;
-    /** The strategy each worker runs over the surface. Default `refine` (iterate-with-feedback). */
-    readonly strategy?: Strategy;
-    /** Max workers live at once. Default 1 (serial — required when workers share a persistent artifact, so
-     *  they continue each other instead of racing the file). */
-    readonly maxLiveWorkers?: number;
-}
-/** The deployable outcome of a supervised surface run. */
-interface SuperviseSurfaceResult {
-    readonly resolved: boolean;
-    readonly score: number;
-    readonly usd: number;
-    readonly tokensIn: number;
-    readonly tokensOut: number;
-    readonly ms: number;
-    /** Total conserved-pool iterations = the driver + worker LLM rounds the run actually spent. */
-    readonly completions: number;
-}
-/** Drive a team of agents (spawned + steered by `profile`) to solve a graded `AgenticSurface` task, and
- *  report the deployable outcome + the full conserved spend. This is `supervise()` configured for surfaces
- *  — there is no other entrypoint to learn. */
-declare function superviseSurface(profile: SupervisorProfile, task: AgenticTask, opts: SuperviseSurfaceOptions): Promise<SuperviseSurfaceResult>;
-
-/**
- * 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;
-}
-/** Any checkable task as an `Environment`, no tool surface required: the artifact is the worker's answer and the domain is one deployable `check` over it. */
-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>;
-}
-/** Host-process `Shell`: run a command via `execFile`, resolving `{ stdout, stderr, code }` (never throws on non-zero exit). */
-declare function localShell(): Shell;
-interface GitWorkspaceOptions {
-    readonly ref: string;
-    readonly shell?: Shell;
-    readonly branch?: string;
-    readonly noHooks?: boolean;
-}
-/** A `Workspace` over a git checkout: materialize an isolated worktree at `ref`, commit produced changes (conflict-aware), and read `head` — hooks disabled, identity pinned. */
-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 AgentTurnBackend, type AgentTurnUsage, AgenticOptions, AgenticSurface, AgenticTask, AgenticTool, AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, 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, type CollectedAgentTurn, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, type ConcurrencyCaps, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type DefinedLeaderboard, type DelegateOptions, type Deliverable, DeliverableSpec, type DispatchReport, type DispatchStopReason, type DispatchUnit, Driver, type DriverAgentOptions, type DumbDriverOptions, type Environment, EqualKArm, EqualKOnCostOptions, EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, ExecutorConfig, ExecutorFactory, ExecutorRegistry, FanoutOptions, FanoutWinnerSelector, FileCorpus, FileResultBlobStore, FileSpawnJournal, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, type InMemoryRunContext, type InMemoryRunContextOptions, InMemorySpawnJournal, type InProcessOnPrompt, type InProcessPromptCtx, type InProcessSandboxClientOptions, type IntentAudit, type Interval, Iteration, type KeyProvider, type Leaderboard, type LeaderboardBenchScore, type LeaderboardBenchTask, type LeaderboardBenchmarkAdapter, type LeaderboardFlagSpec, type LeaderboardIterationInfo, type LeaderboardOptions, type LeaderboardRow, type LeaderboardRunContext, type LeaderboardScenario, type LeaderboardScore, type LeaderboardSpec, type LocalMcpMaterialization, type LocalSandboxClientOptions, type LoopCampaignDispatchOptions, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, MakeWorkerAgent, type MaterializeLocalMcpOptions, type McpEndpoint, type McpEnvironmentOptions, McpSpawnFault, type McpToolDescriptor, MountRecorder, type NaiveDriverOptions, NodeId, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunBeforeStartContext, type OpenSandboxRunOptions, type OpenSandboxRunPromptOptions, Outcome, OutputAdapter, type PairwiseOptions, type PairwiseVerdict, PanelSpec, PendingWait, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, type ResolveSandboxClientOptions, ResultBlobStore, type RollingDispatchOptions, RouterConfig, type RunAgentRoundsOptions, type RunContext, type RunLoopOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, type SandboxToolPartState, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, Settled, ShapeRegistry, type Shell, SpawnEvent, SpawnJournal, SpawnOpts, Spend, type StdioMcpConnection, type StdioMcpServerSpec, SteerContext, type SteeringDecision, StopRule, Strategy, type StrategyEvolutionConfig, type StreamAgentTurnOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, SupervisedResult, Supervisor, SupervisorProfile, SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, ToolLoopChat, ToolLoopCompactionOptions, TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, WaitProbeRegistry, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, analyzeTrace, anytimeReport, areaUnderCurve, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, bestSoFar, buildSteerContext, builtinShapes, collectAgentTurn, completionAuthorizes, connectStdioMcp, contentAddress, createBudgetPool, createFileRunContext, createInMemoryRunContext, createMcpEnvironment, createSandboxLineage, createSandboxToolPartState, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultProfileRichnessThresholds, defaultSelectWinner, defineLeaderboard, definePersona, delegate, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, effectiveConcurrency, envKeyProvider, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, finalizeBestDelivered, flatWidenGate, freeSlots, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, jjWorkspace, leaderboard, localSandboxClient, localShell, loopCampaignDispatch, loopDispatch, loopUntil, mapSandboxEvent, mapSandboxToolEvent, materializeLocalMcp, materializeTreeView, mcpSecretEnvMetadataKey, naiveDriver, observe, openSandboxRun, pairwiseSignificance, panel, pendingWaits, pickChampion, pipeline, plateauLength, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, queueOf, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, replaySpawnTree, reportLoopUsage, resolveSandboxClient, resolveSecretEnv, rollingDispatch, runAgentRounds, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sanitizeMcpToolSchema, secretEnvOfMcpServer, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, streamAgentTurn, sumSandboxUsage, superviseSurface, supervisorInstructions, trajectoryReport, verify, widen };
+import { C as MountRecorder, D as SelectionReceipt, E as SandboxClient, O as ValidationCtx, S as MountManifestEntry, T as RunProvenance, _ as LoopTeardownFailedPayload, a as Iteration, b as LoopTraceEvent, c as LoopIterationDispatchPayload, d as LoopLineageOptions, f as LoopPlanDescription, g as LoopStartedPayload, h as LoopSandboxPlacement, i as ExecCtx, k as Validator, l as LoopIterationEndedPayload, m as LoopResult, n as DefaultVerdict, o as LoopDecisionPayload, p as LoopPlanPayload, r as Driver, s as LoopEndedPayload, t as AgentRunSpec, u as LoopIterationStartedPayload, v as LoopTokenUsage, w as OutputAdapter, x as LoopWinner, y as LoopTraceEmitter } from "./types-BevOjfTY.js";
+import { $ as RootSignal, A as providerAsSandboxClient, At as createPushTraceSource, B as Executor, Bt as readWorkerProgress, C as ProviderAsSandboxClientOptions, Ct as timerAt, D as WorkspaceRequest, Dt as SessionTraceBox, E as SandboxClientProviderOptions, Et as SessionMessageLike, F as createTangleSandboxExactProcessProvider, Ft as DEFAULT_STALL_AFTER_MS, G as Handle, H as ExecutorFactory, I as Agent, It as ExecutorProgress, J as NodeStatus, K as NodeId, L as AgentSpec, Lt as ScopeProgressInput, M as sandboxClientAsProvider, Mt as sandboxSessionTraceSource, N as CreateTangleSandboxExactProcessProviderOptions, Nt as ActivityLog, O as createAgentEnvironmentProviderRegistry, Ot as ToolStepInput, P as SandboxControlClient, Pt as ActivityNote, Q as RootHandle, R as Budget, Rt as WorkerProgress, S as PlacementInfo, St as pollFor, T as ResourceRequest, Tt as waitUntil, U as ExecutorRegistry, V as ExecutorContext, W as ExecutorResult, X as ResultBlobStore, Y as Restart, Z as ResumedWork, _ as CheckpointRequest, _t as WaitProbeRegistry, a as AgentEnvironmentProviderRef, at as SpawnOpts, b as ExecResult, bt as createWaitProbes, c as AgentEnvironmentStatus, ct as Supervisor, d as AgentSession, dt as UsageEvent, et as Runtime, f as AgentSessionRef, ft as WaitOpts, g as CheckpointRef, gt as WaitProbe, h as AgentTurnResult, ht as WaitOutcome, i as AgentEnvironmentProvider, it as SpawnJournal, j as resolveAgentEnvironmentProvider, jt as decodeToolPart, k as providerAsExecutor, kt as TraceSource, l as AgentEnvironmentSummary, lt as SupervisorOpts, m as AgentTurnInput, mt as PendingWait, n as AgentEnvironmentCapabilities, nt as Settled, o as AgentEnvironmentProviderRegistry, ot as Spend, p as AgentSessionStatus, pt as WidenGate, q as NodeSnapshot, r as AgentEnvironmentEvent, rt as SpawnEvent, s as AgentEnvironmentQuery, st as SupervisedResult, t as AgentEnvironment, tt as Scope, u as AgentProfileRef, ut as TreeView, v as CreateAgentEnvironmentInput, vt as WaitRejection, w as ProviderExecutorOptions, wt as validateWaitSpec, x as ForkRequest, xt as isWaitOutcome, y as ExecRequest, yt as WaitSpec, zt as createActivityLog } from "./environment-provider-IUGU3epE.js";
+import { $ as effectiveConcurrency, $a as WidenDecision, $i as mcpSecretEnvMetadataKey, $n as connectStdioMcp, $o as auditIntent, $r as createScopeAnalyst, $s as createExecutor, $t as StructuralRolloutMessage, $u as FileSpawnJournal, A as createSupervisor, Aa as FlatWidenGate, Ai as SurfaceScore, An as ReproductionCheck, Ao as completionAuthorizes, Ar as promotionGate, At as sampleFromSettled, B as createFileRunContext, Ba as RenderCorpusToInstructions, Bi as LoopDispatchOptions, Bn as strategyAuthorContract, Bo as PairwiseOptions, Br as renderCorpusToInstructions, Bt as assessAuthoredProfile, C as failuresAnalyst, Ca as EqualKOnCost, Ci as ShotSpec, Cn as ChampionPolicy, Co as LeaderboardScore, Cr as probeSandboxCapabilities, Ct as StopRule, D as worktreeFanout, Da as FanoutOptions, Dc as gateOnDeliverable, Di as StrategyMessage, Dn as EvolutionCandidate, Do as CompletionEvidence, Dr as resolveSandboxClient, Dt as createProgressTracker, E as WorktreeFanoutOptions, Ea as Fanout, Ec as DeliverableSpec, Ei as StrategyCtx, En as EvolutionBandInfo, Eo as CompletionAnalyst, Er as ResolveSandboxClientOptions, Et as anyOf, F as createScope, Fa as PanelJudge, Fi as refine, Fn as selectChampion, Fo as GroupOf, Fr as registerShape, Ft as spendFromUsageEvents, G as WorktreePatchArtifact, Ga as SteerContext, Gi as RunLoopOptions, Gn as dumbDriver, Go as pairwiseSignificance, Gr as pipeline, Gs as CliWorktreeBridgeSeam, Gt as CheckExecChannel, Gu as BusStats, H as PatchDeliverableOptions, Ha as ScopeAnalyst, Hi as loopCampaignDispatch, Hn as DumbDriverOptions, Ho as ProfileKeyOf, Hr as flatWidenGate, Ht as defaultProfileRichnessThresholds, I as settledToIteration, Ia as PanelSpec, Ii as runAgentic, In as AuthorStrategyOptions, Io as Interval, Ir as definePersona, It as AuthoredProfile, J as ConcurrencyCaps, Ja as TrajectoryReportFn, Ji as runLoop, Jn as MaterializeLocalMcpOptions, Jo as renderLeaderboardSvg, Jr as widen, Js as ProviderSeam, Jt as CheckRunner, Ju as createEventBus, K as createWorktreeCliExecutor, Ka as TrajectoryNode, Ki as defaultSelectWinner, Kn as naiveDriver, Ko as renderLeaderboardHtml, Kr as selectValidWinner, Ks as CliWorktreeSeam, Kt as CheckOutcome, Ku as EventBus, L as InMemoryRunContext, La as PanelVerdict, Li as sample, Ln as AuthoredStrategy, Lo as Leaderboard, Lr as runPersonified, Lt as ProfileRichness, M as supervise, Ma as LoopUntilSpec, Mi as breadthStrategy, Mn as discriminatingMeans, Mo as sentinelCompletion, Mr as trajectoryReport, Mt as BudgetReadout, N as workerFromBackend, Na as LoopUntilState, Ni as defineStrategy, Nn as pickChampion, No as stopSentinel, Nr as builtinShapes, Nt as ReservationTicket, O as TrajectoryAnalysis, Oa as FanoutSynthesis, Oi as StrategyResult, On as EvolutionGeneration, Oo as CompletionPolicy, Or as PromotionGateOptions, Ot as noProgressFor, P as ScopeArgs, Pa as Panel, Pi as depthStrategy, Pn as runStrategyEvolution, Po as AxisScoresOf, Pr as createShapeRegistry, Pt as createBudgetPool, Q as RollingDispatchOptions, Qa as Widen, Qi as envKeyProvider, Qn as StdioMcpServerSpec, Qo as IntentAudit, Qr as buildSteerContext, Qs as cliWorktreeExecutor, Qt as StructuralRolloutConfig, Qu as FileResultBlobStore, R as InMemoryRunContextOptions, Ra as Pipeline, Ri as sampleThenRefine, Rn as assertStrategyContract, Ro as LeaderboardOptions, Rr as FileCorpus, Rt as ProfileRichnessThresholds, S as SurfaceWorkerOut, Sa as EqualKArm, Si as ShotPersona, Sn as ChampionPick, So as LeaderboardScenario, Sr as SandboxCapabilities, St as StopDecision, T as AuthoredHarness, Ta as EqualKVerdict, Ti as StrategyArtifacts, Tn as EvolutionAuthor, To as defineLeaderboard, Tr as acquireSandbox, Tt as allWorkersStalled, U as patchDelivered, Ua as ScopeAnalyzeInput, Ui as loopDispatch, Un as NaiveDriverOptions, Uo as ScoreOf, Ur as loopUntil, Us as BridgeSeam, Ut as profileRichnessFinding, Uu as BusEvent, V as createInMemoryRunContext, Va as RenderCorpusToInstructionsOptions, Vi as LoopOptionsForDispatch, Vn as ApplyContinuation, Vo as PairwiseVerdict, Vr as fanout, Vt as authoredWorker, W as WorktreeCliExecutorOptions, Wa as ScopeWidenGate, Wi as RunAgentRoundsOptions, Wn as SteeringDecision, Wo as leaderboard, Wr as panel, Ws as CliSeam, Wt as supervisorInstructions, Wu as BusRecord, X as DispatchStopReason, Xa as Verify, Xi as localSandboxClient, Xn as McpToolDescriptor, Xo as AuditIntentInput, Xr as RegistryAnalyzeProjection, Xs as RouterToolsSeam, Xt as CheckSourceCtx, Xu as defaultToolDetectors, Y as DispatchReport, Ya as TrajectoryReportOptions, Yi as LocalSandboxClientOptions, Yn as McpSpawnFault, Yo as renderPairwiseMarkdown, Yr as CreateScopeAnalystOptions, Ys as RouterSeam, Yt as CheckSource, Yu as WatchTraceOptions, Z as DispatchUnit, Za as VerifySpec, Zi as KeyProvider, Zn as StdioMcpConnection, Zo as AuditIntentOptions, Zr as assertTraceDerivedFindings, Zs as SandboxSeam, Zt as RepairStop, Zu as watchTrace, _ as VerifierEnvironmentOptions, _a as AssertTraceDerivedFindings, _i as AgenticTask, _n as AgentTurnUsage, _o as LeaderboardBenchTask, _r as extractLlmCallEvent, _t as PlateauOptions, a as SandboxInstance, aa as InProcessSandboxClientOptions, ac as createSteerableSandboxSession, ad as replaySpawnTree, ai as BenchmarkCell, an as composeCheckSources, ao as LoopShape, ar as SandboxRun, as as areaUnderCurve, at as delegate, b as SuperviseSurfaceResult, ba as CorpusFilter, bi as CorpusReadbackOptions, bn as collectAgentTurn, bo as LeaderboardIterationInfo, br as sumSandboxUsage, bs as MakeWorkerAgent, bt as ProgressTrackerOptions, c as GitWorkspaceOptions, ca as HarvestFailure, cc as createInbox, ci as BenchmarkReport, cn as filterAuthoredAsserts, co as PersonaContext, cr as openSandboxRun, cs as renderAnytimeTable, ct as SupervisorProfile, d as WorkspaceCommit, da as Observation, dc as piExecutor, di as Environment, dn as resolveEntrySymbol, do as RunPersonifiedOptions, dr as SandboxLineage, ds as WaterfallSpan, dt as serveCoordinationMcp, ea as resolveSecretEnv, ec as createExecutorRegistry, ed as InMemoryResultBlobStore, ei as registryScopeAnalyst, en as StructuralRolloutPolicy, eo as WidenLineage, er as materializeLocalMcp, es as defaultAuditorInstruction, et as freeSlots, f as WorkspaceRun, fa as ObserveInput, fc as piSeamKey, fi as printBenchmarkReport, fn as sandboxCheckRunner, fo as ShapeBudget, fr as SandboxLineageHandle, fs as createWaterfallCollector, ft as DriverAgentOptions, g as runInWorkspace, ga as renderReport, gc as WorktreeProfileMaterializationReceipt, gi as AgenticSurface, gn as AgentTurnBackend, go as LeaderboardBenchScore, gr as createSandboxToolPartState, gt as NoProgressForOptions, h as localShell, ha as observe, hc as WorktreeHarnessResult, hi as AgenticRunResult, hn as visibleCheckScore, ho as DefinedLeaderboard, hr as SandboxToolPartState, hs as CoordinationEvent, ht as AllWorkersStalledOptions, i as SandboxEvent, ia as InProcessPromptCtx, ic as SteerableSandboxSession, id as pendingWaits, ii as sanitizeMcpToolSchema, in as compareCheckOutcomes, io as DefinePersonaInput, ir as OpenSandboxRunPromptOptions, is as anytimeReport, it as defaultDelegateBudget, j as SuperviseOptions, ja as LoopUntil, ji as adaptiveRefine, jn as StrategyEvolutionConfig, jo as deterministicCompletion, jr as equalKOnCost, jt as BudgetPool, k as analyzeTrace, ka as FanoutWinnerSelector, ki as StrategyShotResult, kn as EvolutionReport, ko as CompletionVerdict, kr as PromotionVerdict, kt as plateau, l as Shell, la as HarvestReport, lc as PI_RUNTIME, li as BenchmarkStrategySummary, ln as modelAuthoredChecks, lo as PersonaExecutors, lr as CheckpointCapableBox, ls as WaterfallCollector, lt as supervisorAgent, m as jjWorkspace, ma as defaultAnalystInstruction, mc as WorktreeCommandResult, mi as AgenticOptions, mn as structuralRollout, mo as ShapeRegistry, mr as createSandboxLineage, ms as AnalystRegistry, mt as finalizeBestDelivered, n as AnalystFinding, na as inlineSandboxClient, nc as SandboxSteeringOptions, nd as contentAddress, ni as McpEnvironmentOptions, nn as VisibleCheck, no as WinnerStrategy, nr as OpenSandboxRunBeforeStartContext, ns as AnytimeStrategySummary, nt as rollingDispatch, o as computeFindingId, oa as inProcessSandboxClient, oc as Inbox, oi as BenchmarkConfig, on as defaultExtractCandidate, oo as Outcome, or as SandboxRunAbortError, os as bestSoFar, ot as DriveHarness, p as gitWorkspace, pa as ObserveOptions, pc as WorktreeCheckRunner, pi as runBenchmark, pn as selectBestIndex, po as ShapeContext, pr as SessionCapableBox, ps as AnalystFindingEvent, pt as driverAgent, q as assertModelAllowed, qa as TrajectoryReport, qi as runAgentRounds, qn as LocalMcpMaterialization, qo as renderLeaderboardMarkdown, qr as verify, qs as ExecutorConfig, qt as CheckRunContext, qu as PublishOptions, r as CreateSandboxOptions, ra as InProcessOnPrompt, rc as SteerableSandboxArgs, rd as materializeTreeView, ri as createMcpEnvironment, rn as canDisplace, ro as DefinePersona, rr as OpenSandboxRunOptions, rs as AnytimeTaskCurve, rt as DelegateOptions, s as makeFinding, sa as HarvestCorpusOptions, sc as InboxMessage, si as BenchmarkLift, sn as defaultStructuralRolloutPolicy, so as Persona, sr as TurnResult, ss as plateauLength, st as SupervisorAgentDeps, t as AgentProfile, ta as secretEnvOfMcpServer, tc as DEFAULT_SANDBOX_STEERING_MAX_TURNS, td as InMemorySpawnJournal, ti as McpEndpoint, tn as StructuralRolloutResult, to as WidenSpec, tr as Deliverable, ts as AnytimeReport, tt as queueOf, u as Workspace, ua as harvestCorpus, uc as PiSeam, ui as BenchmarkTaskRow, un as officialChecksFromMeta, uo as RunPersonified, ur as ForkCapableBox, us as WaterfallReport, ut as CoordinationMcpHandle, v as createVerifierEnvironment, va as CombinatorShape, vi as AgenticTool, vn as CollectedAgentTurn, vo as LeaderboardBenchmarkAdapter, vr as mapSandboxEvent, vs as DEFAULT_AWAIT_EVENT_TIMEOUT_MS, vt as ProgressSample, w as superviseSurface, wa as EqualKOnCostOptions, wi as Strategy, wn as EvolutionArchiveNode, wo as LeaderboardSpec, wr as AcquireOptions, wt as allOf, x as SurfaceWorkerConfig, xa as CorpusRecord, xi as RunAgenticOptions, xn as streamAgentTurn, xo as LeaderboardRunContext, xr as CriuCapableClient, xt as ProgressView, y as SuperviseSurfaceOptions, ya as Corpus, yi as ArtifactHandle, yn as StreamAgentTurnOptions, yo as LeaderboardFlagSpec, yr as mapSandboxToolEvent, ys as DownMessageEvent, yt as ProgressTracker, z as RunContext, za as PipelineStage, zi as LoopCampaignDispatchOptions, zn as authorStrategy, zo as LeaderboardRow, zr as InMemoryCorpus, zt as asAuthoredProfile } from "./index-DruSKs3Z.js";
+import { S as ToolLoopMessageRecord, _ as routerChatWithUsage, b as ToolLoopCompaction, d as RouterConfig, f as RouterToolCall, g as routerChatWithTools, h as routerBrain, l as RouterChatResult, m as ToolSpec, p as RouterToolLoopResult, u as RouterChatToolsResult, v as routerToolLoop, x as ToolLoopCompactionOptions, y as ToolLoopChat } from "./local-harness-Dh8PJ0ot.js";
+export { type AcquireOptions, type ActivityLog, type ActivityNote, type Agent, type AgentEnvironment, type AgentEnvironmentCapabilities, type AgentEnvironmentEvent, type AgentEnvironmentProvider, type AgentEnvironmentProviderRef, type AgentEnvironmentProviderRegistry, type AgentEnvironmentQuery, type AgentEnvironmentStatus, type AgentEnvironmentSummary, type AgentProfile, type AgentProfileRef, type AgentRunSpec, type AgentSession, type AgentSessionRef, type AgentSessionStatus, type AgentSpec, type AgentTurnBackend, type AgentTurnInput, type AgentTurnResult, type AgentTurnUsage, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AllWorkersStalledOptions, type AnalystFinding, type AnalystFindingEvent, type AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, type ArtifactHandle, type AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredHarness, type AuthoredProfile, type AuthoredStrategy, type AxisScoresOf, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, type BridgeSeam, type Budget, type BudgetPool, type BudgetReadout, type BusEvent, type BusRecord, type BusStats, type ChampionPick, type ChampionPolicy, type CheckExecChannel, type CheckOutcome, type CheckRunContext, type CheckRunner, type CheckSource, type CheckSourceCtx, type CheckpointCapableBox, type CheckpointRef, type CheckpointRequest, type CliSeam, type CliWorktreeBridgeSeam, type CliWorktreeSeam, type CollectedAgentTurn, type CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, type ConcurrencyCaps, type CoordinationEvent, type CoordinationMcpHandle, type Corpus, type CorpusFilter, type CorpusReadbackOptions, type CorpusRecord, type CreateAgentEnvironmentInput, type CreateSandboxOptions, type CreateScopeAnalystOptions, type CreateTangleSandboxExactProcessProviderOptions, type CriuCapableClient, DEFAULT_AWAIT_EVENT_TIMEOUT_MS, DEFAULT_SANDBOX_STEERING_MAX_TURNS, DEFAULT_STALL_AFTER_MS, type DefaultVerdict, type DefinePersona, type DefinePersonaInput, type DefinedLeaderboard, type DelegateOptions, type Deliverable, type DeliverableSpec, type DispatchReport, type DispatchStopReason, type DispatchUnit, type DownMessageEvent, type DriveHarness, type Driver, type DriverAgentOptions, type DumbDriverOptions, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EventBus, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, type ExecCtx, type ExecRequest, type ExecResult, type Executor, type ExecutorConfig, type ExecutorContext, type ExecutorFactory, type ExecutorProgress, type ExecutorRegistry, type ExecutorResult, type Fanout, type FanoutOptions, type FanoutSynthesis, type FanoutWinnerSelector, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, type ForkRequest, type GitWorkspaceOptions, type GroupOf, type Handle, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, type InMemoryRunContext, type InMemoryRunContextOptions, InMemorySpawnJournal, type InProcessOnPrompt, type InProcessPromptCtx, type InProcessSandboxClientOptions, type Inbox, type InboxMessage, type IntentAudit, type Interval, type Iteration, type KeyProvider, type Leaderboard, type LeaderboardBenchScore, type LeaderboardBenchTask, type LeaderboardBenchmarkAdapter, type LeaderboardFlagSpec, type LeaderboardIterationInfo, type LeaderboardOptions, type LeaderboardRow, type LeaderboardRunContext, type LeaderboardScenario, type LeaderboardScore, type LeaderboardSpec, type LocalMcpMaterialization, type LocalSandboxClientOptions, type LoopCampaignDispatchOptions, type LoopDecisionPayload, type LoopDispatchOptions, type LoopEndedPayload, type LoopIterationDispatchPayload, type LoopIterationEndedPayload, type LoopIterationStartedPayload, type LoopLineageOptions, type LoopOptionsForDispatch, type LoopPlanDescription, type LoopPlanPayload, type LoopResult, type LoopSandboxPlacement, type LoopShape, type LoopStartedPayload, type LoopTeardownFailedPayload, type LoopTokenUsage, type LoopTraceEmitter, type LoopTraceEvent, type LoopUntil, type LoopUntilSpec, type LoopUntilState, type LoopWinner, type MakeWorkerAgent, type MaterializeLocalMcpOptions, type McpEndpoint, type McpEnvironmentOptions, McpSpawnFault, type McpToolDescriptor, type MountManifestEntry, type MountRecorder, type NaiveDriverOptions, type NoProgressForOptions, type NodeId, type NodeSnapshot, type NodeStatus, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunBeforeStartContext, type OpenSandboxRunOptions, type OpenSandboxRunPromptOptions, type Outcome, type OutputAdapter, PI_RUNTIME, type PairwiseOptions, type PairwiseVerdict, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type PatchDeliverableOptions, type PendingWait, type Persona, type PersonaContext, type PersonaExecutors, type PiSeam, type Pipeline, type PipelineStage, type PlacementInfo, type PlateauOptions, type ProfileKeyOf, type ProfileRichness, type ProfileRichnessThresholds, type ProgressSample, type ProgressTracker, type ProgressTrackerOptions, type ProgressView, type PromotionGateOptions, type PromotionVerdict, type ProviderAsSandboxClientOptions, type ProviderExecutorOptions, type ProviderSeam, type PublishOptions, type RegistryAnalyzeProjection, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type RepairStop, type ReproductionCheck, type ReservationTicket, type ResolveSandboxClientOptions, type ResourceRequest, type Restart, type ResultBlobStore, type ResumedWork, type RollingDispatchOptions, type RootHandle, type RootSignal, type RouterChatResult, type RouterChatToolsResult, type RouterConfig, type RouterSeam, type RouterToolCall, type RouterToolLoopResult, type RouterToolsSeam, type RunAgentRoundsOptions, type RunAgenticOptions, type RunContext, type RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type RunProvenance, type Runtime, type SandboxCapabilities, type SandboxClient, type SandboxClientProviderOptions, type SandboxControlClient, type SandboxEvent, type SandboxInstance, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, type SandboxSeam, type SandboxSteeringOptions, type SandboxToolPartState, type Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeArgs, type ScopeProgressInput, type ScopeWidenGate, type ScoreOf, type SelectionReceipt, type SessionCapableBox, type SessionMessageLike, type SessionTraceBox, type Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, type SpawnEvent, type SpawnJournal, type SpawnOpts, type Spend, type StdioMcpConnection, type StdioMcpServerSpec, type SteerContext, type SteerableSandboxArgs, type SteerableSandboxSession, type SteeringDecision, type StopDecision, type StopRule, type Strategy, type StrategyArtifacts, type StrategyCtx, type StrategyEvolutionConfig, type StrategyMessage, type StrategyResult, type StrategyShotResult, type StreamAgentTurnOptions, type StructuralRolloutConfig, type StructuralRolloutMessage, type StructuralRolloutPolicy, type StructuralRolloutResult, type SuperviseOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, type SupervisedResult, type Supervisor, type SupervisorAgentDeps, type SupervisorOpts, type SupervisorProfile, type SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, type ToolLoopChat, type ToolLoopCompaction, type ToolLoopCompactionOptions, type ToolLoopMessageRecord, type ToolSpec, type ToolStepInput, type TraceSource, type TrajectoryAnalysis, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, type TreeView, type TurnResult, type UsageEvent, type ValidationCtx, type Validator, type VerifierEnvironmentOptions, type Verify, type VerifySpec, type VisibleCheck, type WaitOpts, type WaitOutcome, type WaitProbe, type WaitProbeRegistry, type WaitRejection, type WaitSpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, type Widen, type WidenDecision, type WidenGate, type WidenLineage, type WidenSpec, type WinnerStrategy, type WorkerProgress, type Workspace, type WorkspaceCommit, type WorkspaceRequest, type WorkspaceRun, type WorktreeCheckRunner, type WorktreeCliExecutorOptions, type WorktreeCommandResult, type WorktreeFanoutOptions, type WorktreeHarnessResult, type WorktreePatchArtifact, type WorktreeProfileMaterializationReceipt, acquireSandbox, adaptiveRefine, allOf, allWorkersStalled, analyzeTrace, anyOf, anytimeReport, areaUnderCurve, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, bestSoFar, breadthStrategy, buildSteerContext, builtinShapes, canDisplace, cliWorktreeExecutor, collectAgentTurn, compareCheckOutcomes, completionAuthorizes, composeCheckSources, computeFindingId, connectStdioMcp, contentAddress, createActivityLog, createAgentEnvironmentProviderRegistry, createBudgetPool, createEventBus, createExecutor, createExecutorRegistry, createFileRunContext, createInMemoryRunContext, createInbox, createMcpEnvironment, createProgressTracker, createPushTraceSource, createSandboxLineage, createSandboxToolPartState, createScope, createScopeAnalyst, createShapeRegistry, createSteerableSandboxSession, createSupervisor, createTangleSandboxExactProcessProvider, createVerifierEnvironment, createWaitProbes, createWaterfallCollector, createWorktreeCliExecutor, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultExtractCandidate, defaultProfileRichnessThresholds, defaultSelectWinner, defaultStructuralRolloutPolicy, defaultToolDetectors, defineLeaderboard, definePersona, defineStrategy, delegate, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, effectiveConcurrency, envKeyProvider, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, filterAuthoredAsserts, finalizeBestDelivered, flatWidenGate, freeSlots, gateOnDeliverable, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, isWaitOutcome, jjWorkspace, leaderboard, localSandboxClient, localShell, loopCampaignDispatch, loopDispatch, loopUntil, makeFinding, mapSandboxEvent, mapSandboxToolEvent, materializeLocalMcp, materializeTreeView, mcpSecretEnvMetadataKey, modelAuthoredChecks, naiveDriver, noProgressFor, observe, officialChecksFromMeta, openSandboxRun, pairwiseSignificance, panel, patchDelivered, pendingWaits, piExecutor, piSeamKey, pickChampion, pipeline, plateau, plateauLength, pollFor, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, providerAsExecutor, providerAsSandboxClient, queueOf, readWorkerProgress, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, replaySpawnTree, resolveAgentEnvironmentProvider, resolveEntrySymbol, resolveSandboxClient, resolveSecretEnv, rollingDispatch, routerBrain, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentRounds, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleFromSettled, sampleThenRefine, sandboxCheckRunner, sandboxClientAsProvider, sandboxSessionTraceSource, sanitizeMcpToolSchema, secretEnvOfMcpServer, selectBestIndex, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, streamAgentTurn, structuralRollout, sumSandboxUsage, supervise, superviseSurface, supervisorAgent, supervisorInstructions, timerAt, trajectoryReport, validateWaitSpec, verify, visibleCheckScore, waitUntil, watchTrace, widen, workerFromBackend, worktreeFanout };