@provos/ironcurtain 0.11.0 → 0.12.0

package/dist/workflow/orchestrator.d.ts

@@ -27,6 +27,7 @@ import type { ResolvedSkill } from '../skills/types.js';
  * location.
  */
 export declare function stageWorkflowSkillsAtStart(packageDir: string, runMetaDir: string): string | undefined;
+export declare function stageWorkflowScriptsAtStart(packageDir: string, runMetaDir: string): string | undefined;
 /** Handle for writing to a workflow tab in the mux. */
 export interface WorkflowTabHandle {
     write(text: string): void;
@@ -88,6 +89,10 @@ export interface CreateWorkflowInfrastructureInput {
      * Persona skills are layered in per-state via `bundle.restageSkills`.
      */
     readonly resolvedSkills?: readonly ResolvedSkill[];
+    /** Per-run staged workflow scripts directory to mount read-only in the bundle. */
+    readonly workflowScriptsDir?: string;
+    /** Optional immutable snapshot image digest to use for the main container. */
+    readonly baseImageOverride?: string;
 }
 /** Inputs for starting the coordinator's HTTP control server on a workflow bundle. */
 export interface StartWorkflowControlServerInput {
@@ -157,6 +162,17 @@ export interface WorkflowOrchestratorDeps {
      * to assert on the RPC shape without standing up a real socket.
      */
     readonly loadPolicyRpc?: (input: LoadPolicyRpcInput) => Promise<void>;
+    /**
+     * Raw trajectory-capture override for this workflow run (CLI
+     * `--capture-traces` flag). Passed UNRESOLVED to the infrastructure
+     * factory, which is the single place that resolves it against
+     * `userConfig.capture?.enabled`. When resolution yields true, the
+     * factory constructs a writer for each bundle and `executeAgentState`
+     * brackets each agent's session with `bundle.beginCaptureSession` /
+     * `bundle.endCaptureSession`. Undefined falls through to config.
+     * See docs/designs/mitm-token-trajectory-capture.md §10.
+     */
+    readonly captureTracesOverride?: boolean;
 }
 /** Lifecycle events emitted by the orchestrator. */
 export type WorkflowLifecycleEvent = {
@@ -356,6 +372,20 @@ export declare class WorkflowOrchestrator implements WorkflowController {
      * test or CLI layer), which is the intended signal.
      */
     private destroyWorkflowInfrastructure;
+    /** Body of the bundle teardown; only ever started once per instance. */
+    private runBundleTeardown;
+    private shouldSnapshotOnStop;
+    private snapshotResumableScopes;
+    private dockerForSnapshotCleanup;
+    private removeSnapshotImagesAfterTeardown;
+    /**
+     * Builds and persists the terminal checkpoint, preserving the prior on-disk
+     * machineState/context (which point at the last non-terminal save point) so
+     * resume re-enters that state instead of the terminal snapshot. Shared by the
+     * abort() and handleWorkflowComplete() stop paths.
+     */
+    private saveTerminalCheckpoint;
+    private snapshotsSupersededBy;
     /**
      * Lazy-loads the default `createDockerInfrastructure` wrapper. The real
      * helper requires Docker dependencies and the session config, so we
@@ -399,7 +429,14 @@ export declare class WorkflowOrchestrator implements WorkflowController {
     abort(id: WorkflowId): Promise<void>;
     onEvent(callback: (event: WorkflowLifecycleEvent) => void): void;
     shutdownAll(): Promise<void>;
-    /** Injects concrete agent/deterministic service implementations into the machine. */
+    /**
+     * Injects concrete service implementations into the machine: `agentService`
+     * and `deterministicService` for executable states, plus `fanOutService` —
+     * the invoke body of a `workers` fan-out state, which runs
+     * {@link runFanOutSegment} and is re-provided onto each child round machine
+     * (the children reuse the same agent/deterministic actors, lane-scoped via
+     * input).
+     */
     private provideActors;
     /** Subscribes to actor snapshot changes for lifecycle events, gates, and checkpointing. */
     private subscribeToActor;
@@ -414,7 +451,474 @@ export declare class WorkflowOrchestrator implements WorkflowController {
     private buildCheckpoint;
     private saveCheckpoint;
     private executeAgentState;
+    /**
+     * Runs one fan-out batch: the invoke body of the real `workers` state,
+     * registered as the `fanOutService` actor (see {@link provideActors}). For
+     * each worker it creates a free-standing child round actor, starts it, and
+     * barrier-joins on every child reaching a `final` state, then folds the lane
+     * verdicts into a single parent-edge result (§6.2).
+     *
+     * WHY free-standing `createActor` + `.start()` and NOT in-context `spawn`:
+     * this is a `fromPromise` invoke body (plain async TS), not an XState entry
+     * action — `spawn` is only callable from inside an action. A free-standing
+     * actor is its OWN root, so the parent's `snapshot.value` stays the string
+     * `"workers"` (single-active-state spine preserved, §6.4); the children's
+     * snapshots are their own, read here via {@link waitForRoundChild}. A
+     * `type:'parallel'` region would instead fold into the parent's `value` and
+     * make it an object — fatal to checkpoint/terminal/gate serialization (§6.4).
+     *
+     * WHY mint the scope bundle BEFORE fan-out: {@link preMintFanOutScopeBundle}
+     * runs `ensureBundleForScope` serially up front so the single shared
+     * container exists before any child's first `container:true` step. N children
+     * racing their first container step would each see an empty `bundlesByScope`
+     * and mint a SEPARATE container, defeating `sharedContainer` (§6.2 / §8.1;
+     * cross-ref the `ensureBundleForScope` check-then-act race comment).
+     *
+     * Never throws: every failure path — workflow gone, misconfigured segment,
+     * unsupported worker count, missing child machine — funnels through
+     * {@link fanOutErrorResult}, which yields a `result_file_error` verdict that
+     * the parent `workers` state routes to its `failed` edge. (The `fanOutService`
+     * wrapper in {@link provideActors} would also catch a thrown error, but the
+     * uniform result keeps the parent transition table verdict-driven.)
+     */
+    private runFanOutSegment;
+    /**
+     * Promotes recorded lane lessons once, serially, at the fan-out barrier. This
+     * is the workers>1 cognition single-writer point (§9): lane `attach_analysis`
+     * calls only record durable nodes; the parent invokes `promote_cognition`
+     * after every child has recorded and before re-entering `orchestrator`.
+     *
+     * Only `recorded` lanes are promoted — blocked/errored children are filtered
+     * out because they contributed no durable node to seed a lesson from.
+     *
+     * Returns one of three shapes:
+     * - `{ error }` — the promotion ran but did not pass (the bridge returned a
+     *   non-`cognition_promoted` verdict / `needs_repair`), OR — a hard error —
+     *   `lanes.length === 0` for a workers>1 recorded batch (every recorded child
+     *   should carry a lane id, so an empty set means the join is inconsistent).
+     * - `{ result }` — the promotion passed; the caller folds the payload into the
+     *   batch result under `cognition_promotion`.
+     * - `{}` — a no-op, when {@link buildEvolvePromoteCognitionInput} returns
+     *   undefined (non-evolve segment, or a segment with nothing to promote).
+     *
+     * Mixed-verdict deferral (within §9, intended): this only runs when the batch
+     * verdict is `recorded`. When a batch instead escalates/fails, recorded lanes'
+     * lessons are NOT promoted that turn — on APPROVE→resume the recorded lanes
+     * idempotent-skip then barrier-promote (the ledger dedups), but an
+     * ABORT/FORCE_REVISION never promotes them, by design: an aborted batch must
+     * not seed cognition.
+     */
+    private promoteBarrierCognition;
+    /**
+     * Locates the segment's `attach_analysis` deterministic state and its evolve
+     * command (the segment member that carries the `evolve_result.py` path and
+     * `--run-dir`). Returns `undefined` when the segment has no such state — a
+     * non-evolve fan-out has no cognition to promote.
+     */
+    private findEvolveAttachAnalysisState;
+    /**
+     * Derives the `promote_cognition` invoke input from the segment's already-
+     * resolved `attach_analysis` command: reuses the bridge path, `--run-dir`,
+     * container scope, and timeout; rewrites the subcommand; passes the recorded
+     * lane ids; and writes one barrier-owned result at
+     * `current/cognition_promotion.json`. Returns `undefined` when the command
+     * lacks the bridge path, a `--run-dir`, or a resolvable workspace-relative
+     * result path (the caller then treats promotion as a no-op).
+     */
+    private buildEvolvePromoteCognitionInput;
+    /**
+     * Computes the single canonical `current/stop_signals.json` ONCE at the
+     * barrier join by running the bridge's `compute_stop_signals` subcommand over
+     * the batch-grown `nodes.json`. The bridge writes the bare canonical file
+     * atomically (temp+rename); per-lane `attach_analysis` only ever wrote
+     * lane-scoped copies, so this is the sole writer of the routing input the
+     * orchestrator reads each batch (SHOULD-FIX-1).
+     *
+     * Derived from the segment head's declared `sample` command (the only segment
+     * member guaranteed to carry the `evolve_result.py` path and `--run-dir`), so
+     * it inherits the same container scope / timeout. Returns an error string on
+     * failure (the caller folds it into a `result_file_error`), or `undefined` on
+     * success — including the benign case where the segment has no recognizable
+     * evolve sample command (a non-evolve fan-out has no stop signals to compute).
+     */
+    private computeBarrierStopSignals;
+    /**
+     * Derives the `compute_stop_signals` invoke input from the segment head's
+     * `sample` command: reuses its `evolve_result.py` path and `--run-dir`,
+     * rewrites the subcommand to `compute_stop_signals`, and points
+     * `--result-file` at the shared `current/stop_signals_compute.json` barrier
+     * artifact. Returns `undefined` when the command lacks the bridge path, a
+     * `--run-dir`, or a resolvable workspace-relative result path.
+     */
+    private buildEvolveStopSignalsInput;
+    /**
+     * Mints the fan-out segment's shared-container bundle ONCE, before any child
+     * actor starts (the load-bearing precondition of {@link runFanOutSegment}).
+     *
+     * The mint precondition: only when the workflow actually uses a shared
+     * container (`shouldUseSharedContainer`) AND at least one segment member runs
+     * in-container. A segment with no container members needs no bundle and
+     * returns early.
+     *
+     * `ensureBundleForScope` is an unguarded check-then-act across awaits (its own
+     * doc flags the lazy-mint race): N children each hitting their first
+     * `container:true` step would each see `bundlesByScope.get(scope)` undefined
+     * and mint a SEPARATE container. Calling it once here, serially, closes that
+     * window — every child then borrows the already-minted bundle. Cross-ref the
+     * race comment on `ensureBundleForScope`.
+     *
+     * The multi-scope throw is a guardrail, not a supported path: this slice
+     * keeps the whole segment under one `containerScope` (single-policy
+     * homogeneity, §8.2). A segment spanning >1 scope is out of slice scope and
+     * fails fast rather than minting the wrong bundle.
+     */
+    private preMintFanOutScopeBundle;
+    private buildFanOutLaneContext;
+    /**
+     * Reconstructs an in-flight evolve fan-out batch from the durable engine DB.
+     *
+     * This intentionally does NOT use XState child persistence. The checkpoint
+     * stores `{ machineState, context }` and `resolveState()` re-enters `workers`
+     * without live child ActorRefs; free-standing child actors created in the old
+     * process are gone. First-cut crash-resume therefore treats `nodes.json` as the
+     * source of truth: a recorded `step_<batch>_lane_<k>` means lane k is already
+     * done and must be synthesized, while every missing lane is re-spawned fresh
+     * from `sample`. That fresh re-run can produce a different verdict (§11.2
+     * verdict drift), which is acceptable for node-integrity but not a promise of
+     * batch-outcome reproducibility.
+     *
+     * Cross-language seam (deliberate, NOT accidental duplication). The batch-index
+     * reuse rule below re-implements Python `_next_batch_index(run_dir, workers)`.
+     * We re-derive it here rather than consume the bridge's `sample_batch_prepared`
+     * echo because the index is needed BEFORE `sample_batch` runs: TS must know it
+     * to decide synthesize-vs-respawn per lane AND to pin `--batch-index` into the
+     * very `sample_batch` call whose output would otherwise echo it. Having the
+     * bridge be authoritative would invert that ordering. So the two derivations
+     * MUST move together — TS pins `--batch-index` whenever any lane is recorded (so
+     * the bridge cannot diverge), and recomputes the identical number when none is.
+     * Both sides cite the shared `step_<batch>_lane_<k>` format (`evolveStepName` /
+     * the Python f-string) as the contract.
+     */
+    private reconstructFanOutBatchFromDb;
+    /**
+     * The evolve `--run-dir` for this fan-out segment's `sample` head, or
+     * `undefined` when the segment head is not a deterministic evolve sample
+     * command. `undefined` makes {@link reconstructFanOutBatchFromDb} return
+     * `unavailable`, so resume falls back to re-spawning all lanes fresh.
+     */
+    private evolveRunDirForFanOutSegment;
+    /**
+     * Reads the engine `nodes.json` node map. Missing file ⇒ `{ entries: [] }`
+     * with NO error — a fresh batch (or a run that has not recorded any node yet)
+     * is a normal pre-crash state and must reconstruct as "nothing recorded". A
+     * read or JSON-parse failure ⇒ an `error`, which aborts the fan-out: a corrupt
+     * DB is NOT safe to treat as empty (we would re-run lanes that may already be
+     * recorded), so the missing-vs-corrupt distinction is load-bearing.
+     */
+    private readEvolveNodes;
+    private asRecord;
+    private nodeIdFromRecord;
+    /**
+     * The node's parent lineage as a tri-state: `undefined` when the record has no
+     * `parent` array at all (omit the field from the synthesized payload — lineage
+     * unknown), `[]` for a root node (an explicit empty array — root, not omitted),
+     * and `[...ids]` for a child's parent ids. The empty-vs-undefined distinction
+     * is preserved deliberately so {@link synthesizeRecordedFanOutOutcome} can omit
+     * an unknown parent while still echoing an explicit root.
+     */
+    private nodeParentFromRecord;
+    /**
+     * Builds the barrier outcome for a lane that already recorded before a crash.
+     * The durable node proves the lane advanced; the volatile child actor context
+     * (visit counts, token spend, in-flight state) is not recoverable without the
+     * deferred `getPersistedSnapshot()` + in-context spawn migration, so this is a
+     * minimal recorded context sufficient for join, promotion, and duplicate stats.
+     *
+     * Edge cases (the contract callers rely on):
+     * - Called ONLY for a lane the engine DB already recorded — i.e. the
+     *   just-before-crash case where the node landed but the process died before
+     *   the join. Every NOT-recorded lane is re-spawned instead (see the fork in
+     *   {@link runFanOutSegment}).
+     * - Does NOT rebuild on-disk artifacts. The lane's `analysis.md` /
+     *   `analysis_record.json` may be absent post-crash, but the durable node is
+     *   authoritative, so a fabricated `lastDeterministicResult` with
+     *   `{ verdict: 'recorded', idempotent_skip: true }` is sufficient — nothing
+     *   downstream re-reads those files for a recorded lane.
+     * - `idempotent_skip: true` is the marker that this outcome was synthesized
+     *   (vs produced by a live re-run); the returned `recorded` outcome is
+     *   otherwise indistinguishable to {@link joinFanOutBatch} from a live-recorded
+     *   lane, so the join, promotion, and duplicate-rate paths need no special case.
+     */
+    private synthesizeRecordedFanOutOutcome;
+    /**
+     * Runs the ONE barrier-side `sample_batch(n=workers)` before fan-out and
+     * partitions its result into per-lane pre-computed `sample` results (keyed by
+     * lane id) that {@link executeDeterministicState} replays as each child's
+     * `sample` step.
+     *
+     * WHY one barrier-side `sample_batch(n=N)` and NOT N independent `sample()`
+     * calls: the divergence between lanes is INJECTED at sampling (§7.4). N
+     * independent `sample()` calls each reload the same `nodes.json` and, with a
+     * diversity-maintaining sampler, could draw the SAME parent into multiple
+     * lanes — collapsing the N-wide frontier into "N samples of one distribution"
+     * and producing near-duplicate candidates. A single `sample_batch` over the
+     * whole DB partitions N DISTINCT parents (one per lane) in one serialized,
+     * read-only DB touch, guaranteeing disjoint parent sets up front. The bridge
+     * uses a per-lane seed offset (`base_seed + laneId`) to decorrelate the lanes
+     * while keeping the partition reproducible, with a deterministic hash tiebreak
+     * so the assignment is stable across resume (§7.4).
+     *
+     * `workers === 1` short-circuits: the single lane uses the legacy inline
+     * `sample` step (byte-identical backward compat, gate item 1), so there is no
+     * batch to prepare. A non-deterministic or unrecognized sample state likewise
+     * returns an empty map (the child runs its own `sample`).
+     */
+    private prepareFanOutLaneResults;
+    /**
+     * Derives the deterministic invoke input for the barrier-side `sample_batch`
+     * from the segment head's declared `sample` command: rewrites the `sample`
+     * subcommand to `sample_batch`, adds `--workers <N>`, carries over the
+     * query/top-k flags, and points `--result-file` at the shared
+     * `current/sample_batch.json` (the batch artifact is barrier-owned, not
+     * lane-scoped). Returns `undefined` (the caller then lets each child sample on
+     * its own) when the segment head is not a recognizable evolve `sample`
+     * command, has no `evolve_result.py` entry, or lacks a `--run-dir` / resolvable
+     * workspace-relative result path.
+     */
+    private buildEvolveSampleBatchInput;
+    /**
+     * Shared skeleton for the three barrier-side `evolve_result.py` invocations
+     * (`sample_batch`, `promote_cognition`, `compute_stop_signals`). Given an
+     * already-resolved `sourceCommand` (the caller does the `state.run.find`), it
+     * locates the bridge path, carries over `--run-dir`, rewrites the subcommand,
+     * splices in the per-caller `extraArgs`, and points `--result-file` at the
+     * shared barrier artifact `current/<resultBasename>`. Returns `undefined` when
+     * the source command lacks the bridge path, a `--run-dir`, or a resolvable
+     * workspace-relative result path — the caller's documented no-op signal.
+     */
+    private buildEvolveBarrierInput;
+    private isEvolveSampleCommand;
+    private isEvolveAttachAnalysisCommand;
+    private commandFlagValue;
+    private sampleQueryArgs;
+    private sampleTopKArgs;
+    private containerPathToWorkspaceRelative;
+    /**
+     * Barrier primitive for one lane. Returns a {@link RoundChildWaiter} (NOT a
+     * bare Promise): a two-phase handle whose `promise` resolves by EITHER of two
+     * routes, and whose `drain`/`isSettled` members let the fan-out pump stop and
+     * inspect the lane externally.
+     *
+     * The two resolution routes and the discriminator {@link joinFanOutBatch} reads:
+     * - NATURAL SETTLE — the child's own snapshot reaches a `final` state
+     *   (`status === 'done'`), resolving with `recorded`/`blocked`/`errored` and
+     *   `drainedBy: undefined`. A free-standing child fires no parent-visible
+     *   `onDone`, so the parent watches the child's OWN snapshot (§6.2) via
+     *   subscribe-until-done rather than an `xstate.done.actor` event.
+     * - DRAIN — an external `drain(trigger)` call (a peer blocked/errored) stops
+     *   the actor and resolves with status `drained` and a populated `drainedBy`.
+     *   `drainedBy` being set vs `undefined` is exactly how the join distinguishes
+     *   a drained peer from a naturally-settled lane.
+     *
+     * `isSettled` is first-wins: whichever route fires first latches `settled`, so
+     * a lane that RECORDED before the drain reached it keeps its real `recorded`
+     * outcome (the drain is a no-op on an already-settled lane).
+     *
+     * After the child `onError` -> `errored` fix, a segment-member service
+     * rejection becomes a normal `errored` TERMINAL (status `done`, value
+     * `errored`) and resolves here; the `status === 'error'` branch is the
+     * residual safety net for an actor-level throw the `errored` terminal did not
+     * catch (e.g. an entry-action throw), which resolves as an `errored` lane so
+     * drain-on-escalation can still stop peers and the join can report the full
+     * batch.
+     *
+     * WHY a hand-rolled subscribe loop and NOT `xstate`'s `waitFor`: `waitFor`
+     * resolves only when the actor's OWN snapshot stream matches a predicate. The
+     * drain route resolves the SAME promise from OUTSIDE that stream (the pump
+     * synthesizes a `drained` outcome the instant it stops the actor, without
+     * waiting for any in-flight external service call to settle, FSM-M3). `waitFor`
+     * cannot express that external resolver, so the two-phase waiter is kept.
+     *
+     * The trailing `observe(actor.getSnapshot())` after `subscribe` guards the
+     * synchronous-settle-before-subscribe race: a child whose first state
+     * settles synchronously (e.g. a sync entry-action throw) can already be
+     * `done`/`error` by the time `.subscribe` returns, so the subscription would
+     * never deliver that final snapshot. Observing the current snapshot once,
+     * immediately, closes the lane in that case.
+     */
+    private waitForRoundChild;
+    /**
+     * Folds the settled lane outcomes into a single parent-edge result, applying
+     * a fixed verdict precedence (worst lane wins):
+     *   1. any rejected settle -> `result_file_error` (a residual actor-level
+     *      throw that did not resolve as an `errored` lane);
+     *   2. else any `blocked` lane -> `escalate` (route once to human review,
+     *      with every blocked/errored lane reason aggregated);
+     *   3. else any `errored` lane -> `result_file_error` (explicit fail mapping);
+     *   4. else any `drained` lane without an issue trigger -> `result_file_error`;
+     *   5. else all `recorded` -> `recorded` (the batch advanced).
+     *
+     * WHY `Promise.allSettled` (not `Promise.all`) upstream: one lane's rejection
+     * must not abandon its N-1 in-flight peers (FSM-S5). `all` would reject on the
+     * first throw and lose the other lanes' outcomes; `allSettled` lets the join
+     * see the full batch, including parent-synthesized `drained` peer outcomes.
+     *
+     * For `workers: 1`, the recorded path still promotes the single child context
+     * exactly. For N>1, the recorded path folds lane contexts into a parent batch
+     * context: child artifacts/conversations merge, parent visit counts remain
+     * authoritative for the single-active-state spine, and total tokens fan in
+     * from the orchestrator's workflow-level token accumulator.
+     */
+    private joinFanOutBatch;
+    /**
+     * Projects the blocked/errored lanes (the offenders) into the {@link FanOutIssue}
+     * payload that lands in the aggregated gate. Drained peers are intentionally
+     * excluded — they are the drain-first collateral, not independent issues (§ the
+     * reason list is the blocked-at-drain set, not all-would-have-blocked).
+     */
+    private fanOutIssues;
+    /**
+     * Surfaces a one-line human-readable cause for a blocked/errored lane, with an
+     * ASYMMETRIC fallback order per status — THE footgun this method guards:
+     *
+     * - `errored` prefers `lastError` then `previousAgentOutput`: an errored lane
+     *   DID trip `storeError`, so `lastError` is the populated, authoritative cause.
+     * - `blocked` prefers `previousAgentOutput` then `lastError`: a blocked lane
+     *   (evaluator_blocked) never trips `storeError`, so its `lastError` is null and
+     *   the real reason lives on `previousAgentOutput` (the evaluator's message).
+     *
+     * Do NOT collapse the two branches into one fallback chain: a unified order
+     * would surface a stale/null field for one of the two statuses. This rationale
+     * was deleted from the old call sites and is re-homed here on purpose.
+     */
+    private roundChildReason;
+    /** Renders an issue list as a header line plus one `- lane <i> <status>: <reason>` bullet per offending lane. */
+    private formatFanOutIssues;
+    /**
+     * Builds the parent-spine context for a blocked/errored BATCH (the escalate and
+     * errored-only join branches). WHAT it folds:
+     * - the worst lane's context (`source`) promoted back onto the spine via
+     *   {@link promoteFanOutContext} (lane marker stripped, parent visit counts
+     *   restored, tokens from the accumulator);
+     * - an AGGREGATED multi-lane summary of every blocked/errored lane written to
+     *   `previousAgentOutput` (this is what the orchestrator reads on APPROVE→resume
+     *   and the human reads in the gate banner);
+     * - the same lanes as the structured `issues` payload on
+     *   `lastDeterministicResult` for the gate.
+     *
+     * WHY ONE gate, not one per offending lane: all blocked/errored reasons fold
+     * into a single payload so the human reviews the batch ONCE. The two verdict
+     * shapes differ only in `lastError`: `escalate` leaves `lastError` null (a
+     * blocked lane is recoverable, not an error), while the errored-only verdict
+     * mirrors the summary into `lastError` (the batch failed).
+     *
+     * SCRATCH-SHAPE TAG (workers:1 vs workers>1 disambiguator): the orchestrator's
+     * recovery prompt has two mutually-exclusive recoveries — legacy `evaluate`-
+     * resume of the one written-but-unscored candidate (bare `current/`) vs discard
+     * the lane scratch and start a fresh `design` batch (lane-scoped
+     * `current/lane_<k>/`). At `workers:1` the lane carries NO `lane` marker and the
+     * scratch is the BARE `current/`, so the legacy resume is the correct recovery;
+     * at `workers>1` the lane scratch is under `current/lane_<k>/` and must be
+     * discarded. The summary message alone ("Fan-out batch escalated…") would push
+     * the LLM toward discard in BOTH cases, so we append an explicit scratch-shape
+     * sentence derived from `source.context.lane` to steer the prompt's branch.
+     */
+    private promoteFanOutIssueContext;
+    /**
+     * Promotes a SINGLE lane's context back onto the parent spine (the
+     * blocked/errored drain paths, and the `workers: 1` recorded path where there
+     * is exactly one lane). Strips the per-lane `lane` marker so the parent never
+     * carries a lane identity, restores the parent's authoritative `visitCounts`
+     * (the single-active-state spine owns visit accounting; a lane's own counts
+     * are a within-batch detail, §7.5), and reads `totalTokens` from the
+     * instance-level token accumulator (the aggregate over all lanes' registered
+     * sessionIds, which is the budget-authoritative figure, NOT the lane's local
+     * sum). The `lane === undefined` branch is the no-fan-out / `workers: 1` case:
+     * there is no lane marker to strip, so only the token figure is refreshed.
+     */
+    private promoteFanOutContext;
+    /**
+     * Folds the N recorded lane contexts back into ONE parent-spine context at the
+     * barrier join (the recorded happy path for `workers > 1`). This is the
+     * highest-stakes merge in the fan-out: the parent FSM is single-active-state,
+     * so after the batch it must hold a single coherent context even though N
+     * child actors each evolved their own copy in parallel. Each field is merged
+     * by a rule chosen for WHY it is correct on the spine, NOT by a uniform
+     * strategy:
+     *
+     * - `visitCounts`: the PARENT's counts are authoritative and copied verbatim.
+     *   The spine has a single active state (`workers`), entered once per batch;
+     *   the children's per-lane visit counts are a within-batch bookkeeping detail
+     *   (§7.5) that must not leak onto the parent, or the global round-limit
+     *   backstop would see N× inflated counts.
+     * - `round`: SUM of each lane's POSITIVE delta over the parent baseline
+     *   (`max(0, child.round - parent.round)`). A batch advanced the search by as
+     *   many rounds as lanes that progressed; summing positive deltas counts each
+     *   advancing lane once and ignores any lane that did not move forward.
+     * - `reviewHistory`: SUFFIX-append only — each lane's entries BEYOND the shared
+     *   parent baseline are appended. Lanes start from the same parent
+     *   reviewHistory, so a naive concat would replay the baseline N times; taking
+     *   only the suffix past `parentContext.reviewHistory.length` avoids that N×
+     *   duplication while still capturing every lane's new review notes.
+     * - `humanPrompt`: NULLED. A human prompt is a single-turn directive consumed
+     *   by one state entry; it has no meaning fanned across N lanes and must not
+     *   survive the batch (a stale prompt would mis-route the next orchestrator
+     *   turn).
+     * - `totalTokens`: read from the instance-level accumulator (the aggregate over
+     *   all lanes' registered MITM sessionIds), NOT summed from the children here —
+     *   the accumulator is the budget-authoritative figure and already includes
+     *   every lane's spend.
+     * - `artifacts` / `previousOutputHashes` / `agentConversationsByState`: shallow
+     *   last-writer-wins merge over the parent baseline (lanes write disjoint,
+     *   lane-scoped keys, so collisions are not expected; the parent baseline is
+     *   the floor). The remaining scalar fields come from `last` (the
+     *   highest-index lane), an arbitrary-but-deterministic representative.
+     */
+    private mergeRecordedFanOutContext;
+    private withoutLaneContext;
+    private logFanOutJoin;
+    /**
+     * Measures effective lane diversity for one recorded batch by content-hashing
+     * each lane's candidate source and counting byte-identical collisions.
+     *
+     * WHY content-hash at fan-in (not assume effective-N = N): distinct sampled
+     * parents do NOT guarantee distinct candidates (§7.4). Convergent lanes — the
+     * researcher LLM collapsing two different parents into the same edit, or a
+     * degenerate sampler handing out overlapping parents — can produce
+     * byte-identical candidates, so "N lanes" can have an effective diversity
+     * below N. Hashing the recorded `steps/<step>/code` files surfaces that as an
+     * observable duplicate rate instead of pretending every lane added a distinct
+     * candidate; the operator reads it as a signal to tune the diversity knobs.
+     * It is a diagnostic, NOT a gate — duplicates are still recorded as distinct
+     * nodes (the engine assigns each its own id, §7.6).
+     *
+     * Every skip is best-effort, NOT an error: a missing step_name, a candidate
+     * file that does not exist yet, or a non-recorded lane is simply omitted from
+     * the sample rather than failing the join — a diagnostic must never block a
+     * batch that otherwise recorded cleanly. The `undefined` return is the
+     * "nothing measurable" contract: when no lane yielded a hashable candidate
+     * (every lane skipped), there is no diversity to report and the caller logs no
+     * duplicate stats at all (distinct from a measured `duplicateRate: 0`).
+     */
+    private computeFanOutCandidateDuplicateStats;
+    /**
+     * The single terminal error channel from {@link runFanOutSegment} to the
+     * parent: a `result_file_error` verdict carrying `message`, which the parent
+     * `workers` state routes to its `failed` edge.
+     */
+    private fanOutErrorResult;
     private executeDeterministicState;
+    private applyResultFile;
+    /**
+     * Shared reduction for both deterministic execution paths: skip empty command
+     * arrays, mine the `N tests pass` heuristic from stdout, accumulate per-command
+     * failures, and shape the `{ passed, testCount, errors }` result. Host vs.
+     * container execution differ only in `runCommand` — keep that the only fork so
+     * the pass/fail and test-count semantics cannot drift between the two paths.
+     */
+    private reduceDeterministicCommands;
+    private runDeterministicHost;
+    private runDeterministicInContainer;
     private handleGateEntry;
     private buildGateRequest;
     private handleWorkflowComplete;