@tangle-network/agent-runtime 0.82.0 → 0.84.0

package/dist/loops.d.ts

@@ -1,32 +1,31 @@
-import { ChatClient, RunRecord, AnalystFinding, AgentProfile, AnalystRunInputs, ToolSpan, StreamingDetector, DetectorSignal, buildTrajectory } from '@tangle-network/agent-eval';
+import { ChatClient, RunRecord, HarnessType, AgentProfile, AnalystFinding, AnalystRunInputs, ToolSpan, StreamingDetector, DetectorSignal, buildTrajectory } from '@tangle-network/agent-eval';
 export { AnalystFinding, DefaultVerdict, computeFindingId, makeFinding } from '@tangle-network/agent-eval';
 import { SandboxEvent, SandboxInstance, CreateSandboxOptions } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { d as ResultBlobStore, S as SpawnJournal, N as NodeId, j as SpawnEvent, E as ExecutorFactory, c as Agent, B as Budget, i as Scope, g as Settled, f as SupervisedResult, h as Spend, U as UsageEvent, b as ExecutorRegistry, k as Supervisor } from './types-By9LXllv.js';
-export { A as AgentSpec, a as Executor, l as ExecutorContext, m as ExecutorResult, R as Runtime, n as SupervisorOpts, T as TreeView, W as WidenGate } from './types-By9LXllv.js';
-import { ak as MakeWorkerAgent, A as AnalystRegistry, o as CoordinationTools, n as CoordinationEvent, ar as QuestionPolicy, a$ as ExecutorConfig } from './coordination-BI9tpcmF.js';
-export { b0 as BusEvent, b1 as BusRecord, b2 as BusStats, b3 as EventBus, b4 as ProviderSeam, b5 as PublishOptions, b6 as cliWorktreeExecutor, b7 as createEventBus, b8 as createExecutor, b9 as createExecutorRegistry } from './coordination-BI9tpcmF.js';
-import { R as RuntimeHooks, I as Iteration, S as SandboxClient, W as Driver, A as AgentRunSpec, b as OutputAdapter, V as Validator, E as ExecCtx, X as LoopWinner, Y as LoopLineageOptions, Z as LoopResult, L as LoopTokenUsage, a as RuntimeStreamEvent, _ as MountRecorder } from './types-BF-MEsQB.js';
-export { $ as LoopDecisionPayload, a0 as LoopEndedPayload, a1 as LoopIterationDispatchPayload, a2 as LoopIterationEndedPayload, a3 as LoopIterationStartedPayload, a4 as LoopPlanDescription, a5 as LoopPlanPayload, d as LoopSandboxPlacement, a6 as LoopStartedPayload, a7 as LoopTeardownFailedPayload, e as LoopTraceEmitter, c as LoopTraceEvent, a8 as MountManifestEntry, a9 as RunProvenance, aa as SelectionReceipt, ab as ValidationCtx } from './types-BF-MEsQB.js';
+import { d as ResultBlobStore, S as SpawnJournal, N as NodeId, j as SpawnEvent, E as ExecutorFactory, c as Agent, B as Budget, i as Scope, g as Settled, f as SupervisedResult, h as Spend, U as UsageEvent, b as ExecutorRegistry, k as Supervisor } from './types-Driepl87.js';
+export { A as AgentSpec, a as Executor, l as ExecutorContext, m as ExecutorResult, R as Runtime, n as SupervisorOpts, T as TreeView, W as WidenGate } from './types-Driepl87.js';
+import { ak as MakeWorkerAgent, A as AnalystRegistry, o as CoordinationTools, n as CoordinationEvent, ar as QuestionPolicy, a$ as ExecutorConfig } from './coordination-CuDLO8wj.js';
+export { b0 as BusEvent, b1 as BusRecord, b2 as BusStats, b3 as EventBus, b4 as ProviderSeam, b5 as PublishOptions, b6 as cliWorktreeExecutor, b7 as createEventBus, b8 as createExecutor, b9 as createExecutorRegistry } from './coordination-CuDLO8wj.js';
+import { R as RuntimeHooks, I as Iteration, S as SandboxClient, W as Driver, A as AgentRunSpec, b as OutputAdapter, V as Validator, E as ExecCtx, X as LoopWinner, Y as LoopLineageOptions, Z as LoopResult, L as LoopTokenUsage, a as RuntimeStreamEvent, _ as MountRecorder } from './types-ESeMOj94.js';
+export { $ as LoopDecisionPayload, a0 as LoopEndedPayload, a1 as LoopIterationDispatchPayload, a2 as LoopIterationEndedPayload, a3 as LoopIterationStartedPayload, a4 as LoopPlanDescription, a5 as LoopPlanPayload, d as LoopSandboxPlacement, a6 as LoopStartedPayload, a7 as LoopTeardownFailedPayload, e as LoopTraceEmitter, c as LoopTraceEvent, a8 as MountManifestEntry, a9 as RunProvenance, aa as SelectionReceipt, ab as ValidationCtx } from './types-ESeMOj94.js';
+import { RunProfileMatrixResult, Scenario, ProfileDispatchFn, JudgeConfig, RunProfileMatrixOptions, DispatchFn } from '@tangle-network/agent-eval/campaign';
 export { AgentEnvironmentProviderRef, AgentEnvironmentProviderRegistry, ProviderAsSandboxClientOptions, ProviderExecutorOptions, SandboxClientProviderOptions, createAgentEnvironmentProviderRegistry, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider } from './environment-provider.js';
-import { C as CorpusRecord, c as Corpus, O as Outcome, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, e as SteerContext, f as ScopeAnalyst, F as FanoutOptions, g as CombinatorShape, h as ScopeWidenGate, L as LoopUntilSpec, P as PanelSpec, i as PipelineStage, W as WinnerStrategy, j as FanoutWinnerSelector, V as VerifySpec, k as WidenSpec, l as CorpusFilter, R as RenderCorpusToInstructionsOptions, D as DefinePersonaInput, m as Persona, n as RunPersonifiedOptions, o as ShapeRegistry, p as LoopShape, E as EqualKArm, q as EqualKOnCostOptions, r as EqualKVerdict, T as TrajectoryReportOptions, s as TrajectoryReport } from './worktree-fanout-D9Z2dMS9.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-D9Z2dMS9.js';
-import { Scenario, DispatchFn, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
+import { C as CorpusRecord, c as Corpus, O as Outcome, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, e as SteerContext, f as ScopeAnalyst, F as FanoutOptions, g as CombinatorShape, h as ScopeWidenGate, L as LoopUntilSpec, P as PanelSpec, i as PipelineStage, W as WinnerStrategy, j as FanoutWinnerSelector, V as VerifySpec, k as WidenSpec, l as CorpusFilter, R as RenderCorpusToInstructionsOptions, D as DefinePersonaInput, m as Persona, n as RunPersonifiedOptions, o as ShapeRegistry, p as LoopShape, E as EqualKArm, q as EqualKOnCostOptions, r as EqualKVerdict, T as TrajectoryReportOptions, s as TrajectoryReport } from './worktree-fanout-D6xR2CIA.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-D6xR2CIA.js';
 import { b as AnalystRegistryLike } from './types-BC3bZpH0.js';
 import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
-import { R as RouterConfig, a as ToolLoopChat, b as ToolLoopCompactionOptions } from './router-client-D6Ocf4jG.js';
-export { c as RouterChatResult, d as RouterChatToolsResult, e as RouterToolCall, f as RouterToolLoopResult, g as ToolLoopCompaction, T as ToolSpec, r as routerBrain, h as routerChatWithTools, i as routerChatWithUsage, j as routerToolLoop } from './router-client-D6Ocf4jG.js';
-import { D as DeliverableSpec } from './worktree-harness-Dx8XULW3.js';
-export { g as WorktreeCommandResult, h as gateOnDeliverable } from './worktree-harness-Dx8XULW3.js';
+import { R as RouterConfig, a as ToolLoopChat, b as ToolLoopCompactionOptions } from './router-client-r8y_VFVM.js';
+export { c as RouterChatResult, d as RouterChatToolsResult, e as RouterToolCall, f as RouterToolLoopResult, g as ToolLoopCompaction, T as ToolSpec, r as routerBrain, h as routerChatWithTools, i as routerChatWithUsage, j as routerToolLoop } from './router-client-r8y_VFVM.js';
+import { D as DeliverableSpec } from './worktree-harness-CX_McRLp.js';
+export { g as WorktreeCommandResult, h as gateOnDeliverable } from './worktree-harness-CX_McRLp.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-rNj6TDc3.js';
+import './substrate-DO2GHNg2.js';
 import './otel-export-BKmNwiCb.js';
-import './local-harness-DU7yV6mG.js';
+import './local-harness-sI0S_XNA.js';
 import 'node:child_process';
 
 /**
- * @experimental
  *
  * Event-sourced spawn journal for the recursive execution atom (build steps 3 + 7).
  *
@@ -44,6 +43,8 @@ import 'node:child_process';
  * 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
  */
 
 /**
@@ -136,6 +137,7 @@ interface WaterfallCollector {
     }): string;
     reset(): void;
 }
+/** Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. */
 declare function createWaterfallCollector(): WaterfallCollector;
 
 /**
@@ -273,7 +275,9 @@ interface IntentAudit {
     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>;
 
 /**
@@ -410,7 +414,6 @@ declare function renderLeaderboardSvg(report: Leaderboard): string;
 declare function renderLeaderboardHtml(report: Leaderboard): string;
 
 /**
- * @experimental
  *
  * Completion / satisfiability — the OTHER output of the pluggable analyst (the steer output
  * is `AnalystFinding[]` via the `analyze` hook; this is the "is it done?" output via the
@@ -431,6 +434,8 @@ declare function renderLeaderboardHtml(report: Leaderboard): string;
  *     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,
@@ -464,6 +469,7 @@ 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
@@ -488,6 +494,158 @@ declare function deterministicCompletion<Task, Output>(check: (output: Output, h
     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()`. */
+interface LeaderboardBenchmarkAdapter {
+    readonly name: string;
+    preflight(): Promise<void>;
+    loadTasks(opts?: {
+        limit?: number;
+        split?: string;
+        ids?: string[];
+    }): Promise<LeaderboardBenchTask[]>;
+    judge(task: LeaderboardBenchTask, artifact: string): Promise<LeaderboardBenchScore>;
+    goldArtifact(task: LeaderboardBenchTask): Promise<string | undefined>;
+}
+interface LeaderboardSpec<TCase> {
+    /** 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 text → 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: string, 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 each parsed iteration,
+     *  with the case — the seam for domain metric capture (search counts,
+     *  citations) without a substrate change. */
+    onCellEvents?: (events: readonly SandboxEvent[], c: TCase) => void;
+    /** Output decode override: raw events → the scored output text. Default:
+     *  the sandbox SDK's `collectAgentResponseText` (final answer text; empty
+     *  string when the stream carried none — which then scores 0). */
+    parseOutput?: (events: readonly SandboxEvent[], c: TCase) => string;
+    /** 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<string, 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>, string>;
+    /** LEVEL 2 — full judge replacement. Default: `score` wrapped as one judge. */
+    judges?: JudgeConfig<string, LeaderboardScenario<TCase>>[];
+    /** Naive-retry shot cap per cell (`--shots`). Default 1. */
+    shots?: number;
+    /** Replicates per cell (`--reps`). Default 1. */
+    reps?: number;
+    /** 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>, string>>;
+}
+interface DefinedLeaderboard<TCase> {
+    /**
+     * 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<string, LeaderboardScenario<TCase>>>;
+    /** The same domain surface in the structural `BenchmarkAdapter` shape. */
+    toBenchmarkAdapter(): LeaderboardBenchmarkAdapter;
+}
+declare function defineLeaderboard<TCase>(spec: LeaderboardSpec<TCase>): DefinedLeaderboard<TCase>;
+
 /**
  * The third-person observer — the connective tissue that closes the loop.
  *
@@ -546,6 +704,7 @@ interface Observation {
     /** 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. */
@@ -605,6 +764,7 @@ interface HarvestReport {
     /** 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` call. */
@@ -664,7 +824,6 @@ declare function inProcessSandboxClient(options: InProcessSandboxClientOptions):
 declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): SandboxClient;
 
 /**
- * @experimental
  *
  * `runLoop` — the topology-agnostic kernel built atop the sandbox SDK.
  *
@@ -686,6 +845,8 @@ declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): Sandbox
  * 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 */
@@ -753,7 +914,11 @@ interface RunLoopOptions<Task, Output, Decision> {
      */
     lineage?: LoopLineageOptions;
 }
-/** @experimental */
+/**
+ * The round-synchronous loop kernel: each round `driver.plan()` fans N tasks to sandboxes (bounded concurrency), parses + validates each output, and folds results through `driver.decide`.
+ *
+ * @experimental
+ */
 declare function runLoop<Task, Output, Decision>(options: RunLoopOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
 /**
  * The kernel's winner argmax — best-valid-score, ties broken by earliest index,
@@ -975,7 +1140,9 @@ interface Strategy {
     readonly name: string;
     driver(surface: AgenticSurface, task: AgenticTask, opts: AgenticOptions, budget: number): Agent<unknown, Outcome<unknown>>;
 }
+/** Built-in `Strategy`: K independent attempts, keep the best-verifying (best-of-N / resample). */
 declare const sample: Strategy;
+/** Built-in `Strategy`: attempt → `observe()` reads the trace → steer the next attempt → repeat (deepen one lineage). */
 declare const refine: Strategy;
 /** A role for one shot — multi-agent loops (researcher + engineer, a panel of k
  *  researchers) give each shot its own system prompt and optionally its own model. */
@@ -1144,6 +1311,7 @@ interface BenchmarkStrategySummary {
     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;
@@ -1206,10 +1374,10 @@ interface McpEnvironmentOptions {
     /** Cap on a tool result's text fed back to the worker. Default 1500 chars. */
     maxResultChars?: number;
 }
+/** 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;
 
 /**
- * @experimental
  *
  * Analyst-on-scope (G1) — the analyze→findings→steer wire over the reactive `Scope`.
  *
@@ -1226,6 +1394,8 @@ declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
  * 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;
@@ -1303,7 +1473,6 @@ declare function registryScopeAnalyst<D>(registry: AnalystRegistryLike, buildInp
 declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, settledSoFar: ReadonlyArray<Settled<Outcome<D>>>): SteerContext<D>;
 
 /**
- * @experimental
  *
  * The generic combinator library — the content-free act-bodies the wave's §1 contract froze.
  *
@@ -1323,6 +1492,8 @@ declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, s
  * 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
  */
 
 /**
@@ -1406,7 +1577,6 @@ declare function widen<Task, Seed, D>(spec: WidenSpec<Seed, D>): CombinatorShape
 declare function flatWidenGate<D>(): ScopeWidenGate<D>;
 
 /**
- * @experimental
  *
  * The cross-run corpus (G2) — the learning-flywheel's durable accreted-fact store.
  *
@@ -1421,6 +1591,8 @@ declare function flatWidenGate<D>(): ScopeWidenGate<D>;
  * 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
  */
 
 /**
@@ -1475,7 +1647,6 @@ declare class FileCorpus implements Corpus {
 declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOptions): Promise<AgentProfile$1>;
 
 /**
- * @experimental
  *
  * The personify layer impl — `definePersona` (the thin builder) + `runPersonified` (composes
  * the persona + chosen shape onto the keystone `Supervisor`), plus `createShapeContext`, the
@@ -1492,6 +1663,8 @@ declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOpti
  * 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
  */
 
 /**
@@ -1510,7 +1683,6 @@ declare function definePersona<D = unknown>(input: DefinePersonaInput<D>): Perso
 declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>): Promise<SupervisedResult<Outcome<D>>>;
 
 /**
- * @experimental
  *
  * The loop-shape registry — the OPEN, content-free extension point for the personify layer.
  *
@@ -1524,6 +1696,8 @@ declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>
  * `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
  */
 
 /**
@@ -1539,7 +1713,6 @@ declare const builtinShapes: ShapeRegistry;
 declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D>): void;
 
 /**
- * @experimental
  *
  * Trajectory trace + cost ledger — the post-hoc tree reconstructor (§4 of `wave-types`).
  *
@@ -1560,6 +1733,8 @@ declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D
  * 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
  */
 
 /**
@@ -1635,6 +1810,7 @@ interface PromotionVerdict {
         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;
 
 /**
@@ -1720,7 +1896,6 @@ interface ResolveSandboxClientOptions {
 declare function resolveSandboxClient(opts: ResolveSandboxClientOptions): SandboxClient;
 
 /**
- * @experimental
  *
  * `acquireSandbox` — cold-start-resilient sandbox acquisition. Eliminates the
  * "create timed out at the proxy" failure mode conceptually by DECOUPLING "the
@@ -1744,6 +1919,8 @@ declare function resolveSandboxClient(opts: ResolveSandboxClientOptions): Sandbo
  * 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 */
@@ -1765,11 +1942,14 @@ interface AcquireOptions {
     /** Sleep override for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
 }
-/** @experimental */
+/**
+ * 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>;
 
 /**
- * @experimental
  *
  * Capability probe for the loop kernel's backend-blind lineage seams. The
  * kernel must NEVER ask "is this Docker or Firecracker?"; it asks "can this
@@ -1781,6 +1961,8 @@ declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOpt
  * 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
  */
 
 /**
@@ -1892,7 +2074,6 @@ declare function mapSandboxEvent(event: SandboxEvent, opts?: {
 }): RuntimeStreamEvent | undefined;
 
 /**
- * @experimental
  *
  * `SandboxLineage` — the backend-blind owner of box + session handles for a
  * single `runLoop` invocation. It exists so `run-loop.ts` never references a
@@ -1923,6 +2104,8 @@ declare function mapSandboxEvent(event: SandboxEvent, opts?: {
  * 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
  */
 
 /**
@@ -2074,12 +2257,13 @@ interface SessionCapableBox {
  */
 
 /**
- * @experimental
  * How a typed deliverable `Out` is materialized from a finished turn.
  * - `events`   — pure parse over the event array (identical to `OutputAdapter`).
  * - `artifact` — read a file off the box AFTER the turn drains, then map it (+ the
  *                events). For diffs/codebases/documents that don't fit the chat
  *                stream. `path` relative ⇒ workspace root; absolute ⇒ container FS.
+ *
+ * @experimental
  */
 type Deliverable<Out> = {
     kind: 'events';
@@ -2090,10 +2274,11 @@ type Deliverable<Out> = {
     fromArtifact: (raw: string, events: SandboxEvent[]) => Out;
 };
 /**
- * @experimental
  * One finished turn over the artifact. A failed FS read is surfaced in `readError`
  * (never masked as an empty deliverable) so a caller distinguishes "agent produced
  * nothing" from a transport/FS fault.
+ *
+ * @experimental
  */
 interface TurnResult<Out> {
     out: Out;
@@ -2101,7 +2286,6 @@ interface TurnResult<Out> {
     readError?: string;
 }
 /**
- * @experimental
  * 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
@@ -2109,6 +2293,8 @@ interface TurnResult<Out> {
  *
  * `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";
@@ -2149,15 +2335,15 @@ interface OpenSandboxRunOptions {
     readRetryDelayMs?: number;
 }
 /**
- * @experimental
  * Open a sandbox run. Harness-agnostic: the harness lives in
  * `options.agentRun.sandboxOverrides.backend.type`, so opencode/codex/claude-code/
  * kimi-code all flow through this one entrypoint with identical env/auth wiring.
+ *
+ * @experimental
  */
 declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandboxRunOptions, deliverable: Deliverable<Out>): Promise<SandboxRun<Out>>;
 
 /**
- * @experimental
  *
  * Leak-free steering drivers — the non-LLM controls for the driven loop.
  *
@@ -2198,6 +2384,8 @@ declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandbox
  * They consume nothing the loop kernel does not already give `plan()`/`decide()`
  * — `runLoop` requires no change. A benchmark picks a driver by name and the
  * kernel does the rest.
+ *
+ * @experimental
  */
 
 /**
@@ -2554,10 +2742,10 @@ declare function pickChampion(means: Record<string, {
 }>, 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>;
 
 /**
- * @experimental
  *
  * The supervisor's intelligence is AUTHORING the agents it spawns — not pressing buttons.
  *
@@ -2569,6 +2757,8 @@ declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<Evo
  *
  * 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`). */
@@ -2602,6 +2792,7 @@ interface ProfileRichnessThresholds {
     /** 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 {
@@ -2639,7 +2830,6 @@ declare function profileRichnessFinding(richness: ProfileRichness, opts?: {
 }): AnalystFinding;
 
 /**
- * @experimental
  *
  * The conserved budget reservation pool — the invariant the whole instrument
  * rests on (critique M5/B3). One root `Budget` becomes a conserved pool of three
@@ -2657,6 +2847,8 @@ declare function profileRichnessFinding(richness: ProfileRichness, opts?: {
  * 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
@@ -2735,7 +2927,6 @@ declare function spendFromUsageEvents(events: UsageEvent[]): Spend;
 declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
 
 /**
- * @experimental
  *
  * `driverAgent` — the driver's BRAIN.
  *
@@ -2759,6 +2950,8 @@ declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
  *    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 {
@@ -2835,7 +3028,6 @@ declare function finalizeBestDelivered(settled: ReadonlyArray<{
 }>, blobs: ResultBlobStore): Promise<unknown>;
 
 /**
- * @experimental
  *
  * Serve the coordination verbs (spawn_agent / await_event / observe_agent / steer_agent / stop)
  * as a real HTTP MCP server over a LIVE `Scope`. This is the keystone that lets a coding-harness
@@ -2852,6 +3044,8 @@ declare function finalizeBestDelivered(settled: ReadonlyArray<{
  * 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 {
@@ -2955,10 +3149,10 @@ interface SupervisorAgentDeps {
      *  instead of re-billing the whole thing every turn. See `DriverAgentOptions.compaction`. */
     readonly compaction?: ToolLoopCompactionOptions;
 }
+/** Build a supervisor `Agent` from its profile: the brain resolves from `profile.harness` (backend-as-data), the same resolution rule as every worker. */
 declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAgentDeps): Agent<unknown, unknown>;
 
 /**
- * @experimental
  *
  * `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
@@ -2975,6 +3169,8 @@ declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAge
  * 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`.
@@ -3020,7 +3216,6 @@ interface DelegateOptions<Out = unknown> {
 declare function delegate<Out = unknown>(intent: string, opts?: DelegateOptions<Out>): Promise<SupervisedResult<Out>>;
 
 /**
- * @experimental
  *
  * `TraceSource` — the ONE substrate-agnostic source of a worker's tool-call trace. The online
  * detectors and the settle-time analyzers consume agent-eval `ToolSpan`s from here, regardless of
@@ -3036,6 +3231,8 @@ declare function delegate<Out = unknown>(intent: string, opts?: DelegateOptions<
  *
  * This module imports NO substrate SDK — it decodes generic message parts / OpenAI tool-call shapes.
  * The sandbox wiring (`sandboxSessionTraceSource`) is the thin adapter that feeds box session parts in.
+ *
+ * @experimental
  */
 
 interface ToolStepInput {
@@ -3095,13 +3292,14 @@ declare function sandboxSessionTraceSource(box: SessionTraceBox, sessionId: stri
 }): TraceSource;
 
 /**
- * @experimental
  *
  * The ONLINE analyst: watch a `TraceSource` and fold each tool span through agent-eval's published
  * streaming detector kernel (`repeatedActionDetector`/`errorStreakDetector` — the SAME kernel the
  * control loop folds), firing `onSignal` the moment a worker loops or error-storms. Substrate-
  * agnostic: it consumes spans from any source (owned router/bridge loop OR a sandbox box session),
  * never the raw tool seam. Detection logic + the failure taxonomy live in agent-eval; not reimplemented.
+ *
+ * @experimental
  */
 
 interface WatchTraceOptions {
@@ -3124,7 +3322,6 @@ declare function defaultToolDetectors(): StreamingDetector[];
 declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () => void;
 
 /**
- * @experimental
  *
  * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
  * `Executor.deliver`. The driver's `steer_agent` / `answer_question` land here,
@@ -3138,6 +3335,8 @@ declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () =
  *     of a wrong path mid-task instead of waiting for it to finish the step.
  *
  * `deliver` never throws — a malformed message is ignored, per the `Executor.deliver` contract.
+ *
+ * @experimental
  */
 interface InboxMessage {
     readonly kind: 'steer' | 'answer';
@@ -3159,6 +3358,7 @@ interface Inbox {
     /** Render drained messages as ONE operator turn to fold into the worker's conversation. */
     fold(messages: ReadonlyArray<InboxMessage>): string;
 }
+/** Create the worker-side inbox for the down-leg: the driver's `steer_agent` / `answer_question` messages queue here and the worker's loop drains them at step boundaries and before settle. */
 declare function createInbox(): Inbox;
 
 /**
@@ -3169,7 +3369,6 @@ declare function createInbox(): Inbox;
 declare function assertModelAllowed(model: string | undefined, allowed: readonly string[] | undefined): void;
 
 /**
- * @experimental
  *
  * `createInMemoryRunContext` — the one-call bundle of the in-memory stores a
  * `createSupervisor().run(root, task, opts)` needs: a fresh `InMemorySpawnJournal`
@@ -3191,6 +3390,8 @@ declare function assertModelAllowed(model: string | undefined, allowed: readonly
  * 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 the in-memory run context. */
@@ -3219,7 +3420,6 @@ interface InMemoryRunContext {
 declare function createInMemoryRunContext(opts?: InMemoryRunContextOptions): InMemoryRunContext;
 
 /**
- * @experimental
  *
  * The reactive `Scope` impl (KEYSTONE, build step 4 + the step-8 adapter).
  *
@@ -3242,6 +3442,8 @@ declare function createInMemoryRunContext(opts?: InMemoryRunContextOptions): InM
  * 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,
@@ -3275,6 +3477,7 @@ interface ScopeArgs {
      *  (the topology viewer reads it). Undefined ⇒ the journal stays the only record. */
     readonly hooks?: RuntimeHooks;
 }
+/** 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
@@ -3351,10 +3554,10 @@ interface SuperviseOptions {
      *  or `supervise()` throws a `ConfigError` before any compute is spent. Unset = unrestricted. */
     readonly allowedModels?: readonly string[];
 }
+/** One-call supervisor: build + run a supervisor from its profile with sensible defaults; the raw `supervisorAgent` + `createSupervisor().run` seams stay available for power use. */
 declare function supervise(profile: SupervisorProfile, task: unknown, opts: SuperviseOptions): Promise<SupervisedResult<unknown>>;
 
 /**
- * @experimental
  *
  * The `Supervisor` impl (KEYSTONE, build step 5).
  *
@@ -3386,18 +3589,21 @@ declare function supervise(profile: SupervisorProfile, task: unknown, opts: Supe
  * 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>;
 
 /**
- * @experimental
  *
  * The SETTLE-time analyst: when a worker finishes, collect its tool spans from a `TraceSource` and run
  * agent-eval's PUBLISHED batch analyzers over them — `buildTrajectory` (structured run summary),
  * `stuckLoopView` (full-run repeated-call view, complementing the online consecutive detector), and
  * `toolWasteView`. Substrate-agnostic: the spans come from any source (an owned loop's buffer OR a
  * sandbox box session). No analysis reimplemented — this is the thin bridge into agent-eval's analyzers.
+ *
+ * @experimental
  */
 
 interface TrajectoryAnalysis {
@@ -3513,6 +3719,7 @@ interface VerifierEnvironmentOptions {
     /** 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`. */
@@ -3534,6 +3741,7 @@ interface Workspace {
     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;
@@ -3541,6 +3749,7 @@ interface GitWorkspaceOptions {
     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:
@@ -3569,4 +3778,4 @@ declare function runInWorkspace<T>(ws: Workspace, body: (cwd: string) => Promise
     commitOnInvalid?: boolean;
 }): Promise<WorkspaceRun<T>>;
 
-export { Agent, AgentRunSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, type ArtifactHandle, AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type DelegateOptions, type Deliverable, DeliverableSpec, type DriveHarness, 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, type ForkCapableBox, type GitWorkspaceOptions, 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, Iteration, type Leaderboard, type LeaderboardOptions, type LeaderboardRow, type LoopCampaignDispatchOptions, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, MakeWorkerAgent, type McpEndpoint, type McpEnvironmentOptions, MountRecorder, type NaiveDriverOptions, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, Outcome, OutputAdapter, type PairwiseOptions, type PairwiseVerdict, PanelSpec, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, type ResolveSandboxClientOptions, ResultBlobStore, RouterConfig, type RunAgenticOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, type SessionTraceBox, Settled, ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, Spend, SteerContext, type SteeringDecision, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, type SuperviseOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, SupervisedResult, Supervisor, type SupervisorAgentDeps, type SupervisorProfile, type SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, ToolLoopChat, ToolLoopCompactionOptions, type TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, breadthStrategy, buildSteerContext, builtinShapes, completionAuthorizes, contentAddress, createBudgetPool, createInMemoryRunContext, createInbox, createMcpEnvironment, createPushTraceSource, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultProfileRichnessThresholds, defaultSelectWinner, defaultToolDetectors, definePersona, defineStrategy, delegate, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, finalizeBestDelivered, flatWidenGate, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, jjWorkspace, leaderboard, localShell, loopCampaignDispatch, loopDispatch, loopUntil, mapSandboxEvent, naiveDriver, observe, openSandboxRun, pairwiseSignificance, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, reportLoopUsage, resolveSandboxClient, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, sumSandboxUsage, supervise, superviseSurface, supervisorAgent, supervisorInstructions, trajectoryReport, verify, watchTrace, widen, workerFromBackend };
+export { Agent, AgentRunSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, type ArtifactHandle, AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type DefinedLeaderboard, type DelegateOptions, type Deliverable, DeliverableSpec, type DriveHarness, 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, type ForkCapableBox, type GitWorkspaceOptions, 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, Iteration, type Leaderboard, type LeaderboardBenchScore, type LeaderboardBenchTask, type LeaderboardBenchmarkAdapter, type LeaderboardFlagSpec, type LeaderboardOptions, type LeaderboardRow, type LeaderboardRunContext, type LeaderboardScenario, type LeaderboardScore, type LeaderboardSpec, type LoopCampaignDispatchOptions, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, MakeWorkerAgent, type McpEndpoint, type McpEnvironmentOptions, MountRecorder, type NaiveDriverOptions, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, Outcome, OutputAdapter, type PairwiseOptions, type PairwiseVerdict, PanelSpec, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, type ResolveSandboxClientOptions, ResultBlobStore, RouterConfig, type RunAgenticOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, type SessionTraceBox, Settled, ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, Spend, SteerContext, type SteeringDecision, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, type SuperviseOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, SupervisedResult, Supervisor, type SupervisorAgentDeps, type SupervisorProfile, type SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, ToolLoopChat, ToolLoopCompactionOptions, type TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, breadthStrategy, buildSteerContext, builtinShapes, completionAuthorizes, contentAddress, createBudgetPool, createInMemoryRunContext, createInbox, createMcpEnvironment, createPushTraceSource, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultProfileRichnessThresholds, defaultSelectWinner, defaultToolDetectors, defineLeaderboard, definePersona, defineStrategy, delegate, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, finalizeBestDelivered, flatWidenGate, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, jjWorkspace, leaderboard, localShell, loopCampaignDispatch, loopDispatch, loopUntil, mapSandboxEvent, naiveDriver, observe, openSandboxRun, pairwiseSignificance, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, reportLoopUsage, resolveSandboxClient, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, sumSandboxUsage, supervise, superviseSurface, supervisorAgent, supervisorInstructions, trajectoryReport, verify, watchTrace, widen, workerFromBackend };