@wrongstack/cli 0.296.4 → 0.298.0

package/dist/{acp-A5OSIU2P.js → acp-S4LZQB66.js}

@@ -3,12 +3,14 @@ import {
   loadCachedAcpRegistry,
   refreshAcpRegistry,
   setupProvider
-} from "./chunk-AZESNNIC.js";
-import "./chunk-TADVX644.js";
+} from "./chunk-4HH3YGG4.js";
+import "./chunk-GO3TJICK.js";
 import "./chunk-PJHET45A.js";
 import "./chunk-7OCVIDC7.js";
 
 // src/subcommands/handlers/acp.ts
+import { randomBytes } from "node:crypto";
+import * as path from "node:path";
 import {
   defaultPermissionPolicy,
   EnsembleRegistry,
@@ -26,7 +28,6 @@ import {
   WrongStackACPServer,
   WsBridgeTransport
 } from "@wrongstack/acp/agent";
-import * as path from "node:path";
 import { WebSocketServer } from "ws";
 
 // src/acp-server-agent.ts
@@ -270,6 +271,61 @@ function buildAcpServerAgentFactory(deps, options = {}) {
   };
 }
 
+// src/subcommands/handlers/acp-connection-gate.ts
+import { timingSafeEqual } from "node:crypto";
+var OK = { ok: true };
+function isLoopbackHostHeader(rawHost) {
+  const trimmed = rawHost.trim();
+  if (!trimmed) return false;
+  try {
+    const hostname = new URL(`http://${trimmed}`).hostname.toLowerCase();
+    const bare = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+    return bare === "127.0.0.1" || bare === "localhost" || bare === "::1";
+  } catch {
+    return false;
+  }
+}
+function createAcpConnectionGate(opts) {
+  const { host, port, token } = opts;
+  const maxConnections = opts.maxConnections ?? 8;
+  const expected = Buffer.from(token);
+  const tokenFromRequest = (req) => {
+    const auth = req.headers.authorization;
+    if (typeof auth === "string" && auth.toLowerCase().startsWith("bearer ")) {
+      return auth.slice(7).trim();
+    }
+    try {
+      return new URL(req.url ?? "/", `http://${host}:${port}`).searchParams.get("token") ?? void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  const tokenOk = (supplied) => {
+    if (!supplied) return false;
+    const a = Buffer.from(supplied);
+    if (a.length !== expected.length) return false;
+    return timingSafeEqual(a, expected);
+  };
+  return {
+    check(req, liveConnections) {
+      const origin = req.headers.origin;
+      if (origin && origin !== `http://${host}:${port}` && origin !== `ws://${host}:${port}`) {
+        return { ok: false, code: 1008, reason: "cross-origin forbidden" };
+      }
+      if (!isLoopbackHostHeader(req.headers.host ?? "")) {
+        return { ok: false, code: 1008, reason: "untrusted host header" };
+      }
+      if (!tokenOk(tokenFromRequest(req))) {
+        return { ok: false, code: 1008, reason: "unauthorized" };
+      }
+      if (liveConnections >= maxConnections) {
+        return { ok: false, code: 1013, reason: "too many connections" };
+      }
+      return OK;
+    }
+  };
+}
+
 // src/subcommands/handlers/acp.ts
 function acpOverrides(deps) {
   return deps.config.acp?.agents;
@@ -383,13 +439,20 @@ async function runACPWebSocketServer(deps, port) {
     turnFactory = () => makeACPServerAgentTurn({ agentFor });
     store = deps.paths?.projectDir ? new ACPSessionStore({ dir: path.join(deps.paths.projectDir, "acp-sessions") }) : void 0;
   }
+  const acpToken = process.env["WRONGSTACK_ACP_TOKEN"]?.trim() || randomBytes(32).toString("hex");
+  const gate = createAcpConnectionGate({ host, port, token: acpToken });
+  let liveConnections = 0;
   const wss = new WebSocketServer({ host, port, maxPayload: 20 * 1024 * 1024 });
   wss.on("connection", (socket, req) => {
-    const origin = req.headers.origin;
-    if (origin && origin !== `http://${host}:${port}` && origin !== `ws://${host}:${port}`) {
-      socket.close(1008, "cross-origin forbidden");
+    const verdict = gate.check(req, liveConnections);
+    if (!verdict.ok) {
+      socket.close(verdict.code ?? 1008, verdict.reason ?? "forbidden");
       return;
     }
+    liveConnections++;
+    socket.once("close", () => {
+      liveConnections--;
+    });
     const connectionTurn = turnFactory?.();
     const transport = new WsBridgeTransport((m) => {
       const data = JSON.stringify(m);
@@ -427,9 +490,10 @@ async function runACPWebSocketServer(deps, port) {
     socket.on("close", teardown);
     socket.on("error", teardown);
   });
+  const acpUrl = `ws://${host}:${port}/?token=${acpToken}`;
   deps.renderer.writeInfo(
-    echo ? `ACP server (echo, no provider) listening on ws://${host}:${port}. Press Ctrl+C to stop.
-` : `WrongStack ACP server listening on ws://${host}:${port} (${deps.config.provider}/${deps.config.model}). Press Ctrl+C to stop.
+    echo ? `ACP server (echo, no provider) listening on ${acpUrl}. Press Ctrl+C to stop.
+` : `WrongStack ACP server listening on ${acpUrl} (${deps.config.provider}/${deps.config.model}). Press Ctrl+C to stop.
 `
   );
   await new Promise((resolve) => {
@@ -474,13 +538,17 @@ async function runACPServer(deps) {
     })()
   );
   if (echo) {
-    deps.renderer.writeInfo("ACP server starting in --echo mode (no-op turn; no provider needed).\n");
+    deps.renderer.writeInfo(
+      "ACP server starting in --echo mode (no-op turn; no provider needed).\n"
+    );
   } else {
     deps.renderer.writeInfo(
       `Starting WrongStack ACP server (${deps.config.provider}/${deps.config.model})\u2026
 `
     );
-    deps.renderer.writeInfo("Waiting for an ACP client connection on stdin/stdout. Press Ctrl+C to stop.\n");
+    deps.renderer.writeInfo(
+      "Waiting for an ACP client connection on stdin/stdout. Press Ctrl+C to stop.\n"
+    );
   }
   createGracefulShutdown({
     run: async () => {
@@ -517,8 +585,10 @@ async function listACPAgents(deps) {
 `);
   }
   for (const a of missing) {
-    deps.renderer.write(`  \u2717 ${a.id.padEnd(16)} ${a.displayName}  (${a.reason ?? "not installed"})
-`);
+    deps.renderer.write(
+      `  \u2717 ${a.id.padEnd(16)} ${a.displayName}  (${a.reason ?? "not installed"})
+`
+    );
   }
   deps.renderer.write(`
 ${installed.length} of ${detected.length} agents available.
@@ -549,8 +619,10 @@ async function syncACPRegistry(deps) {
 `);
     return 0;
   } catch (err) {
-    deps.renderer.writeError(`ACP registry sync failed: ${err instanceof Error ? err.message : String(err)}
-`);
+    deps.renderer.writeError(
+      `ACP registry sync failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
     deps.renderer.write("The bundled offline catalog is still available via `wstack acp list`.\n");
     return 1;
   }
@@ -700,19 +772,15 @@ async function parallelACPAgents(args, deps) {
           `[${r.error?.kind ?? "unknown"}] ${r.error?.message ?? "failed"}
 `
         );
-        deps.renderer.write(
-          `[${r.agentId}] failed  ${r.durationMs}ms
-`
-        );
+        deps.renderer.write(`[${r.agentId}] failed  ${r.durationMs}ms
+`);
       } else {
         deps.renderer.writeError(
           `[${r.error?.kind ?? "aborted"}] ${r.error?.message ?? "cancelled"}
 `
         );
-        deps.renderer.write(
-          `[${r.agentId}] cancelled  ${r.durationMs}ms
-`
-        );
+        deps.renderer.write(`[${r.agentId}] cancelled  ${r.durationMs}ms
+`);
       }
     }
     const { succeeded, failed, cancelled, skipped: skip } = result.summary;
@@ -821,4 +889,4 @@ ${renderAcpBenchText(result)}
 export {
   acpCmd
 };
-//# sourceMappingURL=acp-A5OSIU2P.js.map
+//# sourceMappingURL=acp-S4LZQB66.js.map

package/dist/{auth-CJWQJVRH.js → auth-NLLGEYQR.js}

@@ -13,12 +13,12 @@ import {
   runOAuthLoginKind,
   runOAuthLoginMenu,
   validateFamily
-} from "./chunk-JBTFWWKV.js";
+} from "./chunk-I2BM6FK6.js";
 import {
   parseAuthFlags
 } from "./chunk-JBSQ7ONN.js";
 import "./chunk-66T43Q4Y.js";
-import "./chunk-TADVX644.js";
+import "./chunk-GO3TJICK.js";
 import {
   loadConfigProviders,
   maskedKey,
@@ -501,4 +501,4 @@ async function runAuthRemove(deps, providerId) {
 export {
   authCmd
 };
-//# sourceMappingURL=auth-CJWQJVRH.js.map
+//# sourceMappingURL=auth-NLLGEYQR.js.map

package/dist/boot/dispatch-webui.d.ts

@@ -72,6 +72,13 @@ export interface WebUIDispatchContext {
         getAllSessions(): import('@wrongstack/core/coordination').AgentVirtualSession[];
         loadSessionsFromDisk(): Promise<import('@wrongstack/core/coordination').AgentVirtualSession[]>;
     } | undefined;
+    /**
+     * Pre-computed update info from the CLI's preflight version check.
+     * When present, surfaces (WebUI, SimpleUI) receive appVersion,
+     * latestVersion, and updateAvailable fields in their session.start
+     * payload to display an "update available" warning.
+     */
+    updateInfo?: import('../webui-server/session-start-payload.js').BootUpdateInfo | undefined;
     /** Per-task agent factory for the SDD wizard's multi-agent run. */
     sddSubagentFactory?: import('@wrongstack/core/coordination').AgentFactory | undefined;
     onKanbanDispatch?: ((description: string, opts?: {

package/dist/boot/governance-evidence-candidate.d.ts

@@ -0,0 +1,3 @@
+export type { GovernanceEvidenceCandidate, GovernanceEvidenceCandidateMissingBinding, GovernanceEvidenceTraceSnapshot, GovernanceToolOutcomeMetadata, } from '@wrongstack/runtime/governance-bootstrap';
+export { createGovernanceEvidenceCandidate, GOVERNANCE_EVIDENCE_CANDIDATE_SCHEMA_VERSION, } from '@wrongstack/runtime/governance-bootstrap';
+//# sourceMappingURL=governance-evidence-candidate.d.ts.map

package/dist/boot/governance-shadow-bridge.d.ts

@@ -0,0 +1,19 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { GovernanceRuntimeObservationInput, GovernanceRuntimeObservationResult } from '@wrongstack/runtime/governance-bootstrap';
+import type { GovernanceTraceContext } from './governance-trace-context.js';
+export interface GovernanceObservationSink {
+    observe(input: GovernanceRuntimeObservationInput): Promise<GovernanceRuntimeObservationResult>;
+}
+export interface GovernanceShadowLogger {
+    warn(message: string, context?: unknown): void;
+}
+export interface GovernanceShadowBridge {
+    close(): void;
+}
+export declare function createGovernanceShadowBridge(input: {
+    readonly events: EventBus;
+    readonly sink: GovernanceObservationSink;
+    readonly logger: GovernanceShadowLogger;
+    readonly trace: GovernanceTraceContext;
+}): GovernanceShadowBridge;
+//# sourceMappingURL=governance-shadow-bridge.d.ts.map

package/dist/boot/governance-trace-context.d.ts

@@ -0,0 +1,64 @@
+import type { WorkspaceCheckpointRef } from '@wrongstack/core/types';
+export declare const MAX_GOVERNANCE_PLAN_BYTES: number;
+export declare const MAX_GOVERNANCE_ACTIVE_STEP_IDS = 128;
+export type GovernancePlanTrace = {
+    readonly state: 'missing' | 'invalid' | 'unreadable';
+} | {
+    readonly state: 'refreshing';
+    readonly observedAt: string;
+} | {
+    readonly state: 'available';
+    readonly schemaVersion: 1;
+    readonly fingerprint: string;
+    readonly updatedAt?: string | undefined;
+    readonly observedAt: string;
+    readonly itemCount: number;
+    readonly openCount: number;
+    readonly inProgressCount: number;
+    readonly doneCount: number;
+    readonly activeStepIds: readonly string[];
+    readonly activeStepIdsTruncated: boolean;
+};
+export type GovernanceWorkspaceTrace = {
+    readonly state: 'not_captured';
+} | {
+    readonly state: 'unavailable';
+    readonly promptIndex: number;
+    readonly observedAt: string;
+} | {
+    readonly state: 'captured';
+    readonly promptIndex: number;
+    readonly manifestHash: string;
+    readonly baseHead: string;
+    readonly entryCount: number;
+    readonly unresolvedCount: number;
+    readonly capturedAt: string;
+    readonly coverage: WorkspaceCheckpointRef['coverage'];
+};
+export interface GovernanceTraceContextSnapshot {
+    readonly sessionId: string;
+    readonly task: {
+        readonly scope: 'session';
+    } | {
+        readonly scope: 'kanban_task';
+        readonly taskId: string;
+        readonly boardId: string | null;
+    };
+    readonly plan: GovernancePlanTrace;
+    readonly workspace: GovernanceWorkspaceTrace;
+}
+export interface GovernanceTraceContext {
+    matchesPlanPath(candidate: string): boolean;
+    refreshPlan(): Promise<GovernancePlanTrace>;
+    updateWorkspaceCheckpoint(promptIndex: number, observedAt: string, checkpoint: WorkspaceCheckpointRef | undefined): void;
+    snapshot(taskId: string | null, boardId?: string | undefined): GovernanceTraceContextSnapshot;
+}
+export interface GovernanceTraceContextDependencies {
+    readonly readFile: (filePath: string) => Promise<string>;
+    readonly now: () => string;
+}
+export declare function createGovernanceTraceContext(input: {
+    readonly sessionId: string;
+    readonly planPath: string;
+}, dependencies?: GovernanceTraceContextDependencies): Promise<GovernanceTraceContext>;
+//# sourceMappingURL=governance-trace-context.d.ts.map

package/dist/boot/launch-banner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pre-boot launch banner — the WRONGSTACK brand mark + wordmark rendered
+ * as raw ANSI strings for the plain-terminal launch menu.
+ *
+ * This is a deliberate plain-string twin of the TUI banner
+ * (packages/tui/src/components/history/banner.tsx). Importing the TUI
+ * component here would drag ink+react into the pre-boot path — which may
+ * end up launching WebUI/HQ and never need them. When the TUI glyph
+ * tables or palette change, update these in the same commit.
+ */
+/** Exported so the menu can decide full vs compact by terminal width. */
+export declare const WORDMARK_WIDTH: number;
+/**
+ * Build the launch-screen banner as an array of pre-colored lines
+ * (no trailing newlines, no indent — the caller owns placement).
+ *
+ * Full art (mark + wordmark + tagline) when the terminal is wide enough;
+ * a one-line gradient fallback otherwise. Honors NO_COLOR / non-TTY by
+ * emitting plain text.
+ */
+export declare function launchBannerLines(columns: number, version?: string): string[];
+//# sourceMappingURL=launch-banner.d.ts.map

package/dist/boot/tui-session-resume.d.ts

@@ -1,6 +1,6 @@
 import type { Agent } from '@wrongstack/core/agent';
 import type { EventBus } from '@wrongstack/core/kernel';
-import type { TokenCounter } from '@wrongstack/core/types';
+import type { ContextSnapshot, TokenCounter } from '@wrongstack/core/types';
 import type { TuiRuntimeState } from './tui-runtime-state.js';
 export interface SessionResumeContext {
     state: TuiRuntimeState;
@@ -14,6 +14,15 @@ export interface SessionResumeResult {
     entries: unknown[];
     nextId: number;
     sessionId: string;
+    /**
+     * Optional context-window snapshot for the resumed session. `tokens` is a
+     * flat `number` (sum of `tokenCounter.currentRequestTokens()?.`'s
+     * `{ input, cacheRead, cacheWrite }` fields) — the TUI consumer
+     * (`packages/tui/src/reducers/composer.ts:561-577`) reads `tokens` as a
+     * flat number and gates on `snap.tokens > 0`. Forwarding the raw object
+     * would coerce to NaN and silently drop the snapshot at runtime.
+     */
+    contextSnapshot?: ContextSnapshot | undefined;
 }
 /**
  * Resume a past session by id.

package/dist/chimera-leader-wake.d.ts

@@ -0,0 +1,57 @@
+import type { RunResult } from '@wrongstack/core/agent';
+import type { ContentBlock } from '@wrongstack/core/types';
+export interface ChimeraLeaderWakeAgent {
+    readonly ctx: {
+        activeRunSessionId?: string | undefined;
+        session?: {
+            id: string;
+        } | undefined;
+    };
+    run(input: string | ContentBlock[], options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<RunResult>;
+}
+export interface ChimeraLeaderWakeEvents {
+    emitCustom(event: string, payload: unknown): void;
+}
+export interface ChimeraLeaderWakeRequest {
+    sessionId: string;
+    cwd: string;
+    changedFiles: readonly string[];
+    structuredReport: string;
+    /** Optional stable key supplied by a durable report store. */
+    reportId?: string | undefined;
+}
+export interface ChimeraLeaderWakeResult {
+    key: string;
+    status: RunResult['status'];
+    iterations: number;
+    finalText?: string | undefined;
+}
+export declare function shouldWakeChimeraLeader(input: {
+    autoFix: 'off' | 'ask' | 'auto';
+    hasActionableFindings: boolean;
+    leaderApproved: boolean;
+    reviewLength: number;
+}): boolean;
+export interface ChimeraLeaderWakeQueue {
+    enqueue(request: ChimeraLeaderWakeRequest): Promise<ChimeraLeaderWakeResult>;
+}
+export interface CreateChimeraLeaderWakeQueueOptions {
+    agent: ChimeraLeaderWakeAgent;
+    events: ChimeraLeaderWakeEvents;
+    idlePollMs?: number | undefined;
+    wakeTimeoutMs?: number | undefined;
+}
+/**
+ * Serialize system-originated Chimera follow-ups through the session leader.
+ *
+ * A Chimera review can finish after the user's turn has returned. Calling
+ * `Agent.run()` immediately is unsafe when that turn is still draining, so
+ * the queue waits for the agent's pinned run marker to clear and then starts
+ * exactly one synthetic follow-up for a report/content key.
+ */
+export declare function createChimeraLeaderWakeQueue(options: CreateChimeraLeaderWakeQueueOptions): ChimeraLeaderWakeQueue;
+export declare function chimeraLeaderWakeKey(request: ChimeraLeaderWakeRequest): string;
+export declare function buildChimeraLeaderWakePrompt(request: ChimeraLeaderWakeRequest): string;
+//# sourceMappingURL=chimera-leader-wake.d.ts.map

package/dist/chimera-reviewer-policy.d.ts

@@ -1,4 +1,4 @@
-import type { SubagentConfig } from '@wrongstack/core/types';
+import type { SubagentConfig, SubagentError, TaskResult } from '@wrongstack/core/types';
 /**
  * Resolve the fallback-model chain used when spawning the chimera-review
  * reviewer subagent.
@@ -25,6 +25,94 @@ export declare function assignReviewerModelsRoundRobin(provider: string, model:
     model: string;
     fallbackModels: string[];
 };
+/** One rung of the Chimera reviewer retry ladder. */
+export interface ReviewerAttempt {
+    provider: string;
+    model: string;
+    /** In-request fallback chain handled inside the subagent for this rung. */
+    fallbackModels: string[];
+    /**
+     * Where the rung came from — an inherited (unpinned) spawn, the round-robin
+     * pick, an entry of the active fallback profile, or the session model kept as
+     * the guaranteed last resort.
+     */
+    tier: 'inherit' | 'primary' | 'fallback' | 'session';
+}
+/**
+ * Hard cap on reviewer spawns for a single review bundle. Every rung costs a
+ * full subagent run, so the ladder is bounded — but the session rung is always
+ * kept as the final entry no matter where the cap lands.
+ */
+export declare const MAX_REVIEWER_ATTEMPTS = 4;
+/** Per-attempt wall-clock budget for a reviewer spawn. */
+export declare const REVIEWER_ATTEMPT_TIMEOUT_MS = 900000;
+/**
+ * Wall-clock budget for the whole ladder. Session shutdown awaits the pending
+ * Chimera work, so retries must not turn a 15-minute worst case into an
+ * unbounded one — later rungs draw down whatever is left of this budget.
+ */
+export declare const REVIEWER_LADDER_BUDGET_MS = 1200000;
+/** Below this the ladder stops: too little left for a rung to say anything. */
+export declare const REVIEWER_MIN_ATTEMPT_MS = 120000;
+/**
+ * Build the ordered list of reviewer spawns to try for one review bundle.
+ *
+ * The first rung reproduces today's assignment exactly, so the happy path is
+ * unchanged. The rest exist only for the failure path: the assigned chain, then
+ * the session's fallback profile, then the session model itself. A review is
+ * never abandoned just because one model was unavailable.
+ */
+export declare function buildReviewerAttemptLadder(input: {
+    assigned: {
+        provider: string;
+        model: string;
+        fallbackModels?: readonly string[] | undefined;
+    };
+    /** Active fallback profile chain, appended after the assigned chain. */
+    profileChain?: readonly string[] | undefined;
+    /** Session provider/model — the guaranteed last resort. */
+    session: {
+        provider: string;
+        model: string;
+    };
+    maxAttempts?: number | undefined;
+}): ReviewerAttempt[];
+/**
+ * Cap for the mutating Chimera agents (fix, cascade). Deliberately tighter than
+ * the reviewer's: those agents edit files, so every extra rung re-enters a tree
+ * a dead attempt may already have touched. One retry recovers the common case
+ * (primary model down or rate-limited) without compounding that risk.
+ */
+export declare const MAX_MUTATING_ATTEMPTS = 2;
+/**
+ * Ladder for a mutating Chimera agent (fix / cascade).
+ *
+ * Rung 0 deliberately carries no provider/model: those spawns inherit the role
+ * model matrix, and pinning a model here would silently override it. Later
+ * rungs name a model precisely because the inherited one just failed.
+ */
+export declare function buildMutatingAgentLadder(input: {
+    profileChain?: readonly string[] | undefined;
+    session: {
+        provider: string;
+        model: string;
+    };
+    maxAttempts?: number | undefined;
+}): ReviewerAttempt[];
+/**
+ * Should the ladder move to the next rung after this outcome?
+ *
+ * Anything short of success is worth another model — that is the whole point
+ * of the ladder. The exceptions are deliberate stops: a terminated subagent
+ * (`stopped`) and a parent abort (Ctrl+C, session teardown), where spawning a
+ * replacement would fight the thing that asked us to stop.
+ */
+export declare function shouldAdvanceReviewerLadder(status: TaskResult['status'] | undefined, error?: Pick<SubagentError, 'kind'> | undefined): boolean;
+/**
+ * Timeout for the next rung: the per-attempt budget, clamped to whatever is
+ * left of the ladder budget. Returns 0 when the ladder should stop.
+ */
+export declare function reviewerAttemptTimeoutMs(remainingMs: number, attemptTimeoutMs?: number, minAttemptMs?: number): number;
 /**
  * Chimera reviewers only inspect code and return a report. They never repair
  * files themselves; bug-hunter/security-scanner/fix agents own all mutations.

package/dist/chimera-subagent-ladder.d.ts

@@ -0,0 +1,72 @@
+import type { SubagentConfig, TaskResult } from '@wrongstack/core/types';
+import { type ReviewerAttempt } from './chimera-reviewer-policy.js';
+import type { ExecuteDeps } from './execute-deps.js';
+type Director = NonNullable<ExecuteDeps['fleet']['director']>;
+/** Display form of a rung — `inherit` rungs have no model of their own. */
+export declare function attemptLabel(attempt: ReviewerAttempt): string;
+/** What went wrong on one rung of a Chimera subagent ladder. */
+export interface LadderAttemptFailure {
+    /** `provider/model`, or `inherited model` for an unpinned rung. */
+    model: string;
+    tier: ReviewerAttempt['tier'];
+    /** 1-based rung index. */
+    attempt: number;
+    /** Human-readable failure summary. */
+    reason: string;
+    /** True when the rung threw instead of returning a result. */
+    threw: boolean;
+    /** Tool calls the rung made before dying — non-zero means it may have acted. */
+    toolCalls: number;
+}
+export interface LadderRunOutcome {
+    /** Terminal result, when a rung produced one. */
+    result?: TaskResult | undefined;
+    /** Winning subagent, left alive only when `keepWinnerAlive` is set. */
+    subagentId?: string | undefined;
+    /** 1-based index of the rung that succeeded. */
+    wonAt?: number | undefined;
+    attemptsUsed: number;
+    failures: LadderAttemptFailure[];
+    /** Exception from the final rung, when it threw rather than returned. */
+    lastError?: unknown;
+}
+export interface LadderRunOptions {
+    director: Director;
+    ladder: readonly ReviewerAttempt[];
+    /** Build the spawn config for a rung. Must apply the rung's model itself. */
+    buildConfig: (attempt: ReviewerAttempt, timeoutMs: number) => SubagentConfig;
+    /**
+     * Build the task text. Receives the failures so far so a mutating agent can
+     * be warned that the tree may already hold a dead attempt's partial edits.
+     */
+    buildTask: (attempt: ReviewerAttempt, failures: readonly LadderAttemptFailure[]) => string;
+    /** Per-rung wall-clock budget. */
+    attemptTimeoutMs?: number | undefined;
+    /** Wall-clock budget for the whole ladder — bounds session shutdown. */
+    budgetMs?: number | undefined;
+    /**
+     * Leave the winning subagent alive for the caller to retire. Failed rungs are
+     * always terminated immediately regardless.
+     */
+    keepWinnerAlive?: boolean | undefined;
+    onAttemptFailed?: (failure: LadderAttemptFailure, next: ReviewerAttempt | undefined) => void | Promise<void>;
+    onRecovered?: (attempt: ReviewerAttempt, failures: readonly LadderAttemptFailure[]) => void | Promise<void>;
+    /** Injectable clock — tests drive the budget without real waiting. */
+    now?: () => number;
+}
+/**
+ * Run one task down a ladder of models until it succeeds.
+ *
+ * A Chimera agent must never be abandoned because a single model was
+ * unavailable: every rung short of a deliberate stop (`stopped` status, parent
+ * abort) advances to the next model, ending on the session model. The ladder is
+ * bounded by both rung count and wall clock — session shutdown awaits this work.
+ */
+export declare function runSubagentModelLadder(opts: LadderRunOptions): Promise<LadderRunOutcome>;
+/**
+ * Preamble for a mutating agent's retry: the tree may already hold a dead
+ * attempt's edits, so the successor must re-read before it writes.
+ */
+export declare function buildRetryPreamble(failures: readonly LadderAttemptFailure[]): string;
+export {};
+//# sourceMappingURL=chimera-subagent-ladder.d.ts.map

package/dist/{chunk-AZESNNIC.js → chunk-4HH3YGG4.js}

@@ -2,7 +2,7 @@ import {
   fallbackCodexProviderModels,
   filterCurrentCodexModelIds,
   isCodexCatalogModel
-} from "./chunk-TADVX644.js";
+} from "./chunk-GO3TJICK.js";
 
 // src/acp-registry-cache.ts
 import {
@@ -208,9 +208,9 @@ Try \`wstack models refresh\` once you have network access, or run with --no-fea
 }
 
 export {
-  setupProvider,
   loadCachedAcpRegistry,
   refreshAcpRegistry,
+  setupProvider,
   createGracefulShutdown
 };
-//# sourceMappingURL=chunk-AZESNNIC.js.map
+//# sourceMappingURL=chunk-4HH3YGG4.js.map