@mobrienv/autoloop-harness 0.8.0 → 0.9.1

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { AcpSession } from "@mobrienv/autoloop-backends/acp-client";
 import type { ClaudeSdkSession } from "@mobrienv/autoloop-backends/claude-sdk-client";
 import type { PiSession } from "@mobrienv/autoloop-backends/pi-rpc-client";
 import type { AgentMap } from "@mobrienv/autoloop-core/agent-map";
+import type { HookSpec } from "@mobrienv/autoloop-core/hooks-schema";
 import type * as topo from "@mobrienv/autoloop-core/topology";
 import type { LiveControlAdapter } from "./control/adapter.js";
 import type { LoopEventEmitter } from "./events.js";
@@ -11,13 +12,22 @@ export interface LaunchMetadata {
     trigger: TriggerSource;
     createdAt: string;
     parentRunId: string;
+    /**
+     * Absolute path to a single-file (`.toml`) preset, when the run was launched
+     * from one. Config and topology are loaded from this file instead of the
+     * `projectDir`'s `autoloops.toml` + `topology.toml`. Empty for directory
+     * presets.
+     */
+    presetFile?: string;
 }
 export interface ProfileInfo {
     active: string[];
     fragments: Map<string, string>;
     warnings: string[];
 }
-export type VerdictKind = "CONTINUE" | "REDIRECT" | "TAKEOVER" | "EXIT";
+export type VerdictKind = "CONTINUE" | "REDIRECT" | "TAKEOVER" | "EXIT" | "UNKNOWN";
+/** What to do when a metareview yields an UNKNOWN verdict. */
+export type ReviewOnError = "hold" | "exit" | "continue";
 export interface Verdict {
     verdict: VerdictKind;
     confidence: number;
@@ -26,6 +36,10 @@ export interface Verdict {
     takeover_output?: string;
     suggestions?: string[];
 }
+/** Live `command`-backend child process, tracked for signal-based interrupt. */
+export interface CommandSession {
+    pid: number;
+}
 export interface LoopContext {
     objective: string;
     topology: topo.Topology;
@@ -39,11 +53,93 @@ export interface LoopContext {
         maxIterationRuntimeMs?: number;
         /** Loop wall-clock budget in ms (0 = disabled). */
         maxRuntimeMs?: number;
+        /**
+         * Circuit-breaker: max transient/rate-limit pauses before the breaker opens
+         * and the run stops with a typed reason. Default 3.
+         */
+        transientMaxPauses?: number;
+        /** Base backoff (ms) for the transient retry ladder. Default 5000. */
+        transientPauseMs?: number;
+        /** Upper bound (ms) on the exponential transient backoff. Default 30000. */
+        transientBackoffCapMs?: number;
+        /**
+         * Max times a premature quit (stall with authorized work remaining and no
+         * blocker) is re-armed before it escalates to attention. Default 1.
+         */
+        prematureMaxRearms?: number;
     };
     completion: {
         promise: string;
         event: string;
         requiredEvents: string[];
+        /**
+         * Ralph-parity ordering policy (opt-in, default false). When true, a
+         * completion claim via `event` is rejected if any other event was
+         * emitted after it within the same turn — set-membership alone is not
+         * enough. Order-insensitive behavior (unchanged) when false.
+         */
+        mustBeLast: boolean;
+    };
+    /**
+     * Permission-enforcement policies (orthogonal to completion gating).
+     */
+    policy: {
+        /**
+         * Ralph-parity emit-boundary audit (opt-in, default false). After every
+         * iteration, diffs the working tree against HEAD; if the acting role has
+         * `disallowedTools`/`readOnly` and files changed, emits
+         * `policy.file_modification_violation` with the role + file list. Purely
+         * observational — never alters loop control flow on its own.
+         */
+        fileModAudit: boolean;
+    };
+    /**
+     * Out-of-band acceptance gate. On a done-claim the HARNESS (not the agent's
+     * session) runs every `verifyCmds` entry in a clean shell; completion is
+     * accepted only when all exit 0. A failing command blocks completion and
+     * re-injects its output. Empty `verifyCmds` disables the gate.
+     */
+    acceptance: {
+        verifyCmds: string[];
+        timeoutMs: number;
+        /**
+         * Declarative required-absence guards evaluated at the acceptance gate
+         * regardless of agent claims. Each defaults off (opt-in per preset) so
+         * existing loops are unaffected. They catch reward-hacks the LLM gates miss:
+         * leftover TODO/FIXME, skipped/only/xfail tests, committed secrets, and a
+         * dirty/untracked working tree.
+         */
+        assertNoTodo: boolean;
+        assertNoSkippedTests: boolean;
+        assertNoSecrets: boolean;
+        assertCleanTree: boolean;
+        /**
+         * Anti-reward-hack screen: under bypassPermissions the maker can edit the
+         * very tests that gate it. When on, a test-backed done-claim is blocked if
+         * the run modified test files or inserted tamper patterns (skip/only/xfail,
+         * early exit, tautological assertions) on test paths. Default off.
+         */
+        screenTestTamper: boolean;
+        /**
+         * Intent-binding acceptance criteria captured at loop start (the contract
+         * between what was asked and what is accepted). Sourced from
+         * `[acceptance].criteria` and an "Acceptance criteria" section of the
+         * objective. A criterion may bind a deterministic check with ` :: <shell
+         * cmd>`; checked criteria gate completion, unchecked ones are advisory.
+         */
+        criteria: string[];
+    };
+    /**
+     * Human-in-the-loop. When an agent emits `ask.event`, the loop blocks until
+     * an operator responds (via the `respond` control verb) or `timeoutMs`
+     * elapses, then injects the answer into the next prompt as guidance.
+     * Disabled when `enabled` is false (ask.event is empty).
+     */
+    ask: {
+        enabled: boolean;
+        event: string;
+        timeoutMs: number;
+        pollMs: number;
     };
     backend: {
         kind: string;
@@ -55,6 +151,14 @@ export interface LoopContext {
         trustAllTools: boolean;
         agent: string;
         model: string;
+        profile?: string;
+        disallowedTools: string[];
+        /**
+         * Opt-in cost-telemetry convention for `command`-kind backends: `"file"`
+         * reads a JSON usage object the wrapped command wrote to
+         * `$AUTOLOOP_USAGE_FILE`. Empty disables extraction (default).
+         */
+        usageFrom: string;
     };
     review: {
         enabled: boolean;
@@ -70,11 +174,52 @@ export interface LoopContext {
         trustAllTools: boolean;
         agent: string;
         model: string;
+        profile?: string;
+        /**
+         * Fail-closed routing for an UNKNOWN verdict (malformed/empty/timed-out
+         * review, or confidence below `minConfidence`). Default `hold`: stop the
+         * loop and raise attention rather than silently continuing.
+         */
+        onError: ReviewOnError;
+        /**
+         * A parsed verdict whose confidence is below this threshold is downgraded
+         * to UNKNOWN. Default 0.5. Set 0 to disable confidence gating.
+         */
+        minConfidence: number;
     };
     parallel: {
         enabled: boolean;
         maxBranches: number;
         branchTimeoutMs: number;
+        /** Loop-level default wave completion strategy (role `aggregate` overrides). */
+        aggregate: {
+            mode: "wait_for_all" | "first_success" | "timeout";
+            timeoutMs: number;
+        };
+    };
+    /**
+     * Fan-out `[[stage]]` execution knobs. `concurrency` bounds how many stage
+     * branches run at once run-wide (defaults to `defaultConcurrency()`, the
+     * same core/os-derived ceiling waves use); `branchTimeoutMs` bounds one
+     * branch's wall-clock time.
+     */
+    stage: {
+        concurrency: number;
+        branchTimeoutMs: number;
+    };
+    hooks: {
+        preRun: string;
+        preIteration: string;
+        postIteration: string;
+        postRun: string;
+        strict: boolean;
+        /**
+         * Structured per-hook specs (legacy flat keys + `[[hook]]` entries),
+         * merged and template-expanded. This is the engine's source of truth;
+         * the flat fields above remain for backward compatibility with existing
+         * callers/tests but `specs` is what `runPhaseHooks` iterates.
+         */
+        specs: HookSpec[];
     };
     memory: {
         budgetChars: number;
@@ -85,6 +230,16 @@ export interface LoopContext {
     harness: {
         instructions: string;
     };
+    /**
+     * Preset-declared progress metric: a command whose numeric stdout is the
+     * scalar (tests passing, coverage, tasks closed, ...) journaled per iteration
+     * to enable drift/convergence detection. Disabled when `metricCmd` is "".
+     */
+    progress?: {
+        metricCmd: string;
+        name: string;
+        timeoutMs: number;
+    };
     profiles: ProfileInfo;
     paths: {
         projectDir: string;
@@ -113,6 +268,13 @@ export interface LoopContext {
         logLevel: string;
         branchMode: boolean;
         isolationMode: string;
+        /**
+         * Forces every fan-out stage branch to relaunch rather than reuse a
+         * journaled `stage.branch.finish` record from an interrupted prior
+         * attempt (`run --no-resume` / `resume --no-resume`). Lives on `runtime`
+         * (not config-derived `stage`) because it survives `reloadLoop`.
+         */
+        noResume?: boolean;
     };
     launch: LaunchMetadata;
     store: Record<string, unknown>;
@@ -141,13 +303,31 @@ export interface LoopContext {
     claudeSdkSession: {
         current: ClaudeSdkSession | undefined;
     };
+    /**
+     * Live `command`-backend child process holder, aliased like the other
+     * session holders. Populated for the duration of an in-flight `command`
+     * iteration (async-spawned, not `execSync`) so `commandControlAdapter` can
+     * signal it (SIGUSR1 → SIGTERM → SIGKILL) for the `interrupt` verb. Cleared
+     * once the iteration's process exits.
+     */
+    commandSession: {
+        current: CommandSession | undefined;
+    };
     lastVerdict?: Verdict;
     /** Optional structured-event emitter, forwarded from RunOptions.onEvent. */
     onEvent?: LoopEventEmitter;
     controlAdapter?: LiveControlAdapter;
+    /** Abort signal for the run; consulted while blocking on a human ask. */
+    signal?: AbortSignal;
 }
 export interface RunOptions {
     workDir?: string;
+    /**
+     * Absolute path to a single-file (`.toml`) preset. When set, config and
+     * topology are loaded from this file rather than from `projectDir`'s
+     * `autoloops.toml` + `topology.toml`.
+     */
+    presetFile?: string;
     backendOverride?: Record<string, unknown>;
     configOverride?: Record<string, unknown>;
     logLevel?: string | null;
@@ -163,6 +343,11 @@ export interface RunOptions {
     mergeStrategy?: string;
     automerge?: boolean;
     keepWorktree?: boolean;
+    /**
+     * Force every fan-out stage branch to relaunch rather than reuse a
+     * journaled `stage.branch.finish` record from an interrupted prior attempt.
+     */
+    noResume?: boolean;
     /**
      * Optional abort signal. When provided, the CLI (or SDK caller) owns
      * process signal handling; the harness only listens to this signal for
@@ -176,8 +361,68 @@ export interface RunOptions {
      */
     onEvent?: LoopEventEmitter;
 }
+/**
+ * Versioned, exhaustive set of terminal `RunSummary.stopReason` values.
+ * Every literal string ever assigned to `RunSummary.stopReason` anywhere in
+ * this package must appear here. Consumers (e.g. ralph v3) can rely on this
+ * being a closed set instead of an unbounded `string`, and can use
+ * {@link STOP_REASONS} to validate values arriving over an untrusted
+ * boundary (e.g. a persisted journal or IPC payload) at runtime.
+ *
+ * Emission sites (see the enforcement test in
+ * `packages/harness/test/harness/stop-reason.test.ts`):
+ * - `stop.ts` — `max_iterations`, `backend_failed`, `backend_timeout`,
+ *   `stalled`, `cost_budget`, `max_runtime`, `review_unknown`,
+ *   `premature_quit`, `suspended`, and `completeLoop()` which echoes the
+ *   `completion_event`/`completion_promise`/`verdict_*` literals its
+ *   callers pass in.
+ * - `index.ts` — `interrupted`, `error`, and `verdict_unknown` /
+ *   `verdict_exit` / `verdict_takeover` (via `completeLoop`).
+ * - `iteration.ts` — `completion_event`, `completion_promise` (via
+ *   `completeLoop`), and a direct `interrupted` result.
+ * - `provisional.ts` — `completion_held` (non-terminal `failure.diagnostic`
+ *   event emitted while a done-claim is parked in `awaiting_acceptance`).
+ * - `circuit-breaker.ts` — `auth_failed`, `quota_exhausted`, `rate_limited`,
+ *   `transient_error`, `backend_failed` (consumed by
+ *   `stopBackendErrorClass` in `stop.ts`).
+ * - `wave.ts` / `wave/finalize-wave.ts` — `parallel_wave_timeout`,
+ *   `parallel_wave_failed` (terminal, via `stopAfterParallelWave`), and
+ *   `parallel_wave_invalid` (terminal — `wave.ts` rejects a dispatch while
+ *   another wave is already active, or an unparsable payload, and that
+ *   rejection is *also* routed through `stopAfterParallelWave`, ending the
+ *   run). Note: `parallel_wave_complete` is a distinct, non-terminal
+ *   internal value used only to trigger `continueAfterParallelJoin`; it
+ *   never reaches `RunSummary` and is intentionally **not** part of this
+ *   union.
+ *
+ * Categories (23 values enumerated by the originating issue, plus two
+ * additional real terminal literals — `parallel_wave_invalid` and `suspended` —
+ * discovered during implementation; see the parallel-wave and hooks notes above):
+ * - success (3): `completed`, `completion_event`, `completion_promise`
+ * - failures (7): `backend_failed`, `backend_timeout`, `auth_failed`,
+ *   `quota_exhausted`, `rate_limited`, `transient_error`, `review_unknown`
+ * - stops (7): `max_iterations`, `stalled`, `cost_budget`, `max_runtime`,
+ *   `premature_quit`, `interrupted`, `suspended`
+ * - verdicts (3): `verdict_exit`, `verdict_takeover`, `verdict_unknown`
+ * - held (1): `completion_held`
+ * - parallel (3): `parallel_wave_timeout`, `parallel_wave_failed`,
+ *   `parallel_wave_invalid`
+ * - error handling (1): `error`
+ *
+ * Naming-collision warning: `stopReason` is also a field name on the ACP
+ * per-turn protocol (`"end_turn" | "cancelled" | "refusal"`, see
+ * `packages/cli/src/acp/*.ts` and `packages/backends/src/acp-client.ts`) and
+ * on the wave-branch-parsing domain (`BranchResult.stopReason`,
+ * `WaveResult.reason` in `wave/types.ts`, which additionally include the
+ * synthetic `"branch_process_failed"` value parsed from untrusted
+ * subprocess stdout). Those are unrelated, wider domains — do not widen
+ * this union to cover them, and do not narrow them to this union.
+ */
+export declare const STOP_REASONS: readonly ["completed", "completion_event", "completion_promise", "backend_failed", "backend_timeout", "auth_failed", "quota_exhausted", "rate_limited", "transient_error", "review_unknown", "max_iterations", "stalled", "cost_budget", "max_runtime", "premature_quit", "interrupted", "suspended", "verdict_exit", "verdict_takeover", "verdict_unknown", "completion_held", "parallel_wave_timeout", "parallel_wave_failed", "parallel_wave_invalid", "error"];
+/** See {@link STOP_REASONS} for documentation of every literal. */
+export type StopReason = (typeof STOP_REASONS)[number];
 export interface RunSummary {
     iterations: number;
-    stopReason: string;
+    stopReason: StopReason;
     runId?: string;
 }

package/dist/types.js

@@ -1,2 +1,92 @@
-export {};
+/**
+ * Versioned, exhaustive set of terminal `RunSummary.stopReason` values.
+ * Every literal string ever assigned to `RunSummary.stopReason` anywhere in
+ * this package must appear here. Consumers (e.g. ralph v3) can rely on this
+ * being a closed set instead of an unbounded `string`, and can use
+ * {@link STOP_REASONS} to validate values arriving over an untrusted
+ * boundary (e.g. a persisted journal or IPC payload) at runtime.
+ *
+ * Emission sites (see the enforcement test in
+ * `packages/harness/test/harness/stop-reason.test.ts`):
+ * - `stop.ts` — `max_iterations`, `backend_failed`, `backend_timeout`,
+ *   `stalled`, `cost_budget`, `max_runtime`, `review_unknown`,
+ *   `premature_quit`, `suspended`, and `completeLoop()` which echoes the
+ *   `completion_event`/`completion_promise`/`verdict_*` literals its
+ *   callers pass in.
+ * - `index.ts` — `interrupted`, `error`, and `verdict_unknown` /
+ *   `verdict_exit` / `verdict_takeover` (via `completeLoop`).
+ * - `iteration.ts` — `completion_event`, `completion_promise` (via
+ *   `completeLoop`), and a direct `interrupted` result.
+ * - `provisional.ts` — `completion_held` (non-terminal `failure.diagnostic`
+ *   event emitted while a done-claim is parked in `awaiting_acceptance`).
+ * - `circuit-breaker.ts` — `auth_failed`, `quota_exhausted`, `rate_limited`,
+ *   `transient_error`, `backend_failed` (consumed by
+ *   `stopBackendErrorClass` in `stop.ts`).
+ * - `wave.ts` / `wave/finalize-wave.ts` — `parallel_wave_timeout`,
+ *   `parallel_wave_failed` (terminal, via `stopAfterParallelWave`), and
+ *   `parallel_wave_invalid` (terminal — `wave.ts` rejects a dispatch while
+ *   another wave is already active, or an unparsable payload, and that
+ *   rejection is *also* routed through `stopAfterParallelWave`, ending the
+ *   run). Note: `parallel_wave_complete` is a distinct, non-terminal
+ *   internal value used only to trigger `continueAfterParallelJoin`; it
+ *   never reaches `RunSummary` and is intentionally **not** part of this
+ *   union.
+ *
+ * Categories (23 values enumerated by the originating issue, plus two
+ * additional real terminal literals — `parallel_wave_invalid` and `suspended` —
+ * discovered during implementation; see the parallel-wave and hooks notes above):
+ * - success (3): `completed`, `completion_event`, `completion_promise`
+ * - failures (7): `backend_failed`, `backend_timeout`, `auth_failed`,
+ *   `quota_exhausted`, `rate_limited`, `transient_error`, `review_unknown`
+ * - stops (7): `max_iterations`, `stalled`, `cost_budget`, `max_runtime`,
+ *   `premature_quit`, `interrupted`, `suspended`
+ * - verdicts (3): `verdict_exit`, `verdict_takeover`, `verdict_unknown`
+ * - held (1): `completion_held`
+ * - parallel (3): `parallel_wave_timeout`, `parallel_wave_failed`,
+ *   `parallel_wave_invalid`
+ * - error handling (1): `error`
+ *
+ * Naming-collision warning: `stopReason` is also a field name on the ACP
+ * per-turn protocol (`"end_turn" | "cancelled" | "refusal"`, see
+ * `packages/cli/src/acp/*.ts` and `packages/backends/src/acp-client.ts`) and
+ * on the wave-branch-parsing domain (`BranchResult.stopReason`,
+ * `WaveResult.reason` in `wave/types.ts`, which additionally include the
+ * synthetic `"branch_process_failed"` value parsed from untrusted
+ * subprocess stdout). Those are unrelated, wider domains — do not widen
+ * this union to cover them, and do not narrow them to this union.
+ */
+export const STOP_REASONS = [
+    // success (3)
+    "completed",
+    "completion_event",
+    "completion_promise",
+    // failures (7)
+    "backend_failed",
+    "backend_timeout",
+    "auth_failed",
+    "quota_exhausted",
+    "rate_limited",
+    "transient_error",
+    "review_unknown",
+    // stops (7)
+    "max_iterations",
+    "stalled",
+    "cost_budget",
+    "max_runtime",
+    "premature_quit",
+    "interrupted",
+    "suspended",
+    // verdicts (3)
+    "verdict_exit",
+    "verdict_takeover",
+    "verdict_unknown",
+    // held (1)
+    "completion_held",
+    // parallel (3)
+    "parallel_wave_timeout",
+    "parallel_wave_failed",
+    "parallel_wave_invalid",
+    // error handling (1)
+    "error",
+];
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAsWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc;IACd,WAAW;IACX,kBAAkB;IAClB,oBAAoB;IACpB,eAAe;IACf,gBAAgB;IAChB,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;IACZ,gBAAgB;IAChB,SAAS;IACT,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,WAAW;IACX,eAAe;IACf,cAAc;IACd,kBAAkB;IAClB,iBAAiB;IACjB,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,uBAAuB;IACvB,sBAAsB;IACtB,uBAAuB;IACvB,qBAAqB;IACrB,OAAO;CACC,CAAC"}

package/dist/wave/finalize-wave.d.ts

@@ -1,9 +1,19 @@
 import type { IterationContext } from "../prompt.js";
-import type { LoopContext, RunSummary } from "../types.js";
-import type { BranchResult, IterateFn } from "./types.js";
-export declare function finalizeParallelWave(loop: LoopContext, iter: IterationContext, waveId: string, results: BranchResult[]): {
-    reason: string;
+import type { LoopContext, RunSummary, StopReason } from "../types.js";
+import type { AggregateConfig, AggregateOutcome, BranchResult, IterateFn, WaveJoinReason } from "./types.js";
+/**
+ * Finalize a joined wave under its configured aggregate strategy.
+ *  - `wait_for_all` (default): unchanged semantics — any branch timeout or
+ *    non-success stop reason fails the whole wave.
+ *  - `first_success`: the wave completes as soon as ONE branch succeeds, even
+ *    though its siblings were cancelled (not treated as failures).
+ *  - `timeout`: if the wall-clock deadline was hit, the wave completes if at
+ *    least one branch had already succeeded, else it is a wave timeout.
+ */
+export declare function finalizeParallelWave(loop: LoopContext, iter: IterationContext, waveId: string, results: BranchResult[], aggregate: AggregateConfig, aggregateOutcome: AggregateOutcome): {
+    reason: WaveJoinReason;
     waveId: string;
 };
+export declare function branchSuccessStatus(status: string): boolean;
 export declare function continueAfterParallelJoin(loop: LoopContext, iter: IterationContext, waveId: string, emittedTopic: string, totalElapsedMs: number, iterateFn: IterateFn): Promise<RunSummary>;
-export declare function stopAfterParallelWave(loop: LoopContext, iter: IterationContext, reason: string, waveId: string): RunSummary;
+export declare function stopAfterParallelWave(loop: LoopContext, iter: IterationContext, reason: StopReason, waveId: string): RunSummary;

package/dist/wave/finalize-wave.js

@@ -2,7 +2,30 @@ import { joinCsv, jsonField } from "@mobrienv/autoloop-core";
 import { appendEvent, appendHarnessEvent, } from "@mobrienv/autoloop-core/journal";
 import * as topology from "@mobrienv/autoloop-core/topology";
 import { parallelDispatchBase, parallelJoinedTopic } from "../emit.js";
-export function finalizeParallelWave(loop, iter, waveId, results) {
+/**
+ * Finalize a joined wave under its configured aggregate strategy.
+ *  - `wait_for_all` (default): unchanged semantics — any branch timeout or
+ *    non-success stop reason fails the whole wave.
+ *  - `first_success`: the wave completes as soon as ONE branch succeeds, even
+ *    though its siblings were cancelled (not treated as failures).
+ *  - `timeout`: if the wall-clock deadline was hit, the wave completes if at
+ *    least one branch had already succeeded, else it is a wave timeout.
+ */
+export function finalizeParallelWave(loop, iter, waveId, results, aggregate, aggregateOutcome) {
+    appendWaveAggregate(loop, iter, waveId, aggregate, aggregateOutcome);
+    if (aggregate.mode === "first_success") {
+        if (aggregateOutcome.satisfiedByBranchId) {
+            return { reason: "parallel_wave_complete", waveId };
+        }
+        return finalizeNoSuccess(loop, iter, waveId, results);
+    }
+    if (aggregate.mode === "timeout" && aggregateOutcome.aggregateTimedOut) {
+        const anySucceeded = results.some((r) => branchSuccessStatus(r.stopReason));
+        if (anySucceeded)
+            return { reason: "parallel_wave_complete", waveId };
+        return finalizeNoSuccess(loop, iter, waveId, results);
+    }
+    // wait_for_all (default), or timeout mode that resolved before its deadline.
     const timedOut = results
         .filter((r) => r.stopReason === "backend_timeout")
         .map((r) => r.branchId);
@@ -23,7 +46,38 @@ export function finalizeParallelWave(loop, iter, waveId, results) {
     }
     return { reason: "parallel_wave_complete", waveId };
 }
-function branchSuccessStatus(status) {
+/** No branch succeeded (first_success/timeout modes without a winner):
+ * prefer a `wave.timeout` verdict when any branch actually timed out
+ * (backend- or aggregate-level), otherwise `wave.failed`. */
+function finalizeNoSuccess(loop, iter, waveId, results) {
+    const timedOut = results
+        .filter((r) => r.stopReason === "backend_timeout" ||
+        r.stopReason === "wave_aggregate_timeout")
+        .map((r) => r.branchId);
+    if (timedOut.length > 0) {
+        appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "wave.timeout", jsonField("wave_id", waveId) +
+            ", " +
+            jsonField("timed_out_branches", joinCsv(timedOut)));
+        return { reason: "parallel_wave_timeout", waveId };
+    }
+    const failed = results
+        .filter((r) => !branchSuccessStatus(r.stopReason))
+        .map((r) => r.branchId);
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "wave.failed", jsonField("wave_id", waveId) +
+        ", " +
+        jsonField("failed_branches", joinCsv(failed)));
+    return { reason: "parallel_wave_failed", waveId };
+}
+function appendWaveAggregate(loop, iter, waveId, aggregate, aggregateOutcome) {
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "wave.aggregate", jsonField("wave_id", waveId) +
+        ", " +
+        jsonField("mode", aggregate.mode) +
+        ", " +
+        jsonField("satisfied_by_branch_id", aggregateOutcome.satisfiedByBranchId ?? "") +
+        ", " +
+        jsonField("aggregate_timed_out", String(aggregateOutcome.aggregateTimedOut)));
+}
+export function branchSuccessStatus(status) {
     return (status === "max_iterations" ||
         status === "completion_event" ||
         status === "completion_promise");

package/dist/wave/finalize-wave.js.map

@@ -1 +1 @@
-{"version":3,"file":"finalize-wave.js","sourceRoot":"","sources":["../../src/wave/finalize-wave.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"finalize-wave.js","sourceRoot":"","sources":["../../src/wave/finalize-wave.ts"],"names":[],"mappings":"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"}

package/dist/wave/launch-branches.d.ts

@@ -1,6 +1,27 @@
 import type { IterationContext } from "../prompt.js";
 import type { LoopContext } from "../types.js";
-import type { BranchResult, BranchSpec } from "./types.js";
+import type { AggregateConfig, AggregateOutcome, BranchResult, BranchSpec } from "./types.js";
 export declare function prepareParallelBranches(loop: LoopContext, iter: IterationContext, waveId: string, waveDir: string, emittedTopic: string, objectives: string[]): BranchSpec[];
 export declare function launchParallelBranches(loop: LoopContext, specs: BranchSpec[]): BranchSpec[];
-export declare function joinParallelBranches(loop: LoopContext, iter: IterationContext, waveId: string, pending: BranchSpec[]): BranchResult[];
+export interface JoinResult {
+    results: BranchResult[];
+    aggregateOutcome: AggregateOutcome;
+}
+/**
+ * Poll all branches to completion. The default `wait_for_all` aggregate mode
+ * blocks until every branch has a result (unchanged from prior behavior). Two
+ * additional modes let a wave resolve early:
+ *  - `first_success`: return as soon as one branch succeeds, terminating the
+ *    remaining pending branches (their results are synthesized as cancelled).
+ *  - `timeout`: bound the whole wave's wall clock; branches still pending at
+ *    the deadline are terminated and synthesized as timed out.
+ */
+export declare function joinParallelBranches(loop: LoopContext, iter: IterationContext, waveId: string, pending: BranchSpec[], aggregate: AggregateConfig, waveStartMs: number): JoinResult;
+/**
+ * Write the `launch.json` a `branch-run` subprocess reads to drive one
+ * isolated branch iteration. Exported so the fan-out stage runner
+ * (`wave/stage-branch-runner.ts`) can launch stage branches through the exact
+ * same supervisor/`branch-run` spawn machinery as parallel-wave branches,
+ * rather than a second bespoke spawner.
+ */
+export declare function writeBranchLaunch(spec: BranchSpec, loop: LoopContext): void;