@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/harness/types.ts

@@ -54,8 +54,14 @@
  *  - No persist cadence. The runtime's chokepoint is single-flight and
  *    unconditional at settle; WHEN a streaming turn asks for a write is the
  *    adapter's (`shared/persist-decision.ts` over its own dirty flags, since
- *    what counts as a discrete change is engine knowledge), until S3 lifts
- *    the file-review capture and can revisit with both loops in view.
+ *    what counts as a discrete change is engine knowledge). Revisited with
+ *    both loops in view at S3 M4 and kept (Q-S3-13): the cadence RULE is
+ *    shared, the timing is the engine's.
+ *  - No capture. The file-review capture is the runtime's whole
+ *    (`harness/capture.ts`): the baseline before `runTurn`, the candidate
+ *    after it, the stamp, the review decision. The one capture fact an
+ *    adapter holds — what its engine observed touching CAS-owned paths — it
+ *    binds through `TurnSink.bindCasObservations`.
  *
  * Module shape follows `shared/checkpointer/`: `types.ts`, `capabilities.ts`,
  * `registry.ts`, no barrel.
@@ -82,6 +88,7 @@ import type { EffectiveThinkingMode } from "../shared/thinking-mode.js";
 import type { SenderIdentity } from "../shared/sender-identity.js";
 import type { DeclaredPreferencesContent } from "../shared/declared-preferences.js";
 import type { RecalledMemoriesContent } from "../shared/recalled-memories.js";
+import type { CasTouchedReader } from "../shared/filereview/cas-touched.js";
 import type { HarnessCapabilities } from "./capabilities.js";
 
 /**
@@ -196,6 +203,21 @@ export interface TurnMcp {
   readonly policies: ReadonlyMap<string, MergedToolPolicy>;
 }
 
+/**
+ * The mounted skills (phase 5), each under the session's platform dir and
+ * reachable from the workspace through its `.stigmer` link; the harness
+ * renders them into its prompt shapes. Resolved per OWNER, because a
+ * sub-agent's skills are its own prompt's, not the root's: the root's are
+ * `blueprint.mergedSkillRefs` (agent plus session), a sub-agent's are its
+ * `skillRefs` on the blueprint, keyed by the sub-agent's name (the key its
+ * compiler uses). A sub-agent with no skills has no entry. Empty for a
+ * harness whose `capabilities.subAgents` is false.
+ */
+export interface TurnSkills {
+  readonly root: readonly SkillMetadata[];
+  readonly bySubAgent: ReadonlyMap<string, readonly SkillMetadata[]>;
+}
+
 /** The turn's explicit inputs (phase 5b), resolved into the workspace with the vision facts derived once. */
 export interface TurnAttachments {
   readonly results: readonly ResolvedAttachment[];
@@ -245,9 +267,13 @@ export interface TurnStandingContext {
  * `engine-minted` harness's first turn (nothing minted yet) and the id the
  * adapter bound through {@link TurnSink.bindHarnessState} on every later
  * invocation; the runtime-minted id on every turn of a `deterministic`
- * harness. An adapter derives create-vs-resume from it and its own state
- * through `turn-context.ts`'s `isReinvocation`; the contract carries no flag
- * because the two harnesses would derive it differently.
+ * harness. An adapter derives create-vs-resume for its ENGINE from it and its
+ * own state; the runtime derives its own reinvocation fact (the seed, the
+ * reconcile) in `turn-context.ts`'s `isReinvocation`, one arm per
+ * `stateIdSource`. The contract carries no flag because the two readings
+ * answer different questions ("does the engine hold state for this session"
+ * vs "does this execution have a transcript") and one name over two meanings
+ * would be the divergence a contract exists to prevent.
  *
  * Adapter-only facts (the Cursor mode, the service-tier params, the seeded
  * sub-agent rows) are read by the adapter from these records, never resolved
@@ -278,8 +304,7 @@ export interface TurnInput extends NormalizedActivityInput {
   readonly environment: TurnEnvironment;
   readonly workspace: TurnWorkspace;
   readonly mcp: TurnMcp;
-  /** The mounted skills (phase 5): each under the session's platform dir, reachable from the workspace through its `.stigmer` link; the harness renders them into its prompt. */
-  readonly skills: readonly SkillMetadata[];
+  readonly skills: TurnSkills;
   readonly attachments: TurnAttachments;
   /** Approved whole-file writes the runtime applied itself this turn (exact-apply); the harness issues no grant for them. */
   readonly appliedToolCallIds: ReadonlySet<string>;
@@ -304,11 +329,10 @@ export interface TurnInput extends NormalizedActivityInput {
  * the adapter appends the engine's transcript rows (assistant messages,
  * tool-call rows and their approval status, sub-agent rows, todos); the
  * runtime writes the phase, the terminal system messages, `streamingUsage`,
- * artifacts, write-backs and the file-review projection. An adapter never
- * writes a phase or a terminal copy: those are Temporal semantics the
- * runtime owns once. (The file-review boundary itself is the adapter's until
- * S3 lifts both harnesses' captures together; `execute-cursor/adapter.ts`
- * says so.)
+ * artifacts, write-backs, `fileChangeProgress`, the file-review ledger
+ * events and the change-set stamp on a flowed edit row (S3 M4,
+ * `harness/capture.ts`). An adapter never writes a phase or a terminal copy:
+ * those are Temporal semantics the runtime owns once.
  */
 export interface TurnSink {
   /**
@@ -398,6 +422,26 @@ export interface TurnSink {
    * that error and executes nothing further.
    */
   bindHarnessState(harnessStateId: string): Promise<void>;
+
+  /**
+   * What the engine observed touching CAS-owned paths this turn — gitignored
+   * paths in a git tree, every path in a non-git one: the pre-turn bytes of
+   * each first-touched path and the paths the gate blocked as secrets
+   * (`shared/filereview/cas-touched.ts`). The one fact about a turn's file
+   * changes the runtime cannot read from the tree: the pre-edit bytes exist
+   * only at mutation time, in whatever sits between the engine and the disk
+   * (the deep-agent's filesystem backend and gate, the Cursor hook's
+   * sidecar). The runtime reads the AFTER bytes itself and owns everything
+   * else of the capture (`harness/capture.ts`): the baseline, the progress,
+   * the candidate, the stamp, the review decision.
+   *
+   * Bound once, before the first persist, as `bindHarnessState` is; the
+   * runtime pulls it at each progress refresh and at the turn boundary, so
+   * it must return an atomic snapshot (copy live state before any await). A
+   * harness that observes nothing binds nothing and gets git-only capture.
+   * Never throws.
+   */
+  bindCasObservations(read: CasTouchedReader): void;
 }
 
 /**
@@ -460,6 +504,15 @@ export type FailureSurface = "engine" | "actionable" | "internal";
  *    takes, `cause` is for the log. The runtime persists FAILED and RETURNS
  *    (Temporal does not retry a returned activity; re-running the same
  *    prompt would fail the same way).
+ *  - `tool_call_limit`: the engine exhausted the tool-round budget the
+ *    execution set (`max_tool_rounds`, `shared/tool-rounds.ts`) and stopped
+ *    at a step boundary with its work checkpointed. Not `failed`: the
+ *    platform deliberately stopped the run, and the conversation continues
+ *    on the next message. The runtime writes TERMINATED with the cross-repo
+ *    prefix and the user copy, and RETURNS (a retry would spend the same
+ *    budget again). Every surveyed SDK ends a turn on a budget with a
+ *    distinct outcome (Claude's `maxTurns` subtype, Codex's turn reason), so
+ *    this is a cross-harness fact, not an engine quirk.
  *  - `interrupted`: `sink.stopSignal` aborted and the adapter stopped. WHY it
  *    aborted is the runtime's evidence (its watchdog, its accounting, its
  *    chokepoint, the cancellation it was delivered), so no reason rides here;
@@ -469,5 +522,6 @@ export type TurnOutcome =
   | { readonly kind: "completed" }
   | { readonly kind: "cancelled" }
   | { readonly kind: "awaiting_approval" }
+  | { readonly kind: "tool_call_limit" }
   | { readonly kind: "failed"; readonly message: string; readonly surface: FailureSurface; readonly cause?: unknown }
   | { readonly kind: "interrupted" };

package/src/harness-adapters.ts

@@ -1,7 +1,8 @@
 /**
  * The harnesses this worker serves: one registry row per adapter, in boot
  * order. The ONE place an adapter's factory is named outside its own
- * directory.
+ * directory; both composition roots read this table and nothing else to
+ * learn which harnesses exist.
  *
  * Lives at the source root, beside the composition roots that read it, and
  * not in `harness/registry.ts`: a row imports its adapter from
@@ -11,20 +12,27 @@
  *
  * ORDER IS LOAD-BEARING (`registry.ts` `bootHarnesses`): the Cursor
  * adapter's interceptors must patch `node:http2` before anything dials the
- * control plane, so it boots first. The native deep-agent harness joins this
- * table at S3 of the harness runtime program; until then both roots import
- * its activities directly beside this table's.
+ * control plane, so it boots first. The native deep-agent adapter boots
+ * second; its `boot` registers the deepagents harness profiles and loads
+ * LangChain, both after the patch (S3 M2b, 2026-09-13; until then the roots
+ * imported the native orchestrator directly beside this table).
  *
  * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT- AND SDK-FREE. The roots
  * import it BEFORE they boot the harnesses, and the Cursor adapter's boot is
  * where `node:http2` is patched and `@cursor/sdk` first loaded; an adapter
- * factory that imported its SDK statically would defeat both. An adapter
- * named here loads its vendor SDK inside `boot` (`adapter.ts` shows the
- * shape). `__tests__/harness-boot-order.test.ts` boots a fresh process
- * through this module and fails if the graph regresses.
+ * factory that imported its SDK statically would defeat both. Every adapter
+ * named here loads its vendor SDK inside `boot` (`execute-cursor/adapter.ts`
+ * and `execute-deep-agent/adapter.ts` show the shape; each has a fence that
+ * walks its static graph). `__tests__/harness-boot-order.test.ts` boots a
+ * fresh process through this module — both rows — and fails if the graph
+ * regresses.
  */
 
 import { createCursorAdapter } from "./activities/execute-cursor/adapter.js";
+import { createDeepAgentAdapter } from "./activities/execute-deep-agent/adapter.js";
 import type { HarnessRow } from "./harness/registry.js";
 
-export const HARNESS_ADAPTERS: readonly HarnessRow[] = [{ harness: "cursor", adapter: createCursorAdapter() }];
+export const HARNESS_ADAPTERS: readonly HarnessRow[] = [
+  { harness: "cursor", adapter: createCursorAdapter() },
+  { harness: "deep-agent", adapter: createDeepAgentAdapter() },
+];

package/src/middleware/__tests__/approval-gate.test.ts

@@ -48,7 +48,7 @@ describe("ApprovalGateMiddleware", () => {
   });
 
   // The global pre-arm (spec.auto_approve_all) is no longer the gate's concern:
-  // setup.ts simply does not install the gate when it is set. The gate is always
+  // turn-setup.ts simply does not install the gate when it is set. The gate is always
   // active once built; scoped leases (below) decide what it lets through.
 
   it("auto-approves a built-in whose category holds a run-lifetime lease", async () => {

package/src/middleware/__tests__/cost-advisory.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The cost advisory: prices each model call off `usage_metadata`, keeps one
+ * running total the sub-agent views share, and warns the model ONCE at the
+ * configured share of `max_cost_usd`. Nothing here caps: the enforcement is
+ * the turn runtime's (`shared/__tests__/cost-guard.test.ts`,
+ * `harness/__tests__/run-turn.test.ts`'s cost-cap arm). Until S3 M2b this
+ * file was `cost-cap.test.ts` and also pinned the in-graph tool block and
+ * the "exceeded" message — retired with that half (Q-S3-3, Q-M2b-9).
+ */
+
+import { describe, it, expect } from "vitest";
+import { AIMessage } from "@langchain/core/messages";
+import { createCostAdvisoryMiddleware } from "../cost-advisory.js";
+
+function stateWithUsage(inputTokens: number, outputTokens: number, cacheRead = 0): Record<string, unknown> {
+  const aiMsg = new AIMessage({ content: "response" });
+  (aiMsg as unknown as Record<string, unknown>).usage_metadata = {
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    input_token_details: { cache_read: cacheRead },
+  };
+  return { messages: [aiMsg] };
+}
+
+const BASE_CONFIG = {
+  maxCostUsd: 1.0,
+  inputPricePerMillion: 3.0,
+  outputPricePerMillion: 15.0,
+  cacheReadPricePerMillion: 0.3,
+  warningPct: 80,
+};
+
+function warningOf(result: unknown): string | undefined {
+  const messages = (result as { messages?: Array<{ content: unknown }> } | undefined)?.messages;
+  return messages?.[0] ? String(messages[0].content) : undefined;
+}
+
+describe("CostAdvisoryMiddleware", () => {
+  it("prices a model call from usage_metadata", () => {
+    const mw = createCostAdvisoryMiddleware(BASE_CONFIG);
+    mw.afterModel!(stateWithUsage(1000, 500), {});
+    // (1000 * 3 + 500 * 15) / 1_000_000 = 0.0105
+    expect(mw.runningCost).toBeCloseTo(0.0105, 4);
+  });
+
+  it("prices cache reads at their own rate when configured", () => {
+    const mw = createCostAdvisoryMiddleware(BASE_CONFIG);
+    mw.afterModel!(stateWithUsage(1000, 500, 600), {});
+    // regular input 400 * 3 + cache 600 * 0.3 + output 500 * 15 = 8,880 / 1M
+    expect(mw.runningCost).toBeCloseTo(0.00888, 4);
+  });
+
+  it("accumulates across model calls", () => {
+    const mw = createCostAdvisoryMiddleware(BASE_CONFIG);
+    mw.afterModel!(stateWithUsage(1000, 500), {});
+    mw.afterModel!(stateWithUsage(2000, 1000), {});
+    expect(mw.runningCost).toBeCloseTo(0.0315, 4);
+  });
+
+  it("skips a message without usage_metadata", () => {
+    const mw = createCostAdvisoryMiddleware(BASE_CONFIG);
+    mw.afterModel!({ messages: [new AIMessage({ content: "no usage" })] }, {});
+    expect(mw.runningCost).toBe(0);
+  });
+
+  it("warns once at the warning share of the cap, and never blocks a tool", () => {
+    const mw = createCostAdvisoryMiddleware({ ...BASE_CONFIG, maxCostUsd: 0.01, warningPct: 80 });
+    // $0.0105 crosses 80% of $0.01.
+    const first = warningOf(mw.afterModel!(stateWithUsage(1000, 500), {}));
+    expect(first).toContain("Budget warning");
+    expect(first).toContain("$0.01");
+    // Far past the cap: still no second message, and no tool hook exists to block with.
+    const second = mw.afterModel!(stateWithUsage(100_000, 50_000), {});
+    expect(second).toBeUndefined();
+    expect(mw.wrapToolCall, "the advisory has no power over tool calls; the runtime enforces the cap").toBeUndefined();
+  });
+
+  it("resets its total on beforeAgent", () => {
+    const mw = createCostAdvisoryMiddleware(BASE_CONFIG);
+    mw.afterModel!(stateWithUsage(1000, 500), {});
+    mw.beforeAgent!({}, {});
+    expect(mw.runningCost).toBe(0);
+  });
+
+  it("rejects a non-positive cap and a warning share outside 50–95", () => {
+    expect(() => createCostAdvisoryMiddleware({ ...BASE_CONFIG, maxCostUsd: 0 })).toThrow("maxCostUsd");
+    expect(() => createCostAdvisoryMiddleware({ ...BASE_CONFIG, maxCostUsd: -1 })).toThrow("maxCostUsd");
+    expect(() => createCostAdvisoryMiddleware({ ...BASE_CONFIG, warningPct: 49 })).toThrow("warningPct");
+    expect(() => createCostAdvisoryMiddleware({ ...BASE_CONFIG, warningPct: 96 })).toThrow("warningPct");
+  });
+
+  describe("forSubAgent", () => {
+    it("advances the parent's running total", () => {
+      const parent = createCostAdvisoryMiddleware(BASE_CONFIG);
+      parent.forSubAgent().afterModel!(stateWithUsage(1000, 500), {});
+      expect(parent.runningCost).toBeCloseTo(0.0105, 4);
+    });
+
+    it("does not reset the total when the sub-agent starts", () => {
+      const parent = createCostAdvisoryMiddleware(BASE_CONFIG);
+      parent.afterModel!(stateWithUsage(1000, 500), {});
+      const child = parent.forSubAgent();
+      expect(child.beforeAgent, "the view has no beforeAgent on purpose").toBeUndefined();
+      expect(parent.runningCost).toBeCloseTo(0.0105, 4);
+    });
+
+    it("warns inside the sub-agent when its call crosses the parent's threshold", () => {
+      const parent = createCostAdvisoryMiddleware({ ...BASE_CONFIG, maxCostUsd: 0.01 });
+      const warning = warningOf(parent.forSubAgent().afterModel!(stateWithUsage(1000, 500), {}));
+      expect(warning).toContain("Budget warning");
+    });
+  });
+});

package/src/middleware/approval-gate.ts

@@ -109,7 +109,7 @@ export interface ApprovalGateConfig {
    * gitignored path stays on the interrupt gate exactly as before.
    *
    * True only for gates whose backend a CAS observer wraps: the parent gate
-   * always (setup.ts), and — since DD-19 — sub-agent gates too, because
+   * always (turn-setup.ts), and — since DD-19 — sub-agent gates too, because
    * `compileSubagents` gives every sub-agent a CAS-observing backend wired to
    * the SAME shared observer and `buildSubAgentMiddleware` then inherits this
    * config verbatim. A gate over an UNOBSERVED backend must keep this false:
@@ -199,7 +199,7 @@ export function createApprovalGateMiddleware(
   const leasedCategories = config.leasedCategories ?? EMPTY_CATEGORY_SET;
 
   // No global-bypass early return: a pre-armed spec.auto_approve_all means the
-  // gate is never even installed (setup.ts builds this config only when not
+  // gate is never even installed (turn-setup.ts builds this config only when not
   // global). Scoped leases keep the gate active so non-leased actions still gate.
 
   return {

package/src/middleware/{cost-cap.ts → cost-advisory.ts}

@@ -1,29 +1,46 @@
 /**
- * Cost cap middleware for agent execution budget enforcement.
+ * Cost advisory middleware: warns the model once as the execution's estimated
+ * spend nears `max_cost_usd`, so it can wrap up before the cap.
  *
- * Tracks running estimated cost of LLM calls and enforces a
- * configurable cost ceiling:
+ * It ADVISES; it does not cap. The one enforcement of `max_cost_usd` is the
+ * turn runtime's (`harness/run-turn.ts` over `shared/cost-guard.ts`): every
+ * usage delta the adapter reports moves the runtime's estimate, and when the
+ * estimate crosses the cap the runtime stops the turn and settles TERMINATED
+ * with the cost-limit copy. The graph learns of the stop through its abort
+ * signal, the same way it learns of a platform STOP or a stall. This is the
+ * shape `execution-budget.ts` already has beside LangGraph's `recursionLimit`:
+ * the middleware warns inside the graph, the engine's own limit enforces.
  *
- * afterModel — extracts usage_metadata from the latest AIMessage,
- *   computes incremental cost, accumulates a running total. Injects
- *   a warning SystemMessage at ~80% and a termination message at 100%.
+ * Until S3 M2b (Q-S3-3) this module was `cost-cap.ts` and did both: it also
+ * blocked every tool call once the running cost passed the cap and gave the
+ * model one tool-free round to summarize. That second enforcement lived
+ * inside the graph, where the runtime could not see it, and a platform STOP
+ * had a sibling (`graceful-stop.ts`, deleted with it) that let the run spend
+ * a summary round after the platform said stop. Both went when the runtime
+ * became the one place a turn is stopped (harness runtime program, S3).
  *
- * wrapToolCall — blocks all tool execution when the budget is exceeded,
- *   giving the model one final tool-free round to produce a summary.
+ * afterModel — reads `usage_metadata` off the latest AIMessage, prices the
+ *   call at the parent's rates (a sub-agent on its own model is priced the
+ *   same way the enforcement prices it; per-sub-agent pricing is an S5 item),
+ *   accumulates the running total, and injects the warning SystemMessage once
+ *   at `warningPct` of the cap.
  *
- * Only injected when maxCostUsd > 0 is explicitly configured.
+ * forSubAgent — a view that shares the running total, so a sub-agent's calls
+ *   advance the same figure the parent's warning reads.
+ *
+ * Only built when `max_cost_usd > 0` is explicitly configured.
  */
 
-import { ToolMessage, SystemMessage } from "@langchain/core/messages";
-import type { StigmerMiddleware, CostCapConfig } from "./types.js";
+import { SystemMessage } from "@langchain/core/messages";
+import type { StigmerMiddleware, CostAdvisoryConfig } from "./types.js";
 
 const DEFAULT_WARNING_PCT = 80;
 const MIN_WARNING_PCT = 50;
 const MAX_WARNING_PCT = 95;
 
-export interface CostCapMiddleware extends StigmerMiddleware {
+export interface CostAdvisoryMiddleware extends StigmerMiddleware {
+  /** The running estimate this advisory has priced, in USD. */
   readonly runningCost: number;
-  readonly exceeded: boolean;
   forSubAgent(): StigmerMiddleware;
 }
 
@@ -49,7 +66,7 @@ function extractUsage(aiMessage: Record<string, unknown>): {
   return { totalInput, output, cacheRead };
 }
 
-export function createCostCapMiddleware(config: CostCapConfig): CostCapMiddleware {
+export function createCostAdvisoryMiddleware(config: CostAdvisoryConfig): CostAdvisoryMiddleware {
   const {
     maxCostUsd,
     inputPricePerMillion,
@@ -65,7 +82,6 @@ export function createCostCapMiddleware(config: CostCapConfig): CostCapMiddlewar
 
   let runningCost = 0;
   let warned = false;
-  let exceeded = false;
   let modelCallCount = 0;
 
   function computeCallCost(totalInput: number, output: number, cacheRead: number): number {
@@ -99,21 +115,7 @@ export function createCostCapMiddleware(config: CostCapConfig): CostCapMiddlewar
     });
   }
 
-  function createExceededMessage(): SystemMessage {
-    return new SystemMessage({
-      content:
-        `Budget exceeded: This execution has consumed ` +
-        `$${runningCost.toFixed(4)}, exceeding the ` +
-        `$${maxCostUsd.toFixed(2)} budget. ` +
-        `All tool calls are now blocked. ` +
-        `Respond with a summary of what you accomplished and ` +
-        `what work remains so the user can continue.`,
-    });
-  }
-
   function processAfterModel(state: Record<string, unknown>): { messages: SystemMessage[] } | void {
-    if (exceeded) return;
-
     const messages = (state.messages ?? []) as unknown[];
     let lastAi: Record<string, unknown> | null = null;
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -128,57 +130,28 @@ export function createCostCapMiddleware(config: CostCapConfig): CostCapMiddlewar
     const { totalInput, output, cacheRead } = extractUsage(lastAi);
     if (totalInput === 0 && output === 0) return;
 
-    const callCost = computeCallCost(totalInput, output, cacheRead);
-    runningCost += callCost;
+    runningCost += computeCallCost(totalInput, output, cacheRead);
     modelCallCount++;
 
     const warningThreshold = maxCostUsd * warningPct / 100;
-
-    if (runningCost >= maxCostUsd) {
-      exceeded = true;
-      console.warn(
-        `[CostCap] EXCEEDED: $${runningCost.toFixed(4)} >= $${maxCostUsd.toFixed(2)} ` +
-        `after ${modelCallCount} calls. Tool execution will be blocked.`,
-      );
-      return { messages: [createExceededMessage()] };
-    }
-
     if (!warned && runningCost >= warningThreshold) {
       warned = true;
       console.warn(
-        `[CostCap] WARNING: $${runningCost.toFixed(4)} >= $${warningThreshold.toFixed(4)} ` +
+        `[CostAdvisory] WARNING: $${runningCost.toFixed(4)} >= $${warningThreshold.toFixed(4)} ` +
         `(${warningPct}% of $${maxCostUsd.toFixed(2)}) after ${modelCallCount} calls.`,
       );
       return { messages: [createWarningMessage()] };
     }
   }
 
-  async function processWrapToolCall(
-    request: Parameters<NonNullable<StigmerMiddleware["wrapToolCall"]>>[0],
-    handler: Parameters<NonNullable<StigmerMiddleware["wrapToolCall"]>>[1],
-  ) {
-    if (exceeded) {
-      return new ToolMessage({
-        content:
-          `[Budget exceeded: tool execution blocked. ` +
-          `Summarize your progress for the user.]`,
-        tool_call_id: request.toolCall.id,
-        name: request.toolCall.name,
-      });
-    }
-    return await handler(request);
-  }
-
-  const middleware: CostCapMiddleware = {
-    name: "CostCapMiddleware",
+  const middleware: CostAdvisoryMiddleware = {
+    name: "CostAdvisoryMiddleware",
 
     get runningCost() { return runningCost; },
-    get exceeded() { return exceeded; },
 
     beforeAgent() {
       runningCost = 0;
       warned = false;
-      exceeded = false;
       modelCallCount = 0;
     },
 
@@ -186,25 +159,22 @@ export function createCostCapMiddleware(config: CostCapConfig): CostCapMiddlewar
       return processAfterModel(state);
     },
 
-    wrapToolCall: processWrapToolCall,
-
     afterAgent() {
       const pctUsed = maxCostUsd > 0
         ? (runningCost / maxCostUsd * 100)
         : 0;
       console.log(
-        `[CostCap] Summary: $${runningCost.toFixed(4)} of $${maxCostUsd.toFixed(2)} ` +
-        `(~${pctUsed.toFixed(0)}%) across ${modelCallCount} calls, ` +
-        `warned=${warned}, exceeded=${exceeded}`,
+        `[CostAdvisory] Summary: $${runningCost.toFixed(4)} of $${maxCostUsd.toFixed(2)} ` +
+        `(~${pctUsed.toFixed(0)}%) across ${modelCallCount} calls, warned=${warned}`,
       );
     },
 
     forSubAgent(): StigmerMiddleware {
       return {
-        name: "CostCapSubAgentView",
-        // Sub-agent view does NOT reset state on beforeAgent
+        name: "CostAdvisorySubAgentView",
+        // The view does NOT reset the running total on beforeAgent: a
+        // sub-agent's calls advance the parent's figure.
         afterModel(state) { return processAfterModel(state); },
-        wrapToolCall: processWrapToolCall,
       };
     },
   };

package/src/middleware/index.ts

@@ -1,43 +1,53 @@
 /**
- * Middleware stack factory.
+ * Middleware stack factory for the native harness's root graph.
  *
- * Assembles the ordered middleware array from a MiddlewareStackConfig.
- * The composition order matches the Python create_deep_agent injection:
+ * Assembles the ordered middleware array from a MiddlewareStackConfig. The
+ * order is load-bearing and reads top to bottom:
  *
  *   0. Path normalization (conditional: only on permission-rule-bearing
  *      graphs — FIRST, so every downstream middleware observes canonical
  *      workspace-absolute paths)
  *   1. Loop detection (always)
- *   2. Execution budget (always)
+ *   2. Execution budget (always — advises at ~80% of the tool-round budget
+ *      that LangGraph's `recursionLimit` enforces)
  *   3. Tool intent (always — bind-time shell schema extension, issue #276)
  *   4. Tool truncation (always)
- *   5. Graceful stop (always, inert until activated)
- *   6. Cost cap (conditional: only when maxCostUsd > 0)
+ *   5. Approval gate (conditional: absent under the global bypass)
+ *   6. Cost advisory (conditional: only when maxCostUsd > 0 — advises at
+ *      ~80% of the cap that the turn runtime enforces)
  *   7. Error hints (always)
  *   8. OTel spans (always, no-op when OTel not configured)
+ *
+ * Every middleware here either shapes the graph's tool surface or ADVISES
+ * the model; none of them stops the run. A stop — the platform's, the
+ * cost cap's, a stall's — is the turn runtime's, delivered to the graph
+ * through its abort signal (harness runtime program, S3 Q-S3-3; until M2b a
+ * graceful-stop middleware and the cost cap's tool block were second stops
+ * inside the graph that the runtime could not see).
+ *
+ * The sub-agent stack is `execute-deep-agent/subagent-wiring.ts`'s: the same
+ * order over the parent's shared instances where one exists (the advisory's
+ * running total), fresh ones otherwise.
  */
 
 import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
-import type { GracefulStopMiddleware } from "./graceful-stop.js";
 import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
 import { createToolIntentMiddleware } from "./tool-intent.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
-import { createGracefulStopMiddleware } from "./graceful-stop.js";
 import { createApprovalGateMiddleware } from "./approval-gate.js";
-import { createCostCapMiddleware, type CostCapMiddleware } from "./cost-cap.js";
+import { createCostAdvisoryMiddleware, type CostAdvisoryMiddleware } from "./cost-advisory.js";
 import { createErrorHintsMiddleware } from "./error-hints.js";
 import { createOtelSpansMiddleware } from "./otel-spans.js";
 
-export type { GracefulStopMiddleware } from "./graceful-stop.js";
-export type { CostCapMiddleware } from "./cost-cap.js";
+export type { CostAdvisoryMiddleware } from "./cost-advisory.js";
 export type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
 
 export interface MiddlewareStackResult {
   readonly middleware: StigmerMiddleware[];
-  readonly gracefulStop: GracefulStopMiddleware;
-  readonly costCap: CostCapMiddleware | null;
+  /** The advisory's instance, for the sub-agent stacks to share its running total; null when no cap is configured. */
+  readonly costAdvisory: CostAdvisoryMiddleware | null;
 }
 
 export function buildMiddlewareStack(
@@ -50,32 +60,22 @@ export function buildMiddlewareStack(
   }
 
   stack.push(createLoopDetectionMiddleware(config.loopDetection));
-
   stack.push(createExecutionBudgetMiddleware(config.executionBudget));
-
   stack.push(createToolIntentMiddleware());
-
   stack.push(createToolTruncationMiddleware(config.toolTruncation));
 
-  const gracefulStop = createGracefulStopMiddleware();
-  stack.push(gracefulStop);
-
   if (config.approvalGate) {
     stack.push(createApprovalGateMiddleware(config.approvalGate));
   }
 
-  if (config.costCap && config.costCap.maxCostUsd > 0) {
-    const costCapMiddleware = createCostCapMiddleware(config.costCap);
-    stack.push(costCapMiddleware);
-
-    stack.push(createErrorHintsMiddleware());
-    stack.push(createOtelSpansMiddleware(config.otelSpans));
-
-    return { middleware: stack, gracefulStop, costCap: costCapMiddleware };
-  }
+  const costAdvisory =
+    config.costAdvisory && config.costAdvisory.maxCostUsd > 0
+      ? createCostAdvisoryMiddleware(config.costAdvisory)
+      : null;
+  if (costAdvisory) stack.push(costAdvisory);
 
   stack.push(createErrorHintsMiddleware());
   stack.push(createOtelSpansMiddleware(config.otelSpans));
 
-  return { middleware: stack, gracefulStop, costCap: null };
+  return { middleware: stack, costAdvisory };
 }

package/src/middleware/types.ts

@@ -82,7 +82,8 @@ export interface ToolTruncationConfig {
   readonly onTruncation?: (toolName: string, charsTruncated: number) => void;
 }
 
-export interface CostCapConfig {
+/** The cap the advisory warns toward; the turn runtime enforces it (`shared/cost-guard.ts`). */
+export interface CostAdvisoryConfig {
   readonly maxCostUsd: number;
   readonly inputPricePerMillion: number;
   readonly outputPricePerMillion: number;
@@ -113,7 +114,7 @@ export interface MiddlewareStackConfig {
   readonly loopDetection?: Partial<LoopDetectionConfig>;
   readonly executionBudget?: Partial<ExecutionBudgetConfig>;
   readonly toolTruncation?: Partial<ToolTruncationConfig>;
-  readonly costCap?: CostCapConfig | null;
+  readonly costAdvisory?: CostAdvisoryConfig | null;
   readonly otelSpans?: Partial<OtelSpansConfig>;
   readonly approvalGate?: ApprovalGateConfig | null;
   /**