@wrongstack/core 0.299.0 → 0.300.0

package/dist/coordination/director.d.ts

@@ -149,5 +149,13 @@ export declare class Director implements DirectorFleetHost, ICoordinator {
     acquireCheckpointLock(): Promise<boolean>;
     spawnCollab(options: CollabSessionOptions): Promise<CollabDebugReport>;
     resumeFromCheckpoint(snapshot: DirectorStateSnapshot): void;
+    /**
+     * After re-attaching checkpoint metadata, pin the live maxSpawns ceiling
+     * (profile/flag/env wins over historical checkpoint metadata). The
+     * historical cumulative spawn counter is deliberately NOT restored — the
+     * lifetime budget is scoped to this director run, so a restarted session
+     * resumes with a fresh budget rather than a possibly-exhausted counter.
+     */
+    private applyResumeBudget;
 }
 //# sourceMappingURL=director.d.ts.map

package/dist/coordination/fleet-manager.d.ts

@@ -72,6 +72,14 @@ export declare class FleetManager implements IFleetManager {
     readonly spawnDepth: number;
     /** Live spawn counter. */
     private spawnCount;
+    /**
+     * Historical `maxSpawns` from the last restored checkpoint (set for any
+     * finite checkpoint ceiling, matching or not). Surfaced in
+     * `budgetSnapshot()` so operators can see resume reconciliation without
+     * reading the JSON file; `ceilingMismatch` carries the actual mismatch signal.
+     */
+    private checkpointMaxSpawnsAtResume;
+    private ceilingMismatchAtResume;
     private readonly stateCheckpoint;
     private readonly sessionWriter;
     private manifestTimer;
@@ -129,7 +137,7 @@ export declare class FleetManager implements IFleetManager {
      * which cap was exceeded. Does NOT throw — the caller decides
      * how to surface the rejection.
      */
-    canSpawn(_config: SubagentConfig): {
+    canSpawn(config: SubagentConfig): {
         kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_tokens' | 'max_context_load';
         limit: number;
         observed: number;
@@ -144,6 +152,41 @@ export declare class FleetManager implements IFleetManager {
         maxCostUsd: number;
         usedCostUsd: number;
         remainingCostUsd: number;
+        /** Historical ceiling from the last restored checkpoint, when it differs. */
+        checkpointMaxSpawns?: number | undefined;
+        /** True when checkpoint metadata and the live ceiling disagree. */
+        ceilingMismatch?: boolean | undefined;
+    };
+    /**
+     * Re-attach the on-disk checkpoint after a resume while keeping the live
+     * `maxSpawns` ceiling from construction (profile / flag / env). The
+     * historical `spawnCount` is deliberately NOT restored: the lifetime
+     * budget is scoped to this director run, so a restarted session gets a
+     * fresh budget instead of inheriting a (possibly exhausted) counter from
+     * before the restart. The checkpoint ceiling is rewritten to the live
+     * value so subsequent writes do not reintroduce a stale limit.
+     */
+    restoreFromCheckpoint(snapshot: {
+        spawnCount: number;
+        maxSpawns?: number | undefined;
+        version?: 1 | undefined;
+        directorRunId?: string | undefined;
+        updatedAt?: string | undefined;
+        spawnDepth?: number | undefined;
+        maxSpawnDepth?: number | undefined;
+        directorBudget?: {
+            maxCostUsd?: number | undefined;
+            maxTokens?: number | undefined;
+        } | undefined;
+        subagents?: unknown[] | undefined;
+        tasks?: unknown[] | undefined;
+        usage?: unknown | undefined;
+    }): {
+        usedSpawns: number;
+        maxSpawns: number;
+        remainingSpawns: number;
+        checkpointMaxSpawns?: number | undefined;
+        ceilingMismatch: boolean;
     };
     setLeaderContextPressure(tokens: number): void;
     /** Test-only accessor: number of entries in the private subagent-meta map. */
@@ -175,8 +218,10 @@ export declare class FleetManager implements IFleetManager {
      */
     get usedNicknames(): ReadonlySet<string>;
     /**
-     * Records a spawn: increments counter, stores metadata, updates state checkpoint,
-     * and schedules a debounced manifest write. Call AFTER the coordinator
+     * Records a spawn: stores metadata, updates state checkpoint, and schedules
+     * a debounced manifest write. Increments the lifetime spawn counter UNLESS
+     * the config is `spawnBudgetExempt` (ephemeral Chimera reviewer/cascade
+     * spawns do not consume the leader's budget). Call AFTER the coordinator
      * has successfully spawned the subagent.
      *
      * @param subagentId The subagent's id (from coordinator.spawn result)

package/dist/coordination/ifleet-manager.d.ts

@@ -52,6 +52,8 @@ export interface IFleetManager {
         maxCostUsd: number;
         usedCostUsd: number;
         remainingCostUsd: number;
+        checkpointMaxSpawns?: number | undefined;
+        ceilingMismatch?: boolean | undefined;
     }) | undefined;
     /**
      * Update the leader agent's current context pressure (tokens used in the

package/dist/coordination/index.js

@@ -6758,16 +6758,21 @@ var BrainMonitor = class {
           this.activeRuns += 1;
           this.lastProgressAt = Date.now();
         }),
+        // `agent.run.completed` is the only terminator. `Agent.run` emits it on
+        // every exit path — the success path and, unconditionally, the catch
+        // path — and emits `agent.run.error` *in addition* when a run fails
+        // (`core/agent.ts:302` then `:310`). Decrementing on both meant one
+        // failed run subtracted two, and the `Math.max(0, …)` clamp hid it
+        // instead of letting the counter go visibly negative.
+        //
+        // The effect was that the watchdog below stopped watching: with two
+        // concurrent runs where one fails, `activeRuns` reaches 0 while a run
+        // is still live, and the stall check returns early on every tick.
         this.opts.events.on("agent.run.completed", (e) => {
           const lsid = this.resolveLeaderSessionId();
           if (lsid && e.sessionId && e.sessionId !== lsid) return;
           this.activeRuns = Math.max(0, this.activeRuns - 1);
         }),
-        this.opts.events.on("agent.run.error", (e) => {
-          const lsid = this.resolveLeaderSessionId();
-          if (lsid && e.sessionId && e.sessionId !== lsid) return;
-          this.activeRuns = Math.max(0, this.activeRuns - 1);
-        }),
         this.opts.events.on("iteration.started", (e) => {
           const lsid = this.resolveLeaderSessionId();
           if (lsid && e.sessionId && e.sessionId !== lsid) return;
@@ -9783,6 +9788,21 @@ var DirectorStateCheckpoint = class {
   resume(snapshot) {
     this.snapshot = snapshot;
   }
+  /**
+   * After resume, pin the live spawn ceiling from the current profile/flag
+   * while preserving `spawnCount` (cumulative used budget). Checkpoint
+   * metadata previously stored a historical `maxSpawns` that can diverge
+   * from the live runtime ceiling — operators need the live value to win.
+   */
+  applyLiveMaxSpawns(maxSpawns) {
+    if (this.snapshot.maxSpawns === maxSpawns) return;
+    this.snapshot = {
+      ...this.snapshot,
+      maxSpawns
+    };
+    this.bumpUpdatedAt();
+    this.schedule();
+  }
   current() {
     return this.snapshot;
   }
@@ -13526,7 +13546,7 @@ async function spawn2(host, config, priceLookup) {
     if (host.spawnDepth >= maxSpawnDepth) {
       throw new FleetSpawnBudgetError("max_spawn_depth", maxSpawnDepth, host.spawnDepth);
     }
-    if (host.spawnCount >= host.maxSpawns) {
+    if (host.spawnCount >= host.maxSpawns && !config.spawnBudgetExempt) {
       throw new FleetSpawnBudgetError("max_spawns", host.maxSpawns, host.spawnCount + 1);
     }
     if (host.maxFleetCostUsd < Number.POSITIVE_INFINITY) {
@@ -13577,7 +13597,9 @@ async function spawn2(host, config, priceLookup) {
       ...Number.isFinite(budget?.remainingSpawns ?? host.maxSpawns - host.spawnCount) ? {
         remainingSpawns: Math.max(
           0,
-          (budget?.remainingSpawns ?? host.maxSpawns - host.spawnCount) - 1
+          // Exempt spawns don't consume leader budget, so the reported
+          // headroom is not decremented for them.
+          (budget?.remainingSpawns ?? host.maxSpawns - host.spawnCount) - (config.spawnBudgetExempt ? 0 : 1)
         )
       } : {},
       ...Number.isFinite(maxFleetTokens) ? { maxTokens: maxFleetTokens } : {},
@@ -13590,7 +13612,9 @@ async function spawn2(host, config, priceLookup) {
   if (host.fleetManager) {
     host.fleetManager.recordSpawn(result.subagentId, config, priceLookup);
   } else {
-    host.spawnCount += 1;
+    if (!config.spawnBudgetExempt) {
+      host.spawnCount += 1;
+    }
     host.subagentMeta.set(result.subagentId, {
       provider: config.provider,
       model: config.model
@@ -14515,8 +14539,17 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
       durationMs: 0
     };
     this.completedResults.push(synthetic);
+    this.trimCompletedResults();
     this.emit("task.completed", { task, result: synthetic });
   }
+  trimCompletedResults() {
+    if (this.completedResults.length > _DefaultMultiAgentCoordinator.MAX_COMPLETED_RESULTS) {
+      this.completedResults.splice(
+        0,
+        this.completedResults.length - _DefaultMultiAgentCoordinator.MAX_COMPLETED_RESULTS
+      );
+    }
+  }
   async runDispatched(subagentId, task) {
     const subagent = this.subagents.get(subagentId);
     if (!subagent) return;
@@ -14650,12 +14683,7 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
   }
   recordCompletion(result) {
     this.completedResults.push(result);
-    if (this.completedResults.length > _DefaultMultiAgentCoordinator.MAX_COMPLETED_RESULTS) {
-      this.completedResults.splice(
-        0,
-        this.completedResults.length - _DefaultMultiAgentCoordinator.MAX_COMPLETED_RESULTS
-      );
-    }
+    this.trimCompletedResults();
     this.totalIterations += result.iterations;
     if (this.inFlight > 0) {
       this.inFlight--;
@@ -19297,6 +19325,7 @@ var Director = class _Director {
   }
   setCheckpointState(snapshot) {
     setCheckpointState(this.checkpointHost(), snapshot);
+    this.applyResumeBudget(snapshot);
   }
   async readSession(subagentId, tail) {
     return readDirectorSubagentSession({
@@ -19348,6 +19377,22 @@ var Director = class _Director {
   }
   resumeFromCheckpoint(snapshot) {
     resumeFromCheckpoint(this.checkpointHost(), snapshot);
+    this.applyResumeBudget(snapshot);
+  }
+  /**
+   * After re-attaching checkpoint metadata, pin the live maxSpawns ceiling
+   * (profile/flag/env wins over historical checkpoint metadata). The
+   * historical cumulative spawn counter is deliberately NOT restored — the
+   * lifetime budget is scoped to this director run, so a restarted session
+   * resumes with a fresh budget rather than a possibly-exhausted counter.
+   */
+  applyResumeBudget(snapshot) {
+    if (this.fleetManager) {
+      this.fleetManager.restoreFromCheckpoint(snapshot);
+    }
+    this.stateCheckpoint?.applyLiveMaxSpawns(
+      Number.isFinite(this.maxSpawns) ? this.maxSpawns : void 0
+    );
   }
 };
 
@@ -19370,6 +19415,14 @@ var FleetManager = class {
   spawnDepth;
   /** Live spawn counter. */
   spawnCount = 0;
+  /**
+   * Historical `maxSpawns` from the last restored checkpoint (set for any
+   * finite checkpoint ceiling, matching or not). Surfaced in
+   * `budgetSnapshot()` so operators can see resume reconciliation without
+   * reading the JSON file; `ceilingMismatch` carries the actual mismatch signal.
+   */
+  checkpointMaxSpawnsAtResume;
+  ceilingMismatchAtResume = false;
   stateCheckpoint;
   sessionWriter;
   manifestTimer = null;
@@ -19473,11 +19526,11 @@ var FleetManager = class {
    * which cap was exceeded. Does NOT throw — the caller decides
    * how to surface the rejection.
    */
-  canSpawn(_config) {
+  canSpawn(config) {
     if (this.spawnDepth >= this.maxSpawnDepth) {
       return { kind: "max_spawn_depth", limit: this.maxSpawnDepth, observed: this.spawnDepth };
     }
-    if (this.spawnCount >= this.maxSpawns) {
+    if (!config.spawnBudgetExempt && this.spawnCount >= this.maxSpawns) {
       return { kind: "max_spawns", limit: this.maxSpawns, observed: this.spawnCount + 1 };
     }
     if (this.maxFleetCostUsd < Number.POSITIVE_INFINITY) {
@@ -19519,7 +19572,39 @@ var FleetManager = class {
       remainingTokens: Math.max(0, this.maxFleetTokens - usedTokens),
       maxCostUsd: this.maxFleetCostUsd,
       usedCostUsd,
-      remainingCostUsd: Math.max(0, this.maxFleetCostUsd - usedCostUsd)
+      remainingCostUsd: Math.max(0, this.maxFleetCostUsd - usedCostUsd),
+      ...this.checkpointMaxSpawnsAtResume !== void 0 ? { checkpointMaxSpawns: this.checkpointMaxSpawnsAtResume } : {},
+      ...this.ceilingMismatchAtResume ? { ceilingMismatch: true } : {}
+    };
+  }
+  /**
+   * Re-attach the on-disk checkpoint after a resume while keeping the live
+   * `maxSpawns` ceiling from construction (profile / flag / env). The
+   * historical `spawnCount` is deliberately NOT restored: the lifetime
+   * budget is scoped to this director run, so a restarted session gets a
+   * fresh budget instead of inheriting a (possibly exhausted) counter from
+   * before the restart. The checkpoint ceiling is rewritten to the live
+   * value so subsequent writes do not reintroduce a stale limit.
+   */
+  restoreFromCheckpoint(snapshot) {
+    const checkpointMax = typeof snapshot.maxSpawns === "number" && Number.isFinite(snapshot.maxSpawns) ? snapshot.maxSpawns : void 0;
+    const ceilingMismatch = checkpointMax !== void 0 && checkpointMax !== this.maxSpawns;
+    this.checkpointMaxSpawnsAtResume = checkpointMax;
+    this.ceilingMismatchAtResume = ceilingMismatch;
+    if (this.stateCheckpoint) {
+      if (snapshot.version === 1 && snapshot.directorRunId && snapshot.updatedAt) {
+        this.stateCheckpoint.resume(snapshot);
+      }
+      this.stateCheckpoint.applyLiveMaxSpawns(
+        Number.isFinite(this.maxSpawns) ? this.maxSpawns : void 0
+      );
+    }
+    return {
+      usedSpawns: this.spawnCount,
+      maxSpawns: this.maxSpawns,
+      remainingSpawns: Math.max(0, this.maxSpawns - this.spawnCount),
+      ...checkpointMax !== void 0 ? { checkpointMaxSpawns: checkpointMax } : {},
+      ceilingMismatch
     };
   }
   setLeaderContextPressure(tokens) {
@@ -19573,8 +19658,10 @@ var FleetManager = class {
     return this._usedNicknames;
   }
   /**
-   * Records a spawn: increments counter, stores metadata, updates state checkpoint,
-   * and schedules a debounced manifest write. Call AFTER the coordinator
+   * Records a spawn: stores metadata, updates state checkpoint, and schedules
+   * a debounced manifest write. Increments the lifetime spawn counter UNLESS
+   * the config is `spawnBudgetExempt` (ephemeral Chimera reviewer/cascade
+   * spawns do not consume the leader's budget). Call AFTER the coordinator
    * has successfully spawned the subagent.
    *
    * @param subagentId The subagent's id (from coordinator.spawn result)
@@ -19583,7 +19670,9 @@ var FleetManager = class {
    */
   recordSpawn(subagentId, config, priceLookup) {
     this.closing = false;
-    this.spawnCount += 1;
+    if (!config.spawnBudgetExempt) {
+      this.spawnCount += 1;
+    }
     this.subagentMeta.set(subagentId, {
       provider: config.provider,
       model: config.model
@@ -26467,6 +26556,9 @@ var KnowledgeGraph = class _KnowledgeGraph {
 };
 
 // src/coordination/task-dag.ts
+function isTerminalDagStatus(status) {
+  return status === "done" || status === "failed" || status === "skipped";
+}
 var TaskDAG = class {
   nodes = /* @__PURE__ */ new Map();
   handlers = /* @__PURE__ */ new Set();
@@ -26549,6 +26641,7 @@ var TaskDAG = class {
   complete(id, result) {
     const node = this.nodes.get(id);
     if (!node) return;
+    if (isTerminalDagStatus(node.status)) return;
     node.status = "done";
     node.result = result;
     node.completedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -26574,6 +26667,7 @@ var TaskDAG = class {
   fail(id, error) {
     const node = this.nodes.get(id);
     if (!node) return;
+    if (isTerminalDagStatus(node.status)) return;
     node.status = "failed";
     node.error = error;
     node.completedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -26602,6 +26696,7 @@ var TaskDAG = class {
   skip(id, reason) {
     const node = this.nodes.get(id);
     if (!node) return;
+    if (isTerminalDagStatus(node.status)) return;
     node.status = "skipped";
     node.completedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.invalidateCache();
@@ -26758,6 +26853,9 @@ var TaskDAG = class {
 
 // src/coordination/task-auctioneer.ts
 import { randomUUID as randomUUID18 } from "node:crypto";
+function isTerminalGoalStatus(status) {
+  return status === "done" || status === "failed";
+}
 var TaskAuctioneer = class {
   graph;
   fleet;
@@ -26953,6 +27051,7 @@ Priority: ${goal.priority}`,
   async complete(taskId, _result) {
     const goal = this.graph.get(taskId);
     if (!goal) return;
+    if (isTerminalGoalStatus(goal.status)) return;
     const agentId = goal.assignee ?? "unknown";
     this.agentTaskCount(agentId, -1);
     await this.graph.update(taskId, {
@@ -26993,6 +27092,7 @@ ${_result ?? "No result provided."}`
   async fail(taskId, error) {
     const goal = this.graph.get(taskId);
     if (!goal) return;
+    if (isTerminalGoalStatus(goal.status)) return;
     const agentId = goal.assignee ?? "unknown";
     this.agentTaskCount(agentId, -1);
     await this.graph.update(taskId, {

package/dist/coordination/multi-agent-coordinator.d.ts

@@ -186,6 +186,7 @@ export declare class DefaultMultiAgentCoordinator extends EventEmitter implement
      * `awaitTasks()` caller. Pushes the result and fires the event directly.
      */
     private emitPendingAborted;
+    private trimCompletedResults;
     private runDispatched;
     private executeWithTimeout;
     private recordCompletion;

package/dist/core/fallback-model.d.ts

@@ -90,7 +90,55 @@ export interface FallbackModelDeps {
      * the fallback chain.
      */
     statusTracker?: ProviderModelStatusTracker | undefined;
+    /**
+     * When set, the fallback chain pauses BEFORE attempting any fallback entry
+     * and emits `provider.fallback_pending`. The gate waits for a choice
+     * (manual pick or auto-countdown) before proceeding. This lets the UI show
+     * a modal with a countdown and manual model selection on every fallback hop.
+     *
+     * Returns the chosen model reference, or `null` to auto-switch to the next
+     * candidate (countdown expired or user accepted the default).
+     */
+    fallbackGate?: FallbackGateFn | undefined;
+    /**
+     * Seconds the UI counts down before auto-switching. Default: 7.
+     */
+    fallbackGateSeconds?: number | undefined;
 }
+/**
+ * Gate function invoked when the fallback chain is about to engage. It should
+ * emit `provider.fallback_pending` on the supplied `events` bus — carrying a
+ * unique `requestId` and a `timestamp` in the payload — wait for the UI's
+ * `provider.fallback_choice` emission echoing that `requestId` (or the
+ * countdown), and resolve with the selected model or `null` to accept the
+ * default next. See `createFallbackGate` in the CLI wiring for a reference
+ * implementation.
+ */
+export type FallbackGateFn = (params: {
+    events: EventBus;
+    sessionId: string | undefined;
+    from: {
+        providerId: string;
+        model: string;
+    };
+    status: number;
+    candidates: Array<{
+        providerId: string;
+        model: string;
+    }>;
+    autoSwitchSeconds: number;
+    /**
+     * Correlation id owned by the caller (the fallback-model extension). The
+     * gate MUST echo it in `provider.fallback_pending` so the UI's choice
+     * reply and the eventual `provider.fallback` completion event share the
+     * same id — clients use it to match the modal to the right gate when
+     * parallel requests fail on the same primary.
+     */
+    requestId: string;
+}) => Promise<{
+    providerId: string;
+    model: string;
+} | null>;
 export declare function fallbackProfileChain(config: Config, profileName: string | undefined): string[];
 export declare function smartDefaultFallbackChain(config: Config): string[];
 /**

package/dist/core/index.d.ts

@@ -5,11 +5,12 @@ export { ConversationState, type ReadonlyConversationState, type StateChange, ty
 export { InputBuilder, type InputBuilderEvent, type InputBuilderOptions, } from './input-builder.js';
 export { buildBtwBlock, consumeBtwNotes, pendingBtwCount, setBtwNote, } from './btw.js';
 export { type ContinuationInput, type ContinuationSource, detectContinueIntent, type ResolvedContinuation, resolveContinuation, } from './continue-intent.js';
-export { createFallbackModelExtension, effectiveFallbackChain, fallbackProfileChain, smartDefaultFallbackChain, } from './fallback-model.js';
+export { createFallbackModelExtension, effectiveFallbackChain, type FallbackGateFn, type FallbackModelDeps, fallbackProfileChain, smartDefaultFallbackChain, } from './fallback-model.js';
 export { FallbackProfileManager } from './fallback-profile-manager.js';
 export { formatModelRef, normalizeModelRef, parseModelRef, type ModelRef, } from './model-ref.js';
 export { DefaultSystemPromptBuilder, type DefaultSystemPromptBuilderOptions, type SystemBlockSource, } from './system-prompt-builder.js';
-export type { SystemInstructionVariant } from './instruction-bundle.js';
+export { type InstructionBundle, type InstructionBundlePaths, loadInstructionBundle, type SystemInstructionVariant, } from './instruction-bundle.js';
+export { type InstructionTemplateContext, renderInstructionLayer, } from './instruction-template.js';
 export { setQueuedMessagesSnapshot } from './queued-messages.js';
 export { runProviderWithRetry } from './provider-runner.js';
 //# sourceMappingURL=index.d.ts.map