@stigmer/runner 3.12.2 → 3.12.4

package/src/activities/execute-cursor/agent-session-cache.ts

@@ -0,0 +1,229 @@
+/**
+ * Session-keyed Cursor agent cache — keeps the SDK executor (and its stdio
+ * MCP server processes) alive across turns of the SAME session (#215).
+ *
+ * Why this exists: the SDK's local executor cache is refcounted and keyed
+ * by the full acquisition config (workingDirectory, hashed apiKey,
+ * settingSources, mcpServers, customSubagents). `agent.close()` releases
+ * the agent's lease; at refcount zero the executor is DISPOSED and every
+ * stdio MCP server is killed. The activity used to close on every terminal
+ * path, so each turn re-acquired the executor and re-spawned every MCP
+ * server inside `agent.send()` — a measured 2.2–3.2s per-turn tax
+ * (`turn_first_event`'s `send_returned` segment).
+ *
+ * Ownership model — exclusive checkout, explicit lifetime:
+ * - A finishing turn PARKS its healthy agent here (`cacheSessionAgent`);
+ *   the next activity for the session CHECKS IT OUT (`takeCachedAgent`),
+ *   removing it from the cache, so two concurrent activities can never
+ *   share one Agent handle — the loser of the race resolves its own.
+ * - The cached agent is reused only when the acquisition FINGERPRINT
+ *   matches. Any config drift (rotated credential, edited MCP servers,
+ *   model change, different workspace) closes the parked agent and forces
+ *   a fresh resolve — correctness by construction: a reused executor would
+ *   otherwise keep serving the OLD config.
+ * - Failure paths never park: a suspect agent is closed where it failed
+ *   (the pre-existing close sites), and `evictSessionAgent` clears any
+ *   parked entry when a session's state is replaced out from under it.
+ * - Idle TTL + LRU cap bound memory on multi-session hosts (the desktop
+ *   runner-manager hosts many sessions per process; a cloud sandbox is
+ *   session-pinned and holds at most one entry). Worker shutdown closes
+ *   everything (`closeAllCachedAgents`).
+ */
+
+import { createHash } from "node:crypto";
+
+/** The slice of SDKAgent this cache needs — close() releases the executor lease. */
+export interface CacheableAgent {
+  readonly agentId: string;
+  close(): void;
+}
+
+interface CachedSessionAgent {
+  readonly agent: CacheableAgent;
+  readonly fingerprint: string;
+  readonly evictTimer: NodeJS.Timeout;
+  /** Insertion-order tiebreaker for the LRU cap. */
+  readonly parkedAt: number;
+}
+
+/**
+ * Default idle lifetime for a parked agent. Long enough to cover human
+ * think-time between turns and approval round-trips; short enough that an
+ * abandoned session does not pin MCP subprocesses for hours.
+ */
+const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Ceiling on concurrently parked agents (each holds an executor + its MCP
+ * subprocesses). Cloud sandboxes never approach it (one session per pod);
+ * it protects long-lived desktop runner-managers.
+ */
+const MAX_PARKED_AGENTS = 32;
+
+function resolveIdleTtlMs(): number {
+  const parsed = Number.parseInt(process.env.STIGMER_CURSOR_AGENT_CACHE_TTL_MS ?? "", 10);
+  return parsed > 0 ? parsed : DEFAULT_IDLE_TTL_MS;
+}
+
+const parkedAgents = new Map<string, CachedSessionAgent>();
+
+function closeQuietly(agent: CacheableAgent): void {
+  try {
+    agent.close();
+  } catch {
+    /* best effort — the lease release is advisory on an already-dead agent */
+  }
+}
+
+/**
+ * Fingerprint of everything that determines whether a parked agent can
+ * serve the next turn as-is: the SDK executor cache key inputs PLUS the
+ * per-agent options resume() re-supplies (model selection, sub-agents).
+ * The API key contributes only as a hash — the fingerprint must never be
+ * a secret-bearing value (it appears in no logs, but defense in depth).
+ */
+export function computeAgentFingerprint(createOptions: Record<string, unknown>): string {
+  const { apiKey, ...rest } = createOptions;
+  const material = {
+    ...rest,
+    apiKeyHash:
+      typeof apiKey === "string" && apiKey.length > 0
+        ? createHash("sha256").update(apiKey).digest("hex")
+        : undefined,
+  };
+  return createHash("sha256").update(stableStringify(material)).digest("hex");
+}
+
+/** Deterministic JSON: object keys sorted recursively (the SDK's own idiom). */
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .sort()
+        .map((k) => [k, sortKeys((value as Record<string, unknown>)[k])]),
+    );
+  }
+  return value;
+}
+
+/**
+ * Exclusive checkout: returns the parked agent for the session and removes
+ * it from the cache, or undefined when there is nothing reusable.
+ *
+ * A parked agent is reusable only when BOTH hold:
+ * - `fingerprint` matches (config identical to what the agent was built with);
+ * - `expectedAgentId`, when non-empty, matches the parked agent (the
+ *   session's harnessStateId is the source of truth — a recovery in another
+ *   activity may have replaced the agent since this one was parked).
+ *
+ * A mismatch on either closes the parked agent: it can never serve this
+ * session again, and holding it would only pin dead MCP processes.
+ */
+export function takeCachedAgent(
+  sessionId: string,
+  fingerprint: string,
+  expectedAgentId: string,
+): CacheableAgent | undefined {
+  const entry = parkedAgents.get(sessionId);
+  if (!entry) return undefined;
+
+  parkedAgents.delete(sessionId);
+  clearTimeout(entry.evictTimer);
+
+  const agentMatches = expectedAgentId === "" || entry.agent.agentId === expectedAgentId;
+  if (entry.fingerprint !== fingerprint || !agentMatches) {
+    console.log(
+      `agent-session-cache: parked agent for session=${sessionId} not reusable ` +
+      `(fingerprintMatch=${entry.fingerprint === fingerprint}, agentIdMatch=${agentMatches}) — closing`,
+    );
+    closeQuietly(entry.agent);
+    return undefined;
+  }
+
+  return entry.agent;
+}
+
+/**
+ * Parks a healthy agent for the session's next turn. Replaces (and closes)
+ * any agent already parked for the session; evicts the oldest entry when
+ * the cap is reached.
+ */
+export function cacheSessionAgent(
+  sessionId: string,
+  agent: CacheableAgent,
+  fingerprint: string,
+): void {
+  if (!sessionId) {
+    // No stable key to reuse by — release the lease as before the cache.
+    closeQuietly(agent);
+    return;
+  }
+
+  const displaced = parkedAgents.get(sessionId);
+  if (displaced) {
+    clearTimeout(displaced.evictTimer);
+    closeQuietly(displaced.agent);
+  }
+
+  if (parkedAgents.size >= MAX_PARKED_AGENTS) {
+    let oldestKey: string | undefined;
+    let oldestAt = Infinity;
+    for (const [key, entry] of parkedAgents) {
+      if (entry.parkedAt < oldestAt) {
+        oldestAt = entry.parkedAt;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== undefined) evictSessionAgent(oldestKey);
+  }
+
+  const ttlMs = resolveIdleTtlMs();
+  const evictTimer = setTimeout(() => evictSessionAgent(sessionId), ttlMs);
+  // Never keep the process alive just to evict an idle agent.
+  evictTimer.unref?.();
+
+  parkedAgents.set(sessionId, {
+    agent,
+    fingerprint,
+    evictTimer,
+    parkedAt: Date.now(),
+  });
+}
+
+/** Closes and forgets the parked agent for a session, if any. */
+export function evictSessionAgent(sessionId: string): void {
+  const entry = parkedAgents.get(sessionId);
+  if (!entry) return;
+  parkedAgents.delete(sessionId);
+  clearTimeout(entry.evictTimer);
+  closeQuietly(entry.agent);
+  console.log(`agent-session-cache: evicted parked agent for session=${sessionId}`);
+}
+
+/** Worker shutdown: release every parked lease so executors dispose cleanly. */
+export function closeAllCachedAgents(): void {
+  for (const [sessionId, entry] of parkedAgents) {
+    clearTimeout(entry.evictTimer);
+    closeQuietly(entry.agent);
+    console.log(`agent-session-cache: closed parked agent for session=${sessionId} (shutdown)`);
+  }
+  parkedAgents.clear();
+}
+
+/** Test seam. */
+export function _resetAgentSessionCacheForTests(): void {
+  for (const entry of parkedAgents.values()) {
+    clearTimeout(entry.evictTimer);
+  }
+  parkedAgents.clear();
+}
+
+/** Test seam. */
+export function _parkedAgentCountForTests(): number {
+  return parkedAgents.size;
+}

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

@@ -41,6 +41,7 @@ import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
 import { describeExecutionError } from "../../shared/model-error.js";
 import { resolveAgentWithTransportRecovery } from "./session-lifecycle.js";
+import { cacheSessionAgent, computeAgentFingerprint, takeCachedAgent } from "./agent-session-cache.js";
 import type { AgentResolution, AgentResolutionReason, CreateAgentOptions, CreateCloudAgentOptions } from "./session-lifecycle.js";
 import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
 import { determineCursorMode, isCloudMode } from "./cursor-mode.js";
@@ -134,7 +135,8 @@ import { statusProtoWriter } from "../../shared/execution-status-writer.js";
 import { setInterceptorExecutionId, runWithExecutionContext } from "./fetch-interceptor.js";
 import { closeProxySessions } from "./http2-interceptor.js";
 import { resolveModelId, ensureLoaded as ensurePricingLoaded } from "./model-pricing.js";
-import { resolveEffectiveServiceTier, resolveServiceTierParams } from "./service-tier.js";
+import { resolveEffectiveServiceTier } from "../../shared/service-tier.js";
+import { resolveServiceTierParams } from "./service-tier.js";
 import { UsageAccumulator } from "./usage-accumulator.js";
 import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
@@ -1052,21 +1054,52 @@ async function executeCursorInner(
     // is the largest user-visible setup segment; this split keeps its
     // historical meaning — the SDK call was already 98%+ of it).
     setupTiming.mark("prepare_agent");
-    let resolution: AgentResolution = await resolveAgentWithTransportRecovery({
-      harnessStateId: threadId,
-      createOptions,
-      mode: agentMode,
-      timeoutMs: config.agentResolveTimeoutMs,
-      buildTimeoutMessage: (finalAttempt) =>
-        `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
-        `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
-        `The transport connection is likely dead. ` +
-        (finalAttempt
-          ? `An automatic retry on a fresh transport connection also timed out. ` +
-            `Retry the message later; if this persists, check proxy and network health.`
-          : `Resetting the transport and retrying automatically.`),
-      resetTransport: closeProxySessions,
-    });
+
+    // Phase 8a: Reuse the previous turn's agent when this session parked one
+    // (#215). A checkout hit skips Agent.resume() AND — the real win — keeps
+    // the SDK executor lease alive, so agent.send() below re-acquires the
+    // warm executor instead of re-spawning every stdio MCP server (the
+    // measured 2.2–3.2s `send_returned` tax). The fingerprint covers the
+    // full acquisition config, so any drift (rotated credential, edited MCP
+    // servers, model change) falls through to a fresh resolve.
+    const agentFingerprint = computeAgentFingerprint(
+      createOptions as unknown as Record<string, unknown>,
+    );
+    const parkedAgent = takeCachedAgent(sessionId, agentFingerprint, threadId ?? "");
+    let resolution: AgentResolution;
+    if (parkedAgent) {
+      console.log(
+        `ExecuteCursor reusing parked session agent: execution=${executionId}, ` +
+        `session=${sessionId}, agentId=${parkedAgent.agentId}`,
+      );
+      resolution = {
+        agent: parkedAgent as AgentResolution["agent"],
+        agentId: parkedAgent.agentId,
+        isNew: false,
+        resumed: true,
+        mode: agentMode,
+        // The parked handle IS the live conversation — every consumer of
+        // "resumed_successfully" (prompt selection, poisoned-handle
+        // recovery eligibility) wants exactly those semantics.
+        reason: "resumed_successfully",
+      };
+    } else {
+      resolution = await resolveAgentWithTransportRecovery({
+        harnessStateId: threadId,
+        createOptions,
+        mode: agentMode,
+        timeoutMs: config.agentResolveTimeoutMs,
+        buildTimeoutMessage: (finalAttempt) =>
+          `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
+          `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
+          `The transport connection is likely dead. ` +
+          (finalAttempt
+            ? `An automatic retry on a fresh transport connection also timed out. ` +
+              `Retry the message later; if this persists, check proxy and network health.`
+            : `Resetting the transport and retrying automatically.`),
+        resetTransport: closeProxySessions,
+      });
+    }
 
     console.log(
       `ExecuteCursor agent resolved: execution=${executionId}, ` +
@@ -1462,7 +1495,9 @@ async function executeCursorInner(
           timestamp: utcTimestamp(),
         }));
         await persist(status);
-        try { resolution.agent.close(); } catch { /* best effort */ }
+        // Clean terminal: the conversation continues on the next message,
+        // so park the healthy agent for that turn (#215).
+        cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
         console.warn(
           `ExecuteCursor terminated (cost cap): execution=${executionId}, ` +
           `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`,
@@ -1527,7 +1562,8 @@ async function executeCursorInner(
           timestamp: utcTimestamp(),
         }));
         await persist(status);
-        try { resolution.agent.close(); } catch { /* best effort */ }
+        // Clean terminal — park for the session's next turn (#215).
+        cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
         console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
         return { kind: "return" };
       }
@@ -1573,6 +1609,12 @@ async function executeCursorInner(
     const enterApprovalPause = async (boundary: TurnBoundaryResult) => {
       status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
       await persist(status);
+      // The approval-resume reinvocation is the cache's best case: park the
+      // agent so the resumed turn skips the full executor rebuild (#215).
+      // (This path previously dropped the handle without close() — the
+      // lease leaked; parking makes the lifetime explicit.) An absent
+      // sessionId falls back to "" — the cache closes the lease immediately.
+      cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
       console.log(
         `ExecuteCursor returning WAITING_FOR_APPROVAL: ${boundary.deniedToolCallCount} gated tool(s), ` +
         `${boundary.capturedChangeCount} file card(s) pending`,
@@ -2088,8 +2130,12 @@ async function executeCursorInner(
         (status.error ? `, error=${status.error}` : ""),
     );
 
-    // Release SDK executor lease to prevent cache buildup across workflow tasks
-    try { resolution.agent.close(); } catch { /* best effort */ }
+    // Park the agent (with its executor lease) for the session's next turn
+    // instead of closing it — the idle TTL / shutdown hooks in
+    // agent-session-cache own the eventual release, so cache buildup across
+    // sessions stays bounded while turns of ONE session stop paying the
+    // executor + MCP re-spawn tax (#215).
+    cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
 
     const slim = slimStatus(status) as Record<string, unknown>;
     if (finalText !== undefined) {

package/src/activities/execute-cursor/service-tier.ts

@@ -20,19 +20,17 @@
  * rides the same proxy fetch-interceptor as every other SDK call, so it
  * works identically in proxy and direct modes.
  *
- * UNSPECIFIED resolves to STANDARD here and ONLY here — every upstream
- * layer preserves the caller's raw enum so "user chose standard" stays
- * distinguishable from "platform default" all the way to the ledger.
+ * The harness-neutral halves — the tier enum semantics, and the single
+ * UNSPECIFIED→STANDARD resolution point — live in
+ * `shared/service-tier.ts` since #361 extended tiers to the native
+ * harness; this module keeps only the Cursor-catalog translation.
  */
 
 import { Cursor } from "@cursor/sdk";
 import type { ModelListItem, ModelParameterValue } from "@cursor/sdk";
 import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
-/**
- * The effective tier after platform-default resolution: never UNSPECIFIED.
- */
-export type EffectiveServiceTier = ServiceTier.STANDARD | ServiceTier.FAST;
+import { serviceTierLabel, type EffectiveServiceTier } from "../../shared/service-tier.js";
 
 /**
  * Catalog ids that mean "Cursor picks the model" (Auto). Auto's single
@@ -72,28 +70,6 @@ export function resetCatalogCacheForTests(): void {
   inflightCatalogFetch = null;
 }
 
-/**
- * Resolve the configured tier to its effective value. The single place in
- * the platform where UNSPECIFIED becomes STANDARD.
- */
-export function resolveEffectiveServiceTier(
-  configured: ServiceTier | undefined,
-): EffectiveServiceTier {
-  return configured === ServiceTier.FAST ? ServiceTier.FAST : ServiceTier.STANDARD;
-}
-
-/** Human-readable tier label for logs and error messages. */
-export function serviceTierLabel(tier: ServiceTier): string {
-  switch (tier) {
-    case ServiceTier.FAST:
-      return "fast";
-    case ServiceTier.STANDARD:
-      return "standard";
-    default:
-      return "unspecified";
-  }
-}
-
 async function listCatalogModels(apiKey: string): Promise<readonly ModelListItem[]> {
   const now = Date.now();
   if (catalogCache && catalogCache.apiKey === apiKey && catalogCache.expiresAt > now) {

package/src/activities/execute-cursor/skill-resolver.ts

@@ -19,6 +19,7 @@
 
 import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -115,14 +116,15 @@ export async function resolveSkills(
       let artifactBytes: Uint8Array | undefined;
       if (wantsArtifact) {
         try {
-          const resp = await client.getSkillArtifact(skill.status!.artifactStorageKey);
-          if (resp.artifact && resp.artifact.length > 0) {
-            artifactBytes = resp.artifact;
-          }
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
         } catch (err) {
-          console.warn(
-            `[resolveSkills] artifact download failed for ${ref.slug}, ` +
-            `falling back to SKILL.md only: ${err instanceof Error ? err.message : err}`,
+          // Deliberate degradation, but LOUD (#675): the session still gets
+          // SKILL.md (better than a dead run), yet a skill silently missing
+          // its scripts/references was exactly how oversized artifacts hid.
+          console.error(
+            `[resolveSkills] artifact download FAILED for ${ref.org || "(default)"}/${ref.slug} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
           );
         }
       }
@@ -161,6 +163,48 @@ async function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact
   }
 }
 
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (#672's hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ *
+ * Exported for tests.
+ */
+export async function downloadArtifact(
+  client: StigmerClient,
+  artifactStorageKey: string,
+): Promise<Uint8Array | undefined> {
+  let minted;
+  try {
+    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      const resp = await client.getSkillArtifact(artifactStorageKey);
+      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url);
+  if (!resp.ok) {
+    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+  }
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+    throw new Error(
+      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
+    );
+  }
+  return bytes.length > 0 ? bytes : undefined;
+}
+
 /**
  * (Re)write a skill's mount directory from scratch.
  *
@@ -188,7 +232,7 @@ async function writeSkillMount(
     for (const entry of entries) {
       const filePath = join(skillDir, entry.path);
       await mkdir(dirname(filePath), { recursive: true });
-      await writeFile(filePath, entry.content, "utf-8");
+      await writeFile(filePath, entry.content);
     }
   }
 

package/src/activities/execute-deep-agent/__test-utils__/scripted-model.ts

@@ -50,11 +50,20 @@ export type ScriptSelector = (boundToolNames: string[]) => ScriptStep;
  */
 export class ScriptedModel extends BaseChatModel {
   toolNames: string[] = [];
+  /**
+   * The tool objects from the most recent `bindTools` call, exactly as the
+   * agent bound them (post-middleware). Lets tests assert on the bound
+   * SCHEMAS — e.g. the tool-intent middleware's bind-time shell clone — not
+   * just the names. The array is shared across the clones `bindTools`
+   * returns, so the instance the test holds always sees the latest bind.
+   */
+  readonly boundTools: unknown[];
   private readonly select: ScriptSelector;
 
-  constructor(select: ScriptSelector) {
+  constructor(select: ScriptSelector, boundTools: unknown[] = []) {
     super({});
     this.select = select;
+    this.boundTools = boundTools;
   }
 
   _llmType(): string {
@@ -62,8 +71,10 @@ export class ScriptedModel extends BaseChatModel {
   }
 
   bindTools(tools: unknown[]): this {
-    const next = new ScriptedModel(this.select);
+    const next = new ScriptedModel(this.select, this.boundTools);
     next.toolNames = (tools as Array<{ name?: string }>).map((t) => t?.name ?? "");
+    this.boundTools.length = 0;
+    this.boundTools.push(...tools);
     return next as unknown as this;
   }
 

package/src/activities/execute-deep-agent/__tests__/subagent-wiring.test.ts

@@ -7,11 +7,12 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
-    expect(stack[3].name).toBe("ErrorHintsMiddleware");
+    expect(stack[2].name).toBe("StigmerToolIntentMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -25,9 +26,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("CostCapSubAgentView");
-    expect(stack[4].name).toBe("ErrorHintsMiddleware");
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -43,7 +44,7 @@ describe("buildSubAgentMiddleware", () => {
 
     expect(parentCostCap.runningCost).toBe(0);
 
-    const subView = stack[3];
+    const subView = stack[4];
     expect(subView.afterModel).toBeDefined();
     expect(subView.wrapToolCall).toBeDefined();
     expect(subView.beforeAgent).toBeUndefined();
@@ -69,7 +70,7 @@ describe("buildSubAgentMiddleware", () => {
       toolTruncation: { maxChars: 5000 },
     });
 
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
   });
 
   it("installs the approval gate when an approvalGate config is provided", () => {
@@ -77,16 +78,16 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, error hints
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[3].wrapToolCall).toBeDefined();
+    // loop, budget, tool intent, truncation, approval gate, error hints
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[4].wrapToolCall).toBeDefined();
   });
 
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -104,13 +105,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view, error hints.
-    // Hints AFTER the gate matches the parent nesting: the gate's HITL
-    // interrupt stays outside the hints' try/catch (issue #255).
-    expect(stack).toHaveLength(6);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[4].name).toBe("CostCapSubAgentView");
-    expect(stack[5].name).toBe("ErrorHintsMiddleware");
+    // loop, budget, tool intent, truncation, approval gate, cost cap view,
+    // error hints. Hints AFTER the gate matches the parent nesting: the
+    // gate's HITL interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(7);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[5].name).toBe("CostCapSubAgentView");
+    expect(stack[6].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored

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

@@ -72,6 +72,7 @@ import { getRunnerHitlMasterSecret } from "../../shared/fingerprint-secret.js";
 import { getModelPricing, ensureLoaded as ensurePricingLoaded } from "../../shared/model-pricing.js";
 import { getDefaultModel, getModelVisionCapability } from "../../shared/model-registry.js";
 import { buildChatModel } from "../../shared/model-client.js";
+import { resolveEffectiveServiceTier } from "../../shared/service-tier.js";
 import {
   loadArtifactStorageConfig,
   resolveUsableArtifactStorage,
@@ -580,11 +581,22 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // The operator's STIGMER_LLM_REQUEST_TIMEOUT_MS bound is applied inside
     // buildChatModel (#468) — the sub-agent modelFactory below silently
     // dropped it when each caller parsed the env itself.
+    //
+    // The service tier resolves ONCE here (UNSPECIFIED → explicit
+    // STANDARD, shared/service-tier.ts) and rides every model this
+    // execution constructs — the primary below AND the sub-agent factory —
+    // so the provider account's default can never pick the price of any
+    // turn (#361, the native half of #357's contract). Sub-agents inherit
+    // it because the tier is an attribute of the EXECUTION's bill, and
+    // sub-agent calls land on the same ledger.
+    const serviceTier = resolveEffectiveServiceTier(
+      execution.spec!.executionConfig?.serviceTier);
     const { model } = await buildChatModel({
       modelName,
       proxyEndpoint: config.proxyEndpoint ?? undefined,
       stigmerToken: config.stigmerToken ?? undefined,
       headerScope: { executionId },
+      serviceTier,
     });
     timing.mark("build_model");
 
@@ -776,6 +788,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
             proxyEndpoint: config.proxyEndpoint ?? undefined,
             stigmerToken: config.stigmerToken ?? undefined,
             headerScope: { executionId },
+            // The execution's tier, inherited: sub-agent calls bill to the
+            // same execution (#361 — see the Step 9 resolution comment).
+            serviceTier,
           })).model,
         // Presence of shellEnv is the shell-capability switch for sub-agent
         // backends too (undefined in plan mode; see buildShellEnv above).