@tangle-network/agent-runtime 0.60.0 → 0.61.0

package/dist/worktree-fanout-CBULEoVe.d.ts

@@ -0,0 +1,1098 @@
+import { AgentProfile, BackendType } from '@tangle-network/sandbox';
+import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
+import { h as AgentSpec, E as ExecutorRegistry, B as Budget, A as Agent, i as SpawnJournal, g as ResultBlobStore, j as RootHandle, k as SupervisedResult, N as NodeId, l as Settled, m as Spend, S as Scope, n as Executor, G as GitRunner } from './delegates-CWMv_rKL.js';
+import { I as Iteration } from './types-Crxftafi.js';
+import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
+import { L as LocalHarness, r as runLocalHarness } from './local-harness-BE_h8szs.js';
+
+/**
+ * @experimental
+ *
+ * The personify layer — the "act like X" knob on top of the recursive keystone.
+ *
+ * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
+ * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
+ * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
+ * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
+ *
+ * This layer adds exactly that content seam without inventing a second engine:
+ *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
+ *    executor), a root `directive` (the goal framing handed to the chosen shape), a
+ *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
+ *    `definePersona` builds it; it is data, not behavior.
+ *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
+ *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
+ *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
+ *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
+ *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
+ *
+ * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
+ * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
+ * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
+ * world-model / memory field is additive (a new optional key), never a breaking change.
+ */
+
+/**
+ * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
+ * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
+ * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
+ * MUST name why); impls fail loud on it rather than emitting a vacuous block.
+ *
+ * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
+ * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
+ */
+type Outcome<D> = {
+    kind: 'done';
+    deliverable: D;
+} | {
+    kind: 'blocked';
+    blockers: string[];
+};
+/**
+ * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
+ * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
+ * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
+ *
+ * The framework never reads `directive`/`context` semantically; it threads them to the shape
+ * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
+ * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
+ * persona string is ever hardcoded in a shape or the engine.
+ *
+ * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
+ */
+interface Persona<D = unknown> {
+    /** Stable persona name — used as the trace/journal label root, never as content. */
+    readonly name: string;
+    /**
+     * The root agent's executor mapping (profile + harness + optional BYO executor). The
+     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
+     * are derived from / resolved against the same persona registry (see `ShapeContext`).
+     */
+    readonly root: AgentSpec;
+    /** The goal framing handed to the shape — the "what to achieve", not "how". */
+    readonly directive: string;
+    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
+     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
+    readonly context: PersonaContext;
+    /**
+     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
+     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
+     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
+     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
+     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
+     */
+    readonly executors: PersonaExecutors;
+    /**
+     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
+     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
+     */
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
+     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
+    readonly __deliverable?: D;
+}
+/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
+ *  own role/audience/constraints; the framework treats it as opaque content. */
+interface PersonaContext {
+    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
+    readonly role: string;
+    /** Optional freeform framing the persona's prompts/profiles consume. */
+    readonly notes?: string;
+    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
+    readonly [key: string]: unknown;
+}
+/**
+ * How a persona supplies executor resolution. Either a pre-built registry (factories already
+ * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
+ * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
+ */
+interface PersonaExecutors {
+    /** A registry whose factories already capture their seams. Highest precedence. */
+    readonly registry?: ExecutorRegistry;
+    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
+    readonly seams?: Readonly<Record<string, unknown>>;
+}
+/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
+ *  the executors-supplied invariant check and freeze the record. */
+interface DefinePersonaInput<D = unknown> {
+    readonly name: string;
+    readonly root: AgentSpec;
+    readonly directive: string;
+    readonly context: PersonaContext;
+    readonly executors: PersonaExecutors;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
+     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
+    readonly __deliverable?: D;
+}
+/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
+ *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
+type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
+/**
+ * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
+ * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
+ * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
+ * against them and fails closed, so an over-eager shape can never overspend.
+ */
+interface ShapeBudget {
+    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
+    readonly perChild: Budget;
+    /** Max children a fanout step may open in one round (the shape's structural width). */
+    readonly fanout: number;
+}
+/**
+ * The construction context a `LoopShape` factory receives. Carries the persona's resolved
+ * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
+ * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
+ * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
+ * registry directly — it asks the context, keeping resolution single-sourced.
+ */
+interface ShapeContext<D = unknown> {
+    readonly persona: Persona<D>;
+    readonly budget: ShapeBudget;
+    /**
+     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
+     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
+     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
+     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
+     */
+    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
+    /** Derive a child `AgentSpec` from the persona's root spec with an overridden profile —
+     *  the seam a shape uses to give a worker a narrower role/prompt than the root persona. */
+    childSpec(profile: AgentProfile, harness?: BackendType | null): AgentSpec;
+    /** The scope analyst (selector≠judge firewall) the combinator steers from. Absent ⇒ the
+     *  dormant default (empty findings → gates read deliverables/state only). */
+    readonly analyst?: ScopeAnalyst<D>;
+}
+/**
+ * A reusable act-body factory. Given the persona's content + seams (`ShapeContext`), it
+ * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
+ * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
+ * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
+ * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
+ */
+type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
+/**
+ * The open shape registry — the extension point that makes a new loop-shape ONE file + one
+ * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
+ * `succeeded` before `value`); `register` fails loud on a duplicate name.
+ */
+interface ShapeRegistry {
+    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+    resolve<Task, D>(name: string): {
+        succeeded: true;
+        value: LoopShape<Task, D>;
+    } | {
+        succeeded: false;
+        error: string;
+    };
+    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
+    names(): string[];
+}
+/**
+ * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
+ * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
+ * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
+ * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
+ *
+ * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
+ * default registry). The journal/blobs default to in-memory impls in the engine when omitted
+ * (durable FS impls are passed explicitly for a persisted run).
+ */
+interface RunPersonifiedOptions<Task, D> {
+    readonly persona: Persona<D>;
+    /** A resolved shape factory OR a registered shape name. */
+    readonly shape: LoopShape<Task, D> | string;
+    readonly task: Task;
+    readonly budget: Budget;
+    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
+    readonly shapeBudget?: Partial<ShapeBudget>;
+    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
+    readonly runId?: string;
+    readonly journal?: SpawnJournal;
+    readonly blobs?: ResultBlobStore;
+    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
+    readonly maxDepth?: number;
+    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
+    readonly maxRestarts?: number;
+    readonly withinMs?: number;
+    /** A live root handle to attach (view/signal/abort) before the run starts. */
+    readonly handle?: RootHandle<Outcome<D>>;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal;
+    /** Optional scope analyst threaded into the shape's ShapeContext so loopUntil/widen steer
+     *  on trace-derived findings instead of the dormant empty default. */
+    readonly analyst?: ScopeAnalyst<D>;
+    /**
+     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
+     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
+     * trace export). Absent ⇒ no stream (the run is silent, as today).
+     */
+    readonly hooks?: RuntimeHooks;
+}
+/** The composed run signature. */
+type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
+
+/**
+ * @experimental
+ *
+ * The RSI-wave type surface — the FROZEN contracts the wave's Core + Compose build to.
+ *
+ * The keystone (`../supervise/`) is pure execution structure: a recursive `Agent` atom in a
+ * budget-conserving `Scope`, run to a typed `SupervisedResult` by a `Supervisor`. The persona
+ * layer (`./types`, `./persona`) adds the "act like X" content seam (`Persona` = `AgentSpec` +
+ * `directive` + `context`, `LoopShape = (ctx) => Agent`, `Outcome<D>`). This module freezes the
+ * remaining four wave seams ON TOP of those — and nothing more:
+ *
+ *  1. GENERIC COMBINATORS — the content-free act-library. Five composable shapes
+ *     (`pipeline`/`fanout`/`loopUntil`/`panel`/`verify`) plus the streaming widener (G5). Each
+ *     is a `CombinatorShape` (a `LoopShape` whose `Agent.act` runs the combinator over `Scope`),
+ *     so a combinator IS just a `LoopShape` — no new engine type. The SHAPE is here; the DOMAIN
+ *     (model, prompt, role) stays on the `Persona`. There is no "research" or "code" combinator:
+ *     a research sweep is `fanout` under a research persona; a build is `pipeline` under a coder.
+ *  2. ANALYST-ON-SCOPE (G1, a PORT) — `ScopeAnalyst` carries the round-synchronous driver's
+ *     analyze→findings→steer wire (dynamic.ts) across to the reactive `Scope`, behind
+ *     the same trace-derived firewall (`assertTraceDerivedFindings` semantics): a reactive
+ *     combinator steers from trace FINDINGS, never a child's raw `verdict`.
+ *  3. CROSS-RUN CORPUS (G2) — `Corpus` is the DURABLE accreted-fact store, DISTINCT from the
+ *     per-run `SpawnJournal`/`ResultBlobStore`. `renderCorpusToInstructions` is the read-back:
+ *     it projects accreted facts into `AgentProfile.prompt.instructions` / `resources.instructions`
+ *     for the next run's persona (the learning-flywheel READ side).
+ *  4. TRAJECTORY TRACE + COST LEDGER — `trajectoryReport(journal, blobs)` reconstructs the whole
+ *     spawn tree with per-node + rolled-up `Spend`; `equalKOnCost` compares arms on conserved
+ *     COST (tokens/usd), NOT raw iteration count — closing the leaf-fanout confound.
+ *
+ * Layering: imports ONLY keystone runtime types (`../supervise/types`), persona types
+ * (`./types`), the substrate `AnalystFinding`/`AgentProfile`, and the durable-store interfaces.
+ * Pure types/interfaces — this module typechecks standalone, owns no impl, invents no engine.
+ */
+
+/**
+ * A combinator is just a `LoopShape`: a factory `(ShapeContext) => Agent` whose `Agent.act`
+ * runs the combinator's structure over the `Scope` (spawn children, drain `next()`, select via
+ * the single-sourced `settledToIteration`+`defaultSelectWinner`, synthesize an `Outcome<D>`).
+ * Aliased — NOT a new type — so a combinator stays a first-class shape the persona layer's
+ * `runPersonified`/`ShapeRegistry` resolve with zero new machinery. The SHAPE is content-free;
+ * the persona carries the domain.
+ */
+type CombinatorShape<Task, D> = LoopShape<Task, D>;
+/**
+ * `pipeline(stages)` — sequential composition: each stage's `Outcome.deliverable` feeds the next
+ * stage's task (via `feed`). The first `blocked` stage short-circuits the whole pipeline (its
+ * blockers ARE the pipeline's blockers — never coerced past a failed stage). The terminal
+ * stage's `done` deliverable is the pipeline's deliverable. Spawns one child per stage in order;
+ * a stage that the conserved pool cannot admit is a concrete blocker.
+ *
+ * No domain: "code build test" is `pipeline([plan, implement, integrate])` under a coder persona,
+ * not a named shape. A stage names only its label + how to derive its task from the prior output.
+ */
+interface PipelineStage<Task, StepIn, StepOut> {
+    /** Trace/journal label for this stage's spawned child. */
+    readonly label: string;
+    /** Derive this stage's task from the prior stage's deliverable (or the root task for stage 0).
+     *  Pure projection — the framework never interprets the result; the resolved leaf does. */
+    feed(prior: StepIn, ctx: ShapeContext<unknown>, rootTask: Task): unknown;
+    /** Read this stage's settled child output into the typed `StepOut` the next stage feeds on.
+     *  Fail loud (return a `blocked`) when the child produced nothing usable for the next stage. */
+    collect(settled: Settled<Outcome<StepOut>>): Outcome<StepOut>;
+}
+/** `pipeline(stages)` — build the sequential combinator from an ordered stage list. The first
+ *  stage's `StepIn` is the root `Task`; the last stage's `StepOut` is the deliverable `D`. */
+type Pipeline = <Task, D>(stages: ReadonlyArray<PipelineStage<Task, unknown, unknown>>) => CombinatorShape<Task, D>;
+/**
+ * `fanout(items, { synthesize? })` — N children spawned in one round (one per item, bounded by
+ * the conserved pool's fail-closed admission), drained via `scope.next()`, then optionally a
+ * single SYNTHESIS child over the gathered results. Without `synthesize`, the combinator returns
+ * the best-valid child via the single-sourced selector (selector≠judge). A round that admitted
+ * zero children, or whose synthesis child could not be admitted, is a concrete blocker.
+ *
+ * No domain: a "research sweep over angles" is `fanout(angles, { synthesize: cite })` under a
+ * research persona; a "fanout-vote" is `fanout(copies)` with the default selector. The item list
+ * + the synthesis posture are the SHAPE's args; the prompt that turns an item into work is the
+ * persona's.
+ */
+interface FanoutOptions<Item, D> {
+    /** One child task per item: `item` + the index discriminator. The persona's directive/context
+     *  is threaded in by the combinator; this only supplies the per-item discriminator. */
+    itemTask(item: Item, index: number, ctx: ShapeContext<D>): unknown;
+    /** Per-item child label (defaults to `item:<index>` in the impl). */
+    label?(item: Item, index: number): string;
+    /**
+     * Optional per-item `AgentSpec` override. When set, each item's child is spawned against the
+     * returned spec instead of `persona.root` — the seam a heterogeneous fanout uses to give each
+     * item a DISTINCT executor (e.g. N authored harness profiles, each on its own worktree-CLI
+     * leaf). Absent ⇒ every item runs against the persona's root spec (the homogeneous default).
+     */
+    itemSpec?(item: Item, index: number, ctx: ShapeContext<D>): AgentSpec;
+    /**
+     * Optional synthesis over the gathered child results: when present, the combinator spawns ONE
+     * synthesis child whose task is built from the drained settlements, and its `done` output is
+     * the deliverable. When absent, the deliverable is the best-valid child via `defaultSelectWinner`.
+     * The synthesis child is a SEPARATE keystone agent (not a re-rank behind the driver).
+     */
+    synthesize?: FanoutSynthesis<D>;
+    /**
+     * Winner-selection strategy among the gathered `done` children when there is no `synthesize`.
+     * Receives the SAME `Iteration[]` the default selector reads (each child's output is its
+     * `Outcome<D>`), so a strategy is a thin re-sort (smallest-diff, highest-readiness, first-valid
+     * …) over the candidates — NEVER a re-rank behind a judge. Default = `defaultSelectWinner`
+     * semantics (best-valid-score, ties→earliest). Mutually exclusive with `synthesize` (a
+     * synthesis child IS the selection); supplying both is a config error.
+     */
+    selectWinner?: FanoutWinnerSelector<D>;
+}
+/** A winner-selection strategy: argmax/sort over the gathered child iterations (each output is the
+ *  child's `Outcome<D>`), returning the chosen iteration or `undefined` when none qualifies. */
+type FanoutWinnerSelector<D> = (iterations: Iteration<unknown, Outcome<D>>[]) => {
+    readonly output?: Outcome<D> | undefined;
+} | undefined;
+/** Built-in valid-only winner strategies for `selectValidWinner` (selector≠judge): best gated-valid
+ *  score, the smallest delivered artifact (via a `sizeOf` extractor), or the earliest valid. */
+type WinnerStrategy = 'highest-score' | 'smallest-artifact' | 'first-valid';
+/** How a fanout's synthesis child is built + read. `synthesisTask` projects the drained child
+ *  settlements into the synthesis child's task; `collect` reads its settled output into the
+ *  deliverable `Outcome<D>`. */
+interface FanoutSynthesis<D> {
+    synthesisTask(gathered: ReadonlyArray<Settled<Outcome<D>>>, ctx: ShapeContext<D>): unknown;
+    collect(settled: Settled<Outcome<D>>): Outcome<D>;
+}
+/** `fanout(items, opts)` — build the fanout combinator over a static item list. */
+type Fanout = <Task, Item, D>(items: ReadonlyArray<Item>, opts: FanoutOptions<Item, D>) => CombinatorShape<Task, D>;
+/**
+ * `loopUntil({ until, step })` — iterative deepening inside the conserved pool: spawn one `step`
+ * child per round, ask `until` whether the accumulated state satisfies the goal, and stop when it
+ * does OR when the pool can no longer admit a step (budget IS the loop bound — no unbounded
+ * while). The deployable, non-oracle stop: `until` is the satisfiability gate, read from trace
+ * findings + accumulated deliverables, never a fresh raw verdict the loop minted to stop itself.
+ *
+ * No domain: "refine until tests pass" is `loopUntil` with a coder persona + a `step` that edits
+ * and an `until` that reads the test-finding; the combinator owns only the round/stop wiring.
+ */
+interface LoopUntilSpec<Task, State, D> {
+    /** Build the next step child's task from the root task + the state accumulated so far. */
+    step(rootTask: Task, state: LoopUntilState<State>, ctx: ShapeContext<D>): unknown;
+    /** Fold one settled step into the accumulated state (the loop's running deliverable candidate). */
+    fold(prior: LoopUntilState<State>, settled: Settled<Outcome<D>>): LoopUntilState<State>;
+    /**
+     * The satisfiability gate: given the accumulated state + the round's trace findings, has the
+     * goal been reached? Returns the terminal deliverable when satisfied, or `null` to keep going.
+     * Reads `findings` (trace-derived), NOT a raw verdict score — the deployable-stop discipline.
+     */
+    until(state: LoopUntilState<State>, findings: ReadonlyArray<AnalystFinding>): Outcome<D> | null;
+    /** Per-round step label (defaults to `step:<round>` in the impl). */
+    label?(round: number): string;
+}
+/** The accumulated state `loopUntil` threads across rounds — the running candidate + the round
+ *  index, so `step`/`fold`/`until` are pure functions of it (replay-safe, no wall-clock). */
+interface LoopUntilState<State> {
+    readonly round: number;
+    readonly value: State;
+}
+/** `loopUntil(spec)` — build the iterative-deepening combinator. `seed` is the initial state. */
+type LoopUntil = <Task, State, D>(seed: State, spec: LoopUntilSpec<Task, State, D>) => CombinatorShape<Task, D>;
+/**
+ * `panel(judges)` — M judges over ONE artifact, merged WRITE-ONLY (selector≠judge taken to its
+ * limit). The combinator spawns the M judge children over the same input artifact, drains their
+ * settlements, and MERGES their findings into a panel verdict via `merge` — a pure WRITE-ONLY
+ * fold (a judge's output is never fed back to steer another judge, and the merge never re-ranks
+ * the children behind the driver). The merged verdict gates the deliverable.
+ *
+ * No domain: a "code review panel" and an "essay rubric panel" are the same `panel` shape under
+ * different personas; the rubric lives in each judge persona's profile, not the combinator.
+ */
+interface PanelSpec<Artifact, D> {
+    /** The M judge child specs: each is a persona-derived child (a narrower judge profile). The
+     *  combinator spawns one child per entry over the SAME `artifact` and never lets one judge's
+     *  output reach another's task (write-only). */
+    readonly judges: ReadonlyArray<PanelJudge>;
+    /** Build one judge child's task from the shared artifact under review + the judge descriptor. */
+    judgeTask(artifact: Artifact, judge: PanelJudge, ctx: ShapeContext<D>): unknown;
+    /**
+     * Write-only merge: fold the M settled judge verdicts into the panel's terminal `Outcome<D>`.
+     * Pure over the drained settlements — it MUST NOT spawn, re-judge, or feed one verdict into
+     * another. A panel that reached no quorum is a concrete blocker (fail loud, never a vacuous done).
+     */
+    merge(verdicts: ReadonlyArray<PanelVerdict>, artifact: Artifact): Outcome<D>;
+}
+/** One judge in a panel — a labeled persona-derived judge child. Content (the rubric) lives in
+ *  the judge's profile; this carries only the label + the optional weight the merge may read. */
+interface PanelJudge {
+    readonly label: string;
+    /** Optional merge weight (a write-only hint the `merge` fold may use; default-equal in the impl). */
+    readonly weight?: number;
+}
+/** One judge child's settled verdict, surfaced to the write-only `merge`. `down` judges carry no
+ *  verdict (excluded from the merge `n`, like an infra-errored cell). */
+interface PanelVerdict {
+    readonly judge: PanelJudge;
+    readonly verdict?: DefaultVerdict;
+    /** The judge child's raw output — what it was asked to assess, for a merge that quotes it. */
+    readonly output?: unknown;
+    /** True when the judge child went `down` (no usable verdict — kept out of the merge denominator). */
+    readonly down: boolean;
+}
+/** `panel(spec)` — build the M-judge write-only-merge combinator. */
+type Panel = <Task, Artifact, D>(spec: PanelSpec<Artifact, D>) => CombinatorShape<Task, D>;
+/**
+ * `verify({ implement, verifier })` — the 2-node sequential gate: an IMPLEMENT child produces a
+ * candidate, then a SEPARATE VERIFIER child's verdict GATES shippability. A `valid` verifier
+ * verdict ships the implement deliverable; any other outcome (implement down, verifier down,
+ * invalid verdict) becomes a concrete blocker carrying the failure verbatim — never a coerced
+ * "done". The verifier is a distinct keystone agent (selector≠judge: the implement child does
+ * not grade itself).
+ *
+ * No domain: "write code then run the test gate" and "draft then fact-check" are the same `verify`
+ * shape under different personas; the gate rubric is the verifier persona's, not the combinator's.
+ */
+interface VerifySpec<Task, Candidate, D> {
+    /** Build the implement child's task from the root task. */
+    implement(rootTask: Task, ctx: ShapeContext<D>): unknown;
+    /** Build the verifier child's task from the implement child's settled candidate. */
+    verifier(candidate: Settled<Outcome<Candidate>>, ctx: ShapeContext<D>): unknown;
+    /** Project the gated (verifier-`valid`) candidate into the terminal deliverable. */
+    collect(candidate: Settled<Outcome<Candidate>>, verdict: DefaultVerdict): Outcome<D>;
+    /** Implement / verifier child labels (default `implement` / `verify` in the impl). */
+    readonly implementLabel?: string;
+    readonly verifierLabel?: string;
+}
+/** `verify(spec)` — build the 2-node implement→verifier-gate combinator. */
+type Verify = <Task, Candidate, D>(spec: VerifySpec<Task, Candidate, D>) => CombinatorShape<Task, D>;
+/**
+ * `widen({ gate })` (G5) — the STREAMING spawn-on-completion driver. Unlike the static-fanout
+ * combinators above, the widener REACTS to each `scope.next()`: as each child settles it consults
+ * the `WidenGate` and, when a lineage is `promising`, widens by AT MOST ONE child toward it under
+ * the remaining conserved pool. Defaults to FLAT (the gate never widens) so a gate run stays
+ * non-widening and the R2 selector≠judge collision is dormant. `promising` is derived from the
+ * round's analyst FINDINGS (via `ScopeAnalyst`, §2), NOT a child's raw `verdict` — the firewall.
+ *
+ * This is the progressive-widening (MCTS-PW) combinator: the one shape whose breadth is decided
+ * at runtime from the diagnosis, not fixed at spawn. It is the mechanism the diverse-strategy-vs-
+ * blind GATE is run with — kept FLAT by default until that gate returns positive (don't build
+ * mechanism ahead of the gate).
+ */
+interface WidenSpec<Seed, D> {
+    /** The initial children to spawn before any widening — the seed lineages the gate widens from.
+     *  One child task per seed; bounded by the conserved pool's fail-closed admission. */
+    readonly seeds: ReadonlyArray<Seed>;
+    seedTask(seed: Seed, index: number, ctx: ShapeContext<D>): unknown;
+    /**
+     * The progressive-widening gate. Consulted on EVERY settled child with the round's
+     * trace-derived `findings`; returns a widen decision (spawn one more toward a lineage) or a
+     * stop. DEFAULTS to flat via `flatWidenGate` — never widens, so the firewall stays dormant.
+     */
+    readonly gate: ScopeWidenGate<D>;
+    /** Build the widened child's task from the lineage the gate chose to extend. */
+    widenTask(toward: WidenLineage<D>, ctx: ShapeContext<D>): unknown;
+    /** Synthesize the terminal deliverable from every settled lineage (selector≠judge: the
+     *  single-sourced selector over the gathered children, never a re-judge). */
+    synthesize(gathered: ReadonlyArray<Settled<Outcome<D>>>, ctx: ShapeContext<D>): Outcome<D>;
+}
+/**
+ * The runtime widening gate (the reactive analogue of the keystone's `WidenGate`, lifted to read
+ * trace FINDINGS instead of a raw verdict). `decide` is consulted per settled child; it MUST
+ * derive `promising` from `findings`, never from `settled.verdict`, unless `judgeExempt` is
+ * explicitly argued (the documented off-by-default escape hatch). Flat default never widens.
+ */
+interface ScopeWidenGate<D> {
+    decide(settled: Settled<Outcome<D>>, findings: ReadonlyArray<AnalystFinding>, budget: Scope<Outcome<D>>['budget']): WidenDecision<D>;
+    /** When true, `decide` may read `settled.verdict` directly — collides with the steer firewall,
+     *  so it must be argued per cell, never defaulted on (mirrors the keystone `WidenGate`). */
+    readonly judgeExempt?: boolean;
+}
+/** A widening decision: extend one lineage by one child, or stop widening. `flatWidenGate`
+ *  always returns `{ kind: 'stop' }`. */
+type WidenDecision<D> = {
+    kind: 'widen';
+    toward: WidenLineage<D>;
+} | {
+    kind: 'stop';
+    rationale?: string;
+};
+/** A lineage the gate may widen toward — the settled child that looked promising + the findings
+ *  that justified it (the trace-derived provenance the firewall requires). */
+interface WidenLineage<D> {
+    readonly settled: Extract<Settled<Outcome<D>>, {
+        kind: 'done';
+    }>;
+    readonly findings: ReadonlyArray<AnalystFinding>;
+}
+/** `widen(spec)` — build the streaming progressive-widening combinator. */
+type Widen = <Task, Seed, D>(spec: WidenSpec<Seed, D>) => CombinatorShape<Task, D>;
+/** The flat default `ScopeWidenGate` factory contract — never widens, keeping the R2 firewall
+ *  conflict dormant. Exported so a gate run can pass it explicitly and a test can assert the
+ *  default is flat. */
+type FlatWidenGate = <D>() => ScopeWidenGate<D>;
+/**
+ * The reactive analyst seam — the PORT of the round-synchronous driver's `analyze` hook
+ * (dynamic.ts) onto the reactive `Scope`. The old driver wired the analyst at round
+ * boundaries (`plan` ran the analyst over `history` BEFORE the planner); the reactive `Scope` has
+ * no rounds, so this carries the wire across: a combinator's `act` asks the `ScopeAnalyst` to turn
+ * the settled children SO FAR into `AnalystFinding[]`, and steers from THOSE findings.
+ *
+ * The firewall is preserved (selector≠judge): `analyze` runs the trace-derived analyst and the
+ * impl asserts `assertTraceDerivedFindings` semantics — a finding citing judge/verdict/score
+ * `metric` evidence aborts the round. The steer decision reads `findings`, NEVER the children's
+ * raw `verdict`. Fail loud — a throwing or non-array analyst aborts (no silent empty findings).
+ */
+interface ScopeAnalyst<D> {
+    /**
+     * Turn the children settled so far into trace-derived findings. `settledSoFar` is the cursor-
+     * ordered settlement list a combinator has drained (the reactive analogue of the old driver's
+     * `history`). The impl runs the analyst, then enforces the trace-derived firewall before
+     * returning — a judge-derived finding is rejected, not filtered.
+     */
+    analyze(input: ScopeAnalyzeInput<D>): Promise<ReadonlyArray<AnalystFinding>>;
+}
+/** Input to a `ScopeAnalyst.analyze` — the root task framing + the children settled so far. */
+interface ScopeAnalyzeInput<D> {
+    /** Opaque root-task framing (whatever the combinator was invoked with). */
+    readonly task: unknown;
+    /** The children this combinator has drained off `scope.next()`, in cursor order. */
+    readonly settledSoFar: ReadonlyArray<Settled<Outcome<D>>>;
+    /** This combinator's scope id (the trace-correlation root for the analyst). */
+    readonly nodeId: NodeId;
+}
+/**
+ * How a combinator's `act` consumes findings to steer — the SINGLE firewalled steer surface a
+ * reactive combinator reads. `loopUntil.until`, `widen` gate, and any future steer all funnel
+ * through a `SteerContext` so the firewall is enforced in one place: `findings` is trace-derived
+ * (the analyst already asserted it), and a combinator MUST NOT reach back to `settled.verdict`
+ * for the steer decision. `lastValidScore` is provided for OBSERVABILITY only (rendering/traces),
+ * explicitly NOT for steering — reading it to steer is the coupling the architecture forbids.
+ */
+interface SteerContext<D> {
+    readonly findings: ReadonlyArray<AnalystFinding>;
+    readonly settledSoFar: ReadonlyArray<Settled<Outcome<D>>>;
+    /** Observability-only: the best valid score seen so far. Rendering/trace use ONLY — steering
+     *  off this re-introduces selector=judge. Marked so a reviewer catches a misuse. */
+    readonly lastValidScore?: number;
+}
+/**
+ * The firewall assertion contract, re-stated for the reactive seam (PORT of
+ * `assertTraceDerivedFindings`). A PROVENANCE check, not a content check: span/event/artifact/
+ * finding refs and empty-evidence findings pass; only a `metric` ref whose uri is a
+ * judge/verdict/score scheme is rejected. Fail loud — a tainted finding aborts. The impl lives in
+ * `analyst.ts`; this type pins its signature so callers depend on the contract, not the impl.
+ */
+type AssertTraceDerivedFindings = (findings: ReadonlyArray<AnalystFinding>) => void;
+/**
+ * One accreted fact in the cross-run corpus — the learning-flywheel's durable unit. DISTINCT from
+ * a `SpawnEvent` (a per-run decision record): a `CorpusRecord` is a fact a run LEARNED that a
+ * FUTURE run should read back (the world-model for story 5). It is content the next persona reads,
+ * not a replay input. Tagged + scored so `query`/`renderCorpusToInstructions` can project the
+ * relevant, high-confidence subset.
+ */
+interface CorpusRecord {
+    readonly schemaVersion: '1.0.0';
+    /** Stable id over identity-defining fields (claim + tags) so a re-learned fact dedups. */
+    readonly id: string;
+    /** The run that produced this fact (the journal `runId`/`root`) — provenance back to the trace. */
+    readonly runId: NodeId;
+    readonly producedAt: string;
+    /** Coarse classification the query/render filters on (free-form, mirrors `AnalystFinding.area`). */
+    readonly area: string;
+    /** The accreted fact — the instruction-shaped statement the next run reads back. */
+    readonly claim: string;
+    /** Optional supporting detail the renderer may include under the claim. */
+    readonly rationale?: string;
+    /** Free-form tags for `query` filtering (domain, persona, surface). */
+    readonly tags: ReadonlyArray<string>;
+    /** 0..1 — the producing run's confidence in this fact (the render threshold reads it). */
+    readonly confidence: number;
+    /** Optional provenance back into the run that learned it (a finding id / outRef / span). */
+    readonly evidence?: ReadonlyArray<{
+        readonly kind: string;
+        readonly uri: string;
+    }>;
+}
+/** A corpus query filter — every field is an AND-narrowing; an omitted field does not constrain. */
+interface CorpusFilter {
+    readonly area?: string;
+    /** Match records carrying ALL of these tags. */
+    readonly tags?: ReadonlyArray<string>;
+    /** Minimum confidence a record must clear to be returned (the render gate). */
+    readonly minConfidence?: number;
+    /** Only records from this run (rare — usually a cross-run read). */
+    readonly runId?: NodeId;
+    /** Cap the result count (most-confident first in the impl). */
+    readonly limit?: number;
+}
+/**
+ * The durable cross-run corpus — the learning-flywheel store. DISTINCT from `SpawnJournal`
+ * (per-run decisions, replay) and `ResultBlobStore` (per-run payloads): `Corpus` holds accreted
+ * FACTS across runs that the next run reads back. `InMemoryCorpus` + `FileCorpus` (JSONL) impls
+ * live in `corpus.ts` and MAY share a storage spine with the JSONL journal, but the INTERFACE is
+ * separate so a consumer never confuses a replay record with a learned fact.
+ *
+ * Fail-loud, typed-outcome boundary: `append` is idempotent on an identical record (same `id` +
+ * `claim`); a conflicting re-append under the same `id` is a typed error, never a silent overwrite.
+ */
+interface Corpus {
+    /** Append one accreted fact. Idempotent on an identical record; returns a typed outcome —
+     *  inspect `succeeded` before treating it as durable (no silent write-through on conflict). */
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    /** Query accreted facts by filter — most-confident first. Returns the matching records (an
+     *  empty array when none match is a valid result, NOT an error). */
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+}
+/**
+ * Project accreted corpus facts into an `AgentProfile`'s instruction seams — the learning-flywheel
+ * READ side. Reads the corpus through `filter`, renders the matching facts into instruction lines,
+ * and returns a NEW profile with them merged into `prompt.instructions` (the append-line seam) so
+ * the next run's persona reads the accreted world-model. Pure projection over the queried records;
+ * never mutates the input profile (returns a fresh one). The impl lives in `corpus.ts`.
+ *
+ * `resources.instructions` is `string | AgentProfileResourceRef`; `prompt.instructions` is
+ * `string[]`. The render targets `prompt.instructions` (additive lines) by default; a caller that
+ * wants the single-blob `resources.instructions` form passes `target: 'resources'`.
+ */
+interface RenderCorpusToInstructionsOptions {
+    readonly corpus: Corpus;
+    readonly filter: CorpusFilter;
+    /** The profile to project the facts into. The result is a fresh profile — the input is unchanged. */
+    readonly profile: AgentProfile;
+    /** Where the rendered facts land: appended to `prompt.instructions[]` (default) or folded into
+     *  the single-blob `resources.instructions` string. */
+    readonly target?: 'prompt' | 'resources';
+    /** Optional cap on rendered lines (most-confident first), independent of the query `limit`. */
+    readonly maxLines?: number;
+}
+/** `renderCorpusToInstructions(opts)` — the flywheel read-back projection. Async (queries the
+ *  durable corpus); returns a fresh `AgentProfile` with the accreted facts merged in. */
+type RenderCorpusToInstructions = (opts: RenderCorpusToInstructionsOptions) => Promise<AgentProfile>;
+/**
+ * One node in the reconstructed trajectory tree — a driver OR a leaf, with its OWN spend and the
+ * spend ROLLED UP over its subtree. Reconstructed from the `SpawnJournal` (structure + per-node
+ * `Spend`) + the `ResultBlobStore` (the `out` artifact, rehydrated by `outRef`). The realized tree
+ * shape: `parent`/`children` are the actual spawn edges the run took, not a planned topology.
+ */
+interface TrajectoryNode {
+    readonly id: NodeId;
+    readonly parent?: NodeId;
+    readonly children: ReadonlyArray<NodeId>;
+    readonly label: string;
+    readonly runtime: string;
+    /** Terminal status the journal recorded for this node. */
+    readonly status: 'done' | 'failed' | 'cancelled' | 'pending';
+    /** This node's OWN conserved spend (from its `settled` event). */
+    readonly ownSpend: Spend;
+    /** This node's spend PLUS every descendant's — the rolled-up subtree cost. The cost a parent
+     *  "really" consumed inclusive of its children's fanout (the equal-k-on-cost basis). */
+    readonly rolledUpSpend: Spend;
+    /** The node's verdict, when its settlement carried one (observability — NOT a steer input). */
+    readonly verdict?: DefaultVerdict;
+    /** The rehydrated output artifact, when `withOutputs` was requested + the blob resolved. */
+    readonly output?: unknown;
+    readonly outRef?: string;
+}
+/** The whole reconstructed trajectory — the realized tree + its root-rolled-up total. The
+ *  per-node + rolled-up `Spend` is the evidence both the trace viewer and `equalKOnCost` read. */
+interface TrajectoryReport {
+    readonly root: NodeId;
+    /** Every node, in cursor/spawn order — the realized tree (`parent`/`children` are the real edges). */
+    readonly nodes: ReadonlyArray<TrajectoryNode>;
+    /** The root's rolled-up spend — the whole run's conserved total (tokens + usd + iterations + ms). */
+    readonly total: Spend;
+    /** Count of nodes by terminal status — a quick "how did the tree end" readout. */
+    readonly statusCounts: Readonly<Record<TrajectoryNode['status'], number>>;
+}
+/**
+ * `trajectoryReport(journal, blobs, root, { withOutputs? })` — reconstruct the whole tree 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 or
+ * a `done` node whose blob the store cannot rehydrate (a silent gap would mis-cost the tree). The
+ * impl lives in `trajectory.ts`.
+ */
+interface TrajectoryReportOptions {
+    /** Rehydrate each `done` node's `output` from the blob store. Off by default (cost-only report). */
+    readonly withOutputs?: boolean;
+}
+/** `trajectoryReport(...)` — the tree+cost reconstructor. Async (reads journal + optionally blobs). */
+type TrajectoryReportFn = (journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId, options?: TrajectoryReportOptions) => Promise<TrajectoryReport>;
+/**
+ * One arm of an equal-k comparison — a labeled trajectory (a `TrajectoryReport` is one arm's whole
+ * run). The arm's conserved COST is `report.total` (tokens + usd), which the sandbox executor
+ * already reports INCLUSIVE of a leaf's internal sub-agent fanout — so comparing arms on this cost
+ * (not raw `iterations`) closes the leaf-fanout confound: a treatment arm whose leaf fanned out
+ * internally is charged for that fanout in `total.tokens`/`total.usd`, not hidden behind one
+ * iteration count.
+ */
+interface EqualKArm {
+    readonly label: string;
+    readonly report: TrajectoryReport;
+}
+/**
+ * The equal-k-on-cost verdict: whether every arm spent within `tolerance` of the others on the
+ * CONSERVED cost channels (tokens + usd), so a downstream metric comparison is "at equal k". Per-
+ * arm cost is surfaced so a caller can see HOW close. `withinTolerance: false` means the arms are
+ * NOT comparable at equal compute — a confound to report, not a result to publish.
+ */
+interface EqualKVerdict {
+    readonly withinTolerance: boolean;
+    /** Per-arm conserved cost (the basis: tokens total + usd). */
+    readonly arms: ReadonlyArray<{
+        readonly label: string;
+        readonly tokens: number;
+        readonly usd: number;
+        readonly iterations: number;
+    }>;
+    /** The realized spread on each channel (max − min across arms), for the report. */
+    readonly spread: {
+        readonly tokens: number;
+        readonly usd: number;
+    };
+    /** The fractional tolerance the check used (spread / median ≤ tolerance per channel). */
+    readonly tolerance: number;
+}
+/**
+ * `equalKOnCost(arms, { tolerance? })` — assert arms are comparable at EQUAL conserved COST
+ * (tokens + usd), NOT raw iteration count. The conserved-pool guarantees `Σk` equal by
+ * construction WITHIN one supervised run; this checks it ACROSS arms (separate runs) where the
+ * pool cannot, so a cross-arm gate comparison can prove equal compute before claiming a win. The
+ * impl lives in `trajectory.ts`. Pure over the reports — no I/O.
+ */
+interface EqualKOnCostOptions {
+    /** Max fractional spread (spread/median) per channel for arms to count as equal-k. Default in
+     *  the impl (e.g. 0.05). A tighter tolerance = a stricter equal-compute claim. */
+    readonly tolerance?: number;
+}
+/** `equalKOnCost(arms, opts)` — the cross-arm equal-compute check on conserved cost. */
+type EqualKOnCost = (arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions) => EqualKVerdict;
+
+/**
+ * @experimental
+ *
+ * The completion-oracle: **settled ⟺ DELIVERED.**
+ *
+ * Foreman's one hard lesson (0/18 self-improvement deliverables) — "done" must mean a check
+ * PASSED, not the agent's say-so. `gateOnDeliverable` wraps an `Executor` so its settlement
+ * is `valid` ONLY when the deliverable check passes. The child still RUNS and settles (its
+ * spend is conserved into the pool either way), but a child that ran WITHOUT delivering
+ * settles `valid:false` — so a keep-best driver never counts it as done, and a gate never
+ * inflates with self-judged wins.
+ *
+ * Dual-purpose by construction:
+ *  - product: the agent fleet only advances on real, checked deliverables.
+ *  - proof: the gate's `valid` is the honest settle — equal-k comparisons can't be gamed by an
+ *    arm that "ran" without producing the artifact.
+ *
+ * The check is a DEPLOYABLE oracle — a test command, a state verifier, the commit0 judge —
+ * read off the child's output, never the model judging itself. A throwing check is
+ * fail-closed (not delivered), never a crash.
+ */
+
+interface DeliverableSpec<Out = unknown> {
+    /** The deployable check that decides DELIVERED. `settled.valid ⟺ this resolves true`. */
+    check: (out: Out) => boolean | Promise<boolean>;
+    /** What the spawn was supposed to produce — surfaced in traces/reports. */
+    describe?: string;
+}
+/**
+ * Wrap an `Executor` so its settlement `valid` reflects the deliverable check, not the
+ * inner verdict. Handles both `execute` shapes (one-shot `Promise<ExecutorResult>` and
+ * streaming `AsyncIterable<UsageEvent>` + `resultArtifact()`); the check runs once the inner
+ * executor has produced its output. The inner `score` is preserved; only `valid` is gated.
+ */
+declare function gateOnDeliverable<Out>(inner: Executor<Out>, deliverable: DeliverableSpec<Out>): Executor<Out>;
+
+/**
+ * @experimental
+ *
+ * The mechanical patch gate — the SINGLE source of the no-op / always-on secret-path floor /
+ * forbidden-path / diff-size / test / typecheck checks over a captured diff. No I/O: it scores a
+ * patch plus its already-derived test/typecheck PASS signals. The generic worktree-CLI deliverable
+ * (`patchDelivered`, which runs the commands itself) calls this, so the gate logic never forks.
+ *
+ * The always-on safety floors (no-op rejection + secret-path) are also exported standalone
+ * (`isNonEmptyPatch` / `touchesSecretPath`) for reuse outside the full scorer.
+ */
+
+/** @experimental The patch + its derived PASS signals the mechanical gate decides on. */
+interface CoderCheckInput {
+    /** The unified diff produced by the run. */
+    patch: string;
+    /** Did `testCmd` exit clean? */
+    testsPassed: boolean;
+    /** Did `typecheckCmd` exit clean? */
+    typecheckPassed: boolean;
+}
+/** @experimental The per-task constraints the mechanical gate enforces. */
+interface CoderCheckConstraints {
+    /** Default 400. Hard cap; gate fails when exceeded. */
+    maxDiffLines?: number;
+    /** Literal path prefixes the patch must not touch. */
+    forbiddenPaths?: string[];
+}
+/** The unified-diff paths the patch touches — the `+++`/`---` headers, de-`a/`/`b/`-prefixed,
+ *  with `/dev/null` (a delete's other side) dropped. */
+declare function touchedPathsFromPatch(patch: string): string[];
+/** Count the added/removed content lines in a unified diff (excludes the `+++`/`---` headers). */
+declare function countDiffLines(patch: string): number;
+/** True when the patch actually changes something — at least one touched path AND non-blank body.
+ *  An empty patch can trivially "pass" tests/typecheck (nothing changed) yet does no work. */
+declare function isNonEmptyPatch(patch: string): boolean;
+/** The credential-shaped paths the patch touches (always-on floor, independent of `forbiddenPaths`). */
+declare function touchesSecretPath(patch: string): string[];
+/**
+ * @experimental
+ *
+ * The pure mechanical gate — the SINGLE source of the no-op / always-on secret-path floor /
+ * diff-size / forbidden-path / test / typecheck checks. No I/O: it scores a patch + its
+ * already-derived pass signals.
+ *
+ * Checks in order: (1) no-op rejection, (2) always-on secret-path floor (independent of
+ * `forbiddenPaths`), (3) forbidden-path, (4) diff-size cap, (5) tests, (6) typecheck.
+ * Aggregate score: `0.5*tests + 0.3*typecheck + 0.2*(1 - diffLines/maxDiff)`; `valid` is the
+ * conjunction of all six.
+ */
+declare function runCoderChecks(input: CoderCheckInput, constraints?: CoderCheckConstraints): DefaultVerdict;
+
+/**
+ * @experimental
+ *
+ * The ONE worktree-harness execution core. The physical act — run a supervisor-authored
+ * `AgentProfile` on a local coding-harness CLI (claude / codex / opencode) against a fresh git
+ * worktree off `repoRoot`, capture the diff, derive the test/typecheck PASS signals, then clean
+ * up — lives here ONCE. Two executors adapt it to two ports without re-implementing it:
+ *   - `createWorktreeCliExecutor` — the `Scope`/`Supervisor` leaf `Executor`.
+ *   - `createInProcessExecutor`   — the `runLoop` `SandboxClient` / coder-delegate path.
+ *
+ * §1.5 by construction: the authored `profile.prompt.systemPrompt` + `profile.model.default`
+ * reach the harness through `harnessInvocation` HERE, so neither port can drop them — the exact
+ * bug that existed while the in-process path called `runLocalHarness` with only the task prompt.
+ *
+ * Lifecycle: `createWorktree` → `harnessInvocation` + `runLocalHarness` → `captureWorktreeDiff`
+ * (BEFORE checks, so the patch is the harness's output, not polluted by files a test run writes)
+ * → the configured test/typecheck commands in the live worktree → return the result + a `cleanup`
+ * the caller invokes at its own teardown point. A throw cleans up before propagating, so a failed
+ * run never leaks a worktree.
+ */
+
+/** Outcome of one verification command run in the worktree (test or typecheck). */
+interface WorktreeCommandResult {
+    /** The shell command line that was run. */
+    command: string;
+    /** Did the command exit 0? The PASS signal a deliverable gate / coder output reads. */
+    passed: boolean;
+    /** OS exit code, or `null` when killed before exit. */
+    exitCode: number | null;
+    /** Combined stdout+stderr (capped) — surfaced in traces for diagnosis. */
+    output: string;
+}
+/** The canonical result of one worktree-harness run, projected by each port to its own shape. */
+interface WorktreeHarnessResult {
+    /** The branch the worktree was cut on (`delegate/<runId>`). */
+    branch: string;
+    /** `git diff` of the worktree against its base — the unified patch the harness produced. */
+    patch: string;
+    /** Shortstat-derived change counts. */
+    stats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+    /** The harness subprocess outcome. */
+    harness: {
+        name: LocalHarness;
+        exitCode: number | null;
+        timedOut: boolean;
+        killedBySignal: NodeJS.Signals | null;
+        durationMs: number;
+        stdout: string;
+        stderr: string;
+    };
+    /** Verification signals derived in the live worktree (present only when commands were given). */
+    checks?: {
+        tests?: WorktreeCommandResult;
+        typecheck?: WorktreeCommandResult;
+    };
+}
+/** The single shell-command-in-worktree runner seam (replaces the per-executor copies). */
+type WorktreeCheckRunner = (opts: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    exitCode: number | null;
+    output: string;
+}>;
+
+/**
+ * @experimental
+ *
+ * The worktree-CLI leaf executor — a supervisor-authored `AgentProfile` driving a local
+ * coding-harness CLI (claude / codex / opencode) on its OWN git worktree, surfaced as the open
+ * `Executor<Out>` port (`./types`). It is a LEAF executor: it plugs straight into the
+ * `Scope`/`Supervisor` recursion and `gateOnDeliverable`, so it IS the canonical recursive path
+ * (no `runLoop`/virtual-SandboxInstance shim in between).
+ *
+ * This is a THIN adapter: the physical act (worktree → profile-aware harness invocation → diff →
+ * checks → cleanup) lives ONCE in `runWorktreeHarness` (`../../mcp/worktree-harness`), shared with
+ * the `runLoop`/coder-delegate `createInProcessExecutor`. This executor only projects that core's
+ * result onto the `Executor` port (artifact + spend) and owns the teardown point. The §1.5 payload
+ * (authored systemPrompt + model) reaches the harness inside the core, not here.
+ *
+ * Token accounting: a harness CLI does not surface usage, so this executor is `budgetExempt: true`
+ * — its spend is NOT metered against the conserved pool and its iterations are EXCLUDED from the
+ * equal-k arms by construction (mirrors `cliExecutor`).
+ */
+
+/** Terminal artifact of one worktree-CLI run — the canonical worktree-harness result (the captured
+ *  diff + the harness's run record + the derived checks). */
+type WorktreePatchArtifact = WorktreeHarnessResult;
+/** @experimental */
+interface WorktreeCliExecutorOptions {
+    /** Absolute path to the git checkout the worktree is cut from. */
+    repoRoot: string;
+    /** The SUPERVISOR-AUTHORED profile (the §1.5 payload: systemPrompt + model). */
+    profile: AgentProfile;
+    /** Which local harness CLI drives this leaf (`claude` | `codex` | `opencode`). */
+    harness: LocalHarness;
+    /** The per-task instruction handed to the harness (composed under the system prompt). */
+    taskPrompt: string;
+    /** Unique id for the worktree path + branch. Defaults to a fresh UUID. */
+    runId?: string;
+    /** Override the base ref the worktree is cut from (default `HEAD`). */
+    baseRef?: string;
+    /** Wall-clock cap per harness subprocess (ms). Default 5 min (the `runLocalHarness` default). */
+    harnessTimeoutMs?: number;
+    /**
+     * Shell command run in the live worktree to derive the tests-PASS signal (e.g. `pnpm test`).
+     * Its exit code becomes `artifact.checks.tests.passed`. Omit to skip (no signal derived).
+     */
+    testCmd?: string;
+    /** Shell command run in the live worktree to derive the typecheck-PASS signal (e.g. `pnpm typecheck`). */
+    typecheckCmd?: string;
+    /** Wall-clock cap per verification command (ms). Default = `harnessTimeoutMs` or 5 min. */
+    checkTimeoutMs?: number;
+    /** Test seam — inject a git runner so unit tests drive the worktree helpers without git. */
+    runGit?: GitRunner;
+    /** Test seam — inject the harness runner so unit tests script a `LocalHarnessResult`. */
+    runHarness?: typeof runLocalHarness;
+    /** Test seam — inject the verification-command runner so unit tests script test/typecheck
+     *  outcomes without spawning a real shell. Defaults to a `/bin/sh -c` spawn in the worktree. */
+    runCommand?: WorktreeCheckRunner;
+}
+/**
+ * Build a worktree-CLI leaf `Executor`. Per-spawn (a fresh worktree + abort + teardown each), so a
+ * fanout of N profiles = N parallel worktrees that never clobber each other.
+ *
+ * Fail-loud: an empty `repoRoot`/`harness`/`taskPrompt` throws at construction. `resultArtifact()`
+ * before `execute()` resolves throws.
+ *
+ * @experimental
+ */
+declare function createWorktreeCliExecutor(options: WorktreeCliExecutorOptions): Executor<WorktreePatchArtifact>;
+
+/**
+ * @experimental
+ *
+ * `patchDelivered` — the mechanical patch gate as a generic `DeliverableSpec` over the worktree-CLI
+ * artifact. It is one construction of a `DeliverableSpec` (a plain `check(artifact) => boolean`
+ * function); a domain customizes "is it done" by building its own spec, not by extending this one.
+ * The canonical use: a `fanout(createWorktreeCliExecutor)` of authored harness profiles, each
+ * `gateOnDeliverable(patchDelivered(...))`.
+ *
+ * The checks themselves are NOT re-implemented here — `runCoderChecks` (`./patch-checks`) is the
+ * single source of the no-op / always-on secret-path floor / forbidden-path / diff-size / test /
+ * typecheck logic. This factory only adapts the `WorktreePatchArtifact` shape (its `checks` carry
+ * the test/typecheck PASS signals the executor derived in the live worktree) into the check inputs
+ * and returns the boolean the gate consumes.
+ *
+ * Test/typecheck enforcement is OPT-IN per `require`: when a command was not run in the worktree
+ * (the executor's `testCmd`/`typecheckCmd` were omitted) the corresponding signal is treated as
+ * passed UNLESS `require` lists it — so a gate that demands a tests-pass on an artifact that never
+ * ran tests fails closed (the honest outcome) rather than passing on a missing signal.
+ */
+
+/** @experimental */
+interface PatchDeliverableOptions extends CoderCheckConstraints {
+    /**
+     * Which verification signals the gate REQUIRES to be present-and-passing. A required signal
+     * that the artifact never derived (the command was not configured on the executor) fails the
+     * gate closed. Unlisted signals default to passed-when-absent (the executor simply didn't run
+     * that command). Default `[]` — gate on no-op / secret / forbidden / diff-size only.
+     */
+    require?: ReadonlyArray<'tests' | 'typecheck'>;
+}
+/**
+ * Build the `DeliverableSpec<WorktreePatchArtifact>`: `check(artifact)` runs the shared mechanical
+ * gate (`runCoderChecks`) over the captured patch + the worktree-derived pass signals and returns
+ * whether the patch is DELIVERED (the `valid` conjunction).
+ *
+ * @experimental
+ */
+declare function patchDelivered(options?: PatchDeliverableOptions): DeliverableSpec<WorktreePatchArtifact>;
+
+/**
+ * @experimental
+ *
+ * `worktreeFanout` — the GENERIC coding combinator: a `fanout` of N supervisor-authored harness
+ * profiles, each on its OWN worktree-CLI leaf, each `gateOnDeliverable(deliverable)`, winner via the
+ * shared `selectValidWinner` (valid-only — an ungated patch never wins, the deliverable gate is the
+ * point). The `deliverable` is passed as DATA: it defaults to `patchDelivered(opts)` but any
+ * `DeliverableSpec<WorktreePatchArtifact>` a domain authors slots in unchanged.
+ *
+ * The shape is content-free at the `fanout` layer; this builder only assembles the pieces (the
+ * worktree-CLI executor + the injected deliverable + the diff-size selector) into the generic
+ * combinator's `itemSpec`/`selectWinner` seams. Nothing here re-implements selection, gating, or
+ * fanout — it composes the existing primitives.
+ */
+
+/** @experimental One authored harness profile in a worktree fanout: the §1.5 profile + which local
+ *  harness CLI drives it. The supervisor authors `profile` per sub-task; `harness` chooses the leaf. */
+interface AuthoredHarness {
+    /** A short label for the worktree branch + trace node. */
+    name: string;
+    /** The supervisor-authored `AgentProfile` (systemPrompt + model reach the harness via §1.5). */
+    profile: AgentProfile;
+    /** Which local harness CLI drives this leaf. */
+    harness: 'claude' | 'codex' | 'opencode';
+    /** Per-harness model/runId/baseRef overrides flow through the profile + these. */
+    runId?: string;
+    baseRef?: string;
+}
+/** @experimental */
+interface WorktreeFanoutOptions extends PatchDeliverableOptions {
+    /** Absolute path to the git checkout each worktree is cut from. */
+    repoRoot: string;
+    /** The per-task instruction handed to every harness (composed under each profile's systemPrompt). */
+    taskPrompt: string;
+    /** The authored harness profiles — one fanout item (and one worktree-CLI leaf) each. */
+    harnesses: ReadonlyArray<AuthoredHarness>;
+    /**
+     * The completion check each leaf is gated on. Defaults to `patchDelivered(opts)` (the mechanical
+     * no-op/secret/forbidden/diff-size + required test/typecheck gate). Pass any
+     * `DeliverableSpec<WorktreePatchArtifact>` to customize "is it delivered" as DATA.
+     */
+    deliverable?: DeliverableSpec<WorktreePatchArtifact>;
+    /** Shell command run in each worktree to derive the tests-PASS signal. */
+    testCmd?: string;
+    /** Shell command run in each worktree to derive the typecheck-PASS signal. */
+    typecheckCmd?: string;
+    /** Wall-clock cap per harness subprocess (ms). */
+    harnessTimeoutMs?: number;
+    /** Winner-selection strategy. Default `highest-score`. */
+    winnerStrategy?: WinnerStrategy;
+    /** Test seams forwarded to every worktree-CLI leaf (inject git/harness/command runners so the
+     *  whole fanout runs offline). Production callers leave these unset. */
+    runGit?: WorktreeCliExecutorOptions['runGit'];
+    runHarness?: WorktreeCliExecutorOptions['runHarness'];
+    runCommand?: WorktreeCliExecutorOptions['runCommand'];
+}
+/**
+ * Build the worktree fanout combinator. Run it with `runPersonified({ persona, shape, task, budget })`
+ * — equal-k holds by construction (the conserved budget pool bounds the N leaves), and selection is
+ * the shared valid-only `selectValidWinner` (never a judge).
+ *
+ * @experimental
+ */
+declare function worktreeFanout<Task>(options: WorktreeFanoutOptions): CombinatorShape<Task, WorktreePatchArtifact>;
+
+export { type TrajectoryNode as $, type AuthoredHarness as A, type FlatWidenGate as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type LoopUntil as G, type LoopUntilState as H, type Panel as I, type PanelJudge as J, type PanelVerdict as K, type LoopUntilSpec as L, type PatchDeliverableOptions as M, type PersonaContext as N, type Outcome as O, type PanelSpec as P, type PersonaExecutors as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type Pipeline as U, type VerifySpec as V, type WinnerStrategy as W, type RenderCorpusToInstructions as X, type RunPersonified as Y, type ShapeBudget as Z, type ShapeContext as _, type WorktreeFanoutOptions as a, type TrajectoryReportFn as a0, type Verify as a1, type Widen as a2, type WidenDecision as a3, type WidenLineage as a4, type WorktreeCliExecutorOptions as a5, type WorktreeCommandResult as a6, countDiffLines as a7, createWorktreeCliExecutor as a8, gateOnDeliverable as a9, isNonEmptyPatch as aa, patchDelivered as ab, runCoderChecks as ac, touchedPathsFromPatch as ad, touchesSecretPath as ae, worktreeFanout as af, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DeliverableSpec as t, type CoderCheckConstraints as u, type CoderCheckInput as v, type DefinePersona as w, type EqualKOnCost as x, type Fanout as y, type FanoutSynthesis as z };