@stigmer/runner 3.1.17 → 3.2.1

package/src/activities/execute-cursor/__tests__/turn-stream.test.ts

@@ -111,6 +111,7 @@ function buildDeps(overrides: Partial<CursorTurnStreamDeps> = {}): BuiltDeps {
     promptEstimatedTokens: 100,
     executionId: "exec-test",
     state,
+    maxCostUsd: 0,
     // CursorTurnStreamDeps
     status,
     accumulator,
@@ -261,6 +262,78 @@ describe("consumeCursorTurnStream", () => {
     });
   });
 
+  describe("cost-cap stop", () => {
+    it("cancels the run, stops the stream, and returns 'cost-cap' when onDelta flagged the overrun", async () => {
+      const state = newTurnStreamState();
+      state.costCapExceeded = true; // onDelta's write, simulated
+      const { deps, accumulator } = buildDeps({ state });
+      const run = mockRun([ev({ type: "assistant" }), ev({ type: "assistant" })]);
+
+      const reason = await consumeCursorTurnStream(run, deps);
+
+      expect(reason).toBe("cost-cap");
+      expect(run.cancel).toHaveBeenCalled();
+      // The break happens before the event is processed — no post-cap content.
+      expect(accumulator.processEvent).not.toHaveBeenCalled();
+    });
+
+    it("detects the flag mid-stream when onDelta sets it between events", async () => {
+      const state = newTurnStreamState();
+      const { deps, accumulator } = buildDeps({ state });
+      // Simulate onDelta's write landing between event 1 and event 2 — the
+      // realistic shape: a turn-ended usage delta crosses the cap while the
+      // loop is between stream events.
+      async function* gen(): AsyncIterable<SDKMessage> {
+        yield ev({ type: "assistant" });
+        state.costCapExceeded = true;
+        yield ev({ type: "assistant" });
+      }
+      const run: MockRun = {
+        stream: () => gen(),
+        supports: () => true,
+        cancel: vi.fn(async () => {}),
+      };
+
+      const reason = await consumeCursorTurnStream(run, deps);
+
+      expect(reason).toBe("cost-cap");
+      expect(run.cancel).toHaveBeenCalled();
+      // Event 1 was processed; event 2 hit the break before processing.
+      expect(accumulator.processEvent).toHaveBeenCalledTimes(1);
+    });
+
+    it("swallows the cancel-induced teardown rejection (expected, not a failure)", async () => {
+      const state = newTurnStreamState();
+      state.costCapExceeded = true;
+      const { deps } = buildDeps({ state });
+      // The break exits the for-await, which invokes the iterator's return();
+      // a cancelled SDK run can reject there. The catch must exempt cost-cap
+      // teardown exactly like stall/first-denial teardown.
+      const events = [ev({ type: "assistant" })];
+      let i = 0;
+      const run: MockRun = {
+        stream: () => ({
+          [Symbol.asyncIterator]: () => ({
+            next: async () =>
+              i < events.length
+                ? { value: events[i++], done: false as const }
+                : { value: undefined, done: true as const },
+            return: async () => {
+              throw new Error("run cancelled");
+            },
+          }),
+        }),
+        supports: () => true,
+        cancel: vi.fn(async () => {}),
+      };
+
+      const reason = await consumeCursorTurnStream(run, deps);
+
+      expect(reason).toBe("cost-cap");
+      expect(run.cancel).toHaveBeenCalled();
+    });
+  });
+
   it("returns 'stalled' and cancels the run when the stall watchdog fires", async () => {
     vi.useFakeTimers();
     // The generator yields one event, then awaits a promise resolved only by
@@ -305,6 +378,7 @@ describe("makeCursorTurnOnDelta", () => {
       promptEstimatedTokens: 10,
       executionId: "e",
       state,
+      maxCostUsd: 0,
     });
 
     expect(() => onDelta({ update: { type: "text" } as never })).not.toThrow();
@@ -322,6 +396,7 @@ describe("makeCursorTurnOnDelta", () => {
       promptEstimatedTokens: 10,
       executionId: "e",
       state,
+      maxCostUsd: 0,
     });
 
     expect(() => onDelta({ update: { type: "text" } as never })).toThrow("boom");
@@ -338,6 +413,7 @@ describe("makeCursorTurnOnDelta", () => {
       promptEstimatedTokens: 10,
       executionId: "e",
       state,
+      maxCostUsd: 0,
     });
 
     onDelta({ update: { type: "turn-ended", usage: { inputTokens: 100 } } as never });
@@ -346,4 +422,46 @@ describe("makeCursorTurnOnDelta", () => {
     expect(usageAccumulator.addTurn).toHaveBeenCalledTimes(2);
     expect(state.firstTurnAttributionLogged).toBe(true);
   });
+
+  it("flags costCapExceeded when a turn-ended usage delta pushes the estimate past the cap", () => {
+    const state = newTurnStreamState();
+    const usageAccumulator = {
+      ...stubUsageAccumulator(),
+      snapshot: vi.fn(() => ({ estimatedCostUsd: 0.51 })),
+    };
+    const onDelta = makeCursorTurnOnDelta({
+      usageAccumulator: usageAccumulator as never,
+      deltaEnricher: stubEnricher() as never,
+      heartbeat: vi.fn(),
+      promptEstimatedTokens: 10,
+      executionId: "e",
+      state,
+      maxCostUsd: 0.5,
+    });
+
+    onDelta({ update: { type: "turn-ended", usage: { inputTokens: 100 } } as never });
+
+    expect(state.costCapExceeded).toBe(true);
+  });
+
+  it("never flags costCapExceeded when no cap is configured", () => {
+    const state = newTurnStreamState();
+    const usageAccumulator = {
+      ...stubUsageAccumulator(),
+      snapshot: vi.fn(() => ({ estimatedCostUsd: 999 })),
+    };
+    const onDelta = makeCursorTurnOnDelta({
+      usageAccumulator: usageAccumulator as never,
+      deltaEnricher: stubEnricher() as never,
+      heartbeat: vi.fn(),
+      promptEstimatedTokens: 10,
+      executionId: "e",
+      state,
+      maxCostUsd: 0,
+    });
+
+    onDelta({ update: { type: "turn-ended", usage: { inputTokens: 100 } } as never });
+
+    expect(state.costCapExceeded).toBe(false);
+  });
 });

package/src/activities/execute-cursor/cost-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * ExecutionConfig.max_cost_usd enforcement for the Cursor harness.
+ *
+ * The native harness enforces the cap in middleware (cost-cap.ts): tools are
+ * blocked at the threshold and the model gets one final tool-free round to
+ * summarize. Cursor's only control point is cancelling the in-flight run, so
+ * here the cap is a HARD stop — the shared onDelta flags the overrun when a
+ * turn-ended usage delta lands, and the stream loop ends the run through the
+ * same clean-cancel pattern the stall watchdog and first-denial stop use.
+ * Slightly harsher than native by construction; both harnesses terminate with
+ * the same honesty semantics (EXECUTION_TERMINATED, work checkpointed, the
+ * conversation continues on the next message — the recursion-limit precedent
+ * in execute-deep-agent/streaming-terminal.ts).
+ *
+ * The running figure is the usage accumulator's local pricing-table estimate
+ * (authoritative billing is the BiDi proxy). That is the same estimation
+ * basis the native cost-cap middleware uses — acceptable for a safety net.
+ */
+
+/**
+ * Whether the per-execution cost budget has been exhausted.
+ *
+ * `maxCostUsd <= 0` means "no cap" (the proto contract: 0/unset disables the
+ * ceiling). The boundary is inclusive: reaching the cap exactly stops the run,
+ * matching the native middleware's `runningCost >= maxCostUsd` check.
+ */
+export function costCapExceeded(maxCostUsd: number, estimatedCostUsd: number): boolean {
+  return maxCostUsd > 0 && estimatedCostUsd >= maxCostUsd;
+}
+
+/**
+ * Stable prefix of the cost-limit terminal error. Mirrors the cross-repo
+ * pattern of TOOL_CALL_LIMIT_ERROR_PREFIX (streaming-terminal.ts): consumers
+ * that need to distinguish "ran out of cost budget" from other TERMINATED
+ * causes can match on this prefix, because AgentExecutionStatus carries no
+ * structured termination reason. Do not reword without checking consumers.
+ */
+export const COST_LIMIT_ERROR_PREFIX = "Agent reached the cost limit";
+
+/** The terminal `status.error` for a cost-cap stop. */
+export function formatCostLimitError(maxCostUsd: number, estimatedCostUsd: number): string {
+  return (
+    `${COST_LIMIT_ERROR_PREFIX} for this message ` +
+    `(~$${estimatedCostUsd.toFixed(4)} of the $${maxCostUsd.toFixed(2)} budget). ` +
+    `Send another message to continue.`
+  );
+}
+
+/**
+ * User-facing system message for a cost-cap stop. Parallel to the
+ * recursion-limit copy: honest about the limit, clear that nothing is lost.
+ */
+export const COST_LIMIT_USER_COPY =
+  "The agent reached the cost limit for this message. " +
+  "Work completed so far has been saved. " +
+  "Send another message to continue where the agent left off.";

package/src/activities/execute-cursor/index.ts

@@ -90,6 +90,7 @@ import {
   type CursorTurnStreamDeps,
   type TurnOnDeltaDeps,
 } from "./turn-stream.js";
+import { formatCostLimitError, COST_LIMIT_USER_COPY } from "./cost-guard.js";
 import {
   captureFileChangeProgress,
   newProgressCaptureState,
@@ -950,6 +951,7 @@ async function executeCursorInner(
     // The shared onDelta only needs the usage/enricher/heartbeat/state subset,
     // and it is wired at SEND time — before the accumulator exists — so it takes
     // the narrow deps. The primary send and both retry sends reuse this object.
+    const maxCostUsd = spec.executionConfig?.maxCostUsd ?? 0;
     const onDeltaDeps: TurnOnDeltaDeps = {
       usageAccumulator,
       deltaEnricher,
@@ -957,6 +959,7 @@ async function executeCursorInner(
       promptEstimatedTokens,
       executionId,
       state: turnState,
+      maxCostUsd,
     };
 
     // Periodic heartbeat keeps Temporal informed during silent SDK operations
@@ -1067,6 +1070,7 @@ async function executeCursorInner(
         turnState.pauseDetected ||
         workerShutdownDetected ||
         turnState.stallDetected ||
+        turnState.costCapExceeded ||
         Context.current().cancellationSignal.aborted
       ) {
         accumulator.cancelInProgressSubAgents();
@@ -1117,6 +1121,32 @@ async function executeCursorInner(
         return { kind: "return" };
       }
 
+      // Cost cap (cost-guard.ts): onDelta flagged the overrun and the loop
+      // cancelled the run. EXECUTION_TERMINATED, not FAILED — the platform
+      // deliberately stopped the run, work is checkpointed, and the
+      // conversation continues on the next message (the recursion-limit
+      // precedent in execute-deep-agent/streaming-terminal.ts). RETURN (not
+      // throw): a Temporal retry would re-run the identical prompt and burn
+      // the same budget again.
+      if (turnState.costCapExceeded) {
+        const estimated = usageAccumulator.snapshot().estimatedCostUsd;
+        status.phase = ExecutionPhase.EXECUTION_TERMINATED;
+        status.error = formatCostLimitError(maxCostUsd, estimated);
+        status.completedAt = utcTimestamp();
+        status.messages.push(create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_SYSTEM,
+          content: COST_LIMIT_USER_COPY,
+          timestamp: utcTimestamp(),
+        }));
+        await persist(status);
+        try { resolution.agent.close(); } catch { /* best effort */ }
+        console.warn(
+          `ExecuteCursor terminated (cost cap): execution=${executionId}, ` +
+          `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`,
+        );
+        return { kind: "return" };
+      }
+
       // Worker shutdown: the runner-manager aborted the shutdown signal. NOT a
       // user pause. Checked via the shutdown signal directly so a retry (whose
       // periodic heartbeat is already stopped) still classifies it correctly.

package/src/activities/execute-cursor/turn-stream.ts

@@ -45,6 +45,7 @@ import type { TodoTracker } from "./todo-tracker.js";
 import type { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
 import type { UsageAccumulator } from "./usage-accumulator.js";
 import type { createCursorEventRecorder } from "./cursor-event-recorder.js";
+import { costCapExceeded } from "./cost-guard.js";
 
 /**
  * The subset of the Cursor SDK `Run` the stream phase consumes. Kept structural
@@ -69,7 +70,8 @@ export type TurnStreamReason =
   | "paused"
   | "stalled"
   | "first-denial"
-  | "platform-stop";
+  | "platform-stop"
+  | "cost-cap";
 
 /**
  * Single owner for every flag the turn's stream produces. Before this, these
@@ -97,6 +99,8 @@ export interface TurnStreamState {
   denialCancelSettled: Promise<void> | undefined;
   /** Written by: the loop (a platform STOP signal from persist). Read by: the loop + epilogue. */
   platformStopSignaled: boolean;
+  /** Written by: onDelta (a turn-ended usage delta pushed the estimate past max_cost_usd). Read by: the loop (cancel + break) + epilogue. */
+  costCapExceeded: boolean;
   /** Written by: the loop (a stream ERROR status event) + the retry setup (reset). Read by: error classification. */
   streamErrorMessage: string | undefined;
   /** Written by: the loop (each tool_call). Read by: the stall-watchdog (message enrichment). */
@@ -118,6 +122,7 @@ export function newTurnStreamState(): TurnStreamState {
     denialLedgerDirty: false,
     denialCancelSettled: undefined,
     platformStopSignaled: false,
+    costCapExceeded: false,
     streamErrorMessage: undefined,
     lastToolName: undefined,
     eventCount: 0,
@@ -139,6 +144,13 @@ export interface TurnOnDeltaDeps {
   readonly promptEstimatedTokens: number;
   readonly executionId: string;
   readonly state: TurnStreamState;
+  /**
+   * ExecutionConfig.max_cost_usd — 0/unset disables the cap. Checked by
+   * onDelta after each turn-ended usage delta lands (the only point the
+   * running estimate advances); the loop performs the actual run.cancel().
+   * See cost-guard.ts for the semantics.
+   */
+  readonly maxCostUsd: number;
 }
 
 export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
@@ -170,7 +182,7 @@ export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
 export function makeCursorTurnOnDelta(
   deps: TurnOnDeltaDeps,
 ): (event: { update: InteractionUpdate }) => void {
-  const { usageAccumulator, deltaEnricher, heartbeat, promptEstimatedTokens, executionId, state } =
+  const { usageAccumulator, deltaEnricher, heartbeat, promptEstimatedTokens, executionId, state, maxCostUsd } =
     deps;
   return ({ update }) => {
     // Reset the stall timer on the delta channel too: a long model generation
@@ -180,6 +192,19 @@ export function makeCursorTurnOnDelta(
     if (update.type === "turn-ended" && update.usage) {
       usageAccumulator.addTurn(update.usage);
 
+      // max_cost_usd enforcement (cost-guard.ts): the running estimate only
+      // advances here, so this is the single check point. onDelta cannot reach
+      // the run — the loop reads the flag and performs the clean cancel.
+      if (!state.costCapExceeded
+          && costCapExceeded(maxCostUsd, usageAccumulator.snapshot().estimatedCostUsd)) {
+        state.costCapExceeded = true;
+        console.warn(
+          `ExecuteCursor cost cap exceeded: execution=${executionId}, ` +
+            `estimatedCostUsd=${usageAccumulator.snapshot().estimatedCostUsd.toFixed(4)}, ` +
+            `maxCostUsd=${maxCostUsd.toFixed(2)}`,
+        );
+      }
+
       if (!state.firstTurnAttributionLogged) {
         state.firstTurnAttributionLogged = true;
         const sdkInputTokens = update.usage.inputTokens ?? 0;
@@ -272,6 +297,26 @@ export async function consumeCursorTurnStream(
       }
       if (state.stallDetected) break;
 
+      // Cost cap (cost-guard.ts): onDelta flagged the overrun on a turn-ended
+      // usage delta; end the run through the same clean-cancel pattern as the
+      // stall watchdog and the first-denial stop. Fire-and-forget is correct
+      // here — nothing downstream waits on this turn's agent (unlike the
+      // first-denial stop, whose ledger read needs a stopped agent).
+      if (state.costCapExceeded) {
+        console.log(
+          `ExecuteCursor stopping stream at cost cap: execution=${executionId}`,
+        );
+        if (run.supports?.("cancel")) {
+          void run.cancel().catch((cancelErr) => {
+            console.warn(
+              `ExecuteCursor run.cancel() after cost cap failed (non-fatal): execution=${executionId}, ` +
+                `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`,
+            );
+          });
+        }
+        break;
+      }
+
       // Progress: reset the stall timer on every stream event.
       state.stallWatchdog.recordActivity();
       if (event.type === "tool_call" && typeof event.name === "string") {
@@ -397,14 +442,18 @@ export async function consumeCursorTurnStream(
       }
     }
   } catch (streamErr) {
-    // run.cancel() — from the stall watchdog or the first-denial stop — can make
-    // the stream iterator reject as it tears down; that is the expected teardown
-    // for both, so swallow it and fall through. Anything else is a genuine stream
-    // failure — rethrow it to the activity's error handler.
-    if (!state.stallDetected && !state.firstDenialDetected) throw streamErr;
+    // run.cancel() — from the stall watchdog, the first-denial stop, or the
+    // cost-cap stop — can make the stream iterator reject as it tears down;
+    // that is the expected teardown for all three, so swallow it and fall
+    // through. Anything else is a genuine stream failure — rethrow it to the
+    // activity's error handler.
+    if (!state.stallDetected && !state.firstDenialDetected && !state.costCapExceeded) {
+      throw streamErr;
+    }
     console.warn(
       `ExecuteCursor stream ended via cancel: execution=${executionId}, ` +
-        `stall=${state.stallDetected}, firstDenial=${state.firstDenialDetected}`,
+        `stall=${state.stallDetected}, firstDenial=${state.firstDenialDetected}, ` +
+        `costCap=${state.costCapExceeded}`,
     );
   } finally {
     state.stallWatchdog.stop();
@@ -412,10 +461,12 @@ export async function consumeCursorTurnStream(
 
   // Report why the stream ended, in the same precedence the activity's epilogue
   // applies: a stall (an EXECUTION_FAILED terminal) outranks everything; a
-  // platform stop and a first denial are distinct proceed/return outcomes; a
-  // pause is the fallback for a cancellation with no other cause.
+  // platform stop, a cost-cap stop, and a first denial are distinct
+  // return/proceed outcomes; a pause is the fallback for a cancellation with
+  // no other cause.
   if (state.stallDetected) return "stalled";
   if (state.platformStopSignaled) return "platform-stop";
+  if (state.costCapExceeded) return "cost-cap";
   if (state.firstDenialDetected) return "first-denial";
   if (state.pauseDetected || isCancelled()) return "paused";
   return "completed";

package/src/activities/execute-deep-agent/__tests__/streaming-terminal.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  TOOL_CALL_LIMIT_ERROR_PREFIX,
+  handleRecursionLimit,
+} from "../streaming-terminal.js";
+import type { ExecutionStatusWriter } from "../../../shared/execution-status-writer.js";
+
+function writerWith(status = create(AgentExecutionStatusSchema, {})): ExecutionStatusWriter {
+  return { currentStatus: status } as ExecutionStatusWriter;
+}
+
+describe("handleRecursionLimit", () => {
+  it("terminates with work saved and a continue prompt", () => {
+    const writer = writerWith();
+
+    const result = handleRecursionLimit(writer, 42, [], []);
+
+    expect(writer.currentStatus.phase).toBe(ExecutionPhase.EXECUTION_TERMINATED);
+    expect(writer.currentStatus.completedAt).toBeDefined();
+    expect(result.terminalStatus).toBeDefined();
+  });
+
+  it("pins the cross-repo error prefix that Stigmer Cloud's channel delivery matches on", () => {
+    // ChannelReplyExtractor (stigmer-cloud) distinguishes budget-limit
+    // TERMINATED from other causes by this prefix — there is no structured
+    // termination reason on AgentExecutionStatus. A reword here silently
+    // downgrades channel users from the friendly limit copy to generic
+    // error copy, so the prefix is pinned on both sides.
+    expect(TOOL_CALL_LIMIT_ERROR_PREFIX).toBe("Agent reached the tool-call limit");
+
+    const writer = writerWith();
+    handleRecursionLimit(writer, 7, [], []);
+
+    expect(writer.currentStatus.error).toMatch(/^Agent reached the tool-call limit/);
+    expect(writer.currentStatus.error).toContain("Send another message to continue.");
+  });
+});

package/src/activities/execute-deep-agent/setup.ts

@@ -73,6 +73,10 @@ import {
 import { filterSkills, SKILL_COUNT_THRESHOLD } from "../../shared/skill-relevance.js";
 import { injectAttachments } from "./attachment-injector.js";
 import { transformAndCompileSubagents } from "./subagent-transformer.js";
+import {
+  resolveRecursionLimit,
+  UNBOUNDED_ADVISORY_RECURSION_LIMIT,
+} from "../../shared/tool-rounds.js";
 
 export interface SetupResult {
   readonly agentGraph: AgentGraph;
@@ -472,6 +476,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       : null;
 
     const maxCostUsd = execConfig?.maxCostUsd ?? 0;
+    // max_tool_rounds → recursion limit (proto contract: 0/unset = unlimited,
+    // set = clamped 10–1000 and enforced). One resolved value feeds BOTH the
+    // hard stop on the invoke config below and the budget middleware's ~80%
+    // wrap-up advisory, so the warning and the enforcement can never disagree.
+    const recursionLimit = resolveRecursionLimit(execConfig?.maxToolRounds);
     const { middleware, gracefulStop, costCap: costCapMiddleware } = buildMiddlewareStack({
       loopDetection: {
         historySize: 20,
@@ -479,9 +488,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         totalThreshold: 20,
       },
       executionBudget: {
-        recursionLimit: execConfig?.maxToolRounds
-          ? execConfig.maxToolRounds * 6
-          : 6000,
+        recursionLimit: recursionLimit ?? UNBOUNDED_ADVISORY_RECURSION_LIMIT,
         warningPct: 80,
       },
       toolTruncation: {
@@ -600,6 +607,12 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
 
     const langgraphConfig: Record<string, unknown> = {
       configurable: { thread_id: threadId },
+      // Hard enforcement of max_tool_rounds (null = unlimited, the default):
+      // when the graph exhausts this, the streaming loop's GraphRecursionError
+      // handler terminates gracefully with work saved ("send another message
+      // to continue"). The middleware's wrap-up advisory fires at ~80% of the
+      // same value, so a healthy run finishes normally before ever hitting it.
+      ...(recursionLimit !== null ? { recursionLimit } : {}),
     };
 
     const streamVersion: "v2" | "v3" =

package/src/activities/execute-deep-agent/streaming-terminal.ts

@@ -57,6 +57,16 @@ export function handleStop(
   };
 }
 
+/**
+ * Stable prefix of the recursion-limit terminal error. This is a cross-repo
+ * contract: consumers that need to distinguish "ran out of tool-call budget"
+ * from other TERMINATED causes (e.g. Stigmer Cloud's ChannelReplyExtractor,
+ * which shows channel users a friendly limit message instead of generic
+ * error copy) match on this prefix, because AgentExecutionStatus carries no
+ * structured termination reason. Do not reword without updating them.
+ */
+export const TOOL_CALL_LIMIT_ERROR_PREFIX = "Agent reached the tool-call limit";
+
 export function handleRecursionLimit(
   writer: ExecutionStatusWriter,
   eventsProcessed: number,
@@ -67,7 +77,7 @@ export function handleRecursionLimit(
   status.phase = ExecutionPhase.EXECUTION_TERMINATED;
   status.completedAt = utcTimestamp();
   status.error =
-    `Agent reached the tool-call limit after processing ${eventsProcessed} events. ` +
+    `${TOOL_CALL_LIMIT_ERROR_PREFIX} after processing ${eventsProcessed} events. ` +
     `Send another message to continue.`;
   status.messages.push(create(AgentMessageSchema, {
     type: MessageType.MESSAGE_SYSTEM,

package/src/main.ts

@@ -22,6 +22,7 @@ import { createHash } from "node:crypto";
 import { readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { createInterface } from "node:readline";
+import { preflightNodeRuntime } from "./preflight.js";
 import { loadConfig } from "./config.js";
 import { initTracing, initMetrics } from "./otel.js";
 import { createStigmerRunner } from "./runner.js";
@@ -283,6 +284,22 @@ function collectTsFiles(dir: string, files: string[] = []): string[] {
 // ─── Entry Point ─────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
+  // Runtime capability gate FIRST: everything below (config load, manager /
+  // static init) eventually imports node:sqlite via the checkpointer chain,
+  // and the raw ERR_UNKNOWN_BUILTIN_MODULE from that import is inscrutable.
+  // In manager mode the host reads the first stdout line as the handshake, so
+  // a fatal IPC error here surfaces verbatim in the host's UI (see
+  // negotiate_ready in crates/stigmer-runner-host/src/host.rs).
+  const preflightError = preflightNodeRuntime();
+  if (preflightError !== null) {
+    if (process.env.STIGMER_RUNNER_MODE === "manager") {
+      sendIpc({ type: "error", message: preflightError, fatal: true });
+    } else {
+      writeStderr(`${preflightError}\n`);
+    }
+    process.exit(1);
+  }
+
   checkBuildFreshness();
 
   const config = loadConfig();

package/src/preflight.ts

@@ -0,0 +1,59 @@
+/**
+ * Boot preflight: verify the Node runtime can run this runner BEFORE the deep
+ * import chains load.
+ *
+ * Why this exists: the durable local checkpointer (shared/checkpointer/
+ * sqlite-saver.ts) imports Node's built-in `node:sqlite` at module load time,
+ * and both the manager and the static runner eagerly import that chain during
+ * initialization. On a Node without unflagged `node:sqlite` — anything below
+ * 22.13, and 23.0–23.3 (the 23.x line only gained it in 23.4) — that import
+ * throws a raw `ERR_UNKNOWN_BUILTIN_MODULE` deep inside init, which surfaces
+ * to hosts (e.g. the desktop Run dialog) as an inscrutable internal error.
+ * This gate turns it into an actionable "your Node cannot run the runner"
+ * message on the very first line of output.
+ *
+ * Why a capability probe and not a version check: version gating is exactly
+ * what let this failure ship — the CLI's node resolver encoded a 22.13 floor
+ * but its table missed the 23.0–23.3 gap. Probing the capability itself
+ * ("can this binary provide node:sqlite?") cannot drift. The version floors
+ * appear only in the human-facing message, where staleness is harmless.
+ *
+ * The gate is unconditional (not checkpointer-type-dependent): the eager
+ * import chain needs `node:sqlite` to LOAD regardless of configuration, so
+ * the gate mirrors the actual load-time requirement.
+ */
+
+/**
+ * True when this Node binary provides the built-in `node:sqlite`.
+ *
+ * Probe notes (each verified against real binaries; do not "simplify"):
+ * - `process.getBuiltinModule(id)` returns the module when present and
+ *   `undefined` when absent — no throw. The `?.` guard covers Nodes older
+ *   than 22.3, where `getBuiltinModule` itself does not exist (there
+ *   `node:sqlite` is absent too, so reporting "unsupported" is correct).
+ * - `module.builtinModules` is NOT a valid alternative: it omits experimental
+ *   builtins, so it reports no `sqlite` even on Nodes where `node:sqlite`
+ *   loads fine (e.g. 22.13+). Gating on it would reject every supported Node.
+ * - The probe loads the module, which on 22.x emits a one-time
+ *   `ExperimentalWarning` on stderr. The runner loads `node:sqlite` eagerly
+ *   moments later anyway, so this only moves that warning to boot.
+ */
+export function isNodeSqliteAvailable(): boolean {
+  return process.getBuiltinModule?.("node:sqlite") !== undefined;
+}
+
+/**
+ * Check the current runtime, returning `null` when it can run the runner or
+ * an actionable operator-facing message when it cannot. The probe is
+ * injectable so tests can exercise the failure path on a supported Node.
+ */
+export function preflightNodeRuntime(
+  isSqliteAvailable: () => boolean = isNodeSqliteAvailable,
+): string | null {
+  if (isSqliteAvailable()) return null;
+  return (
+    `Node v${process.versions.node} does not provide the built-in node:sqlite ` +
+    `module required by the runner's durable checkpointer. ` +
+    `Use Node >= 22.13 (22.x line) or >= 23.4 (23.x and later).`
+  );
+}