@stigmer/runner 3.6.0 → 3.8.0

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

@@ -0,0 +1,244 @@
+/**
+ * Service-tier → Cursor variant-parameter translation (stigmer/stigmer#357).
+ *
+ * The platform contract: an execution's model selection is ALWAYS explicit.
+ * A bare `{ id }` lets the Cursor catalog's default variant decide the price
+ * (observed 2026-08-06: composer-2.5 defaults to fast=true at ~4x base
+ * rates, claude-haiku-4-5 to thinking=true), and that default follows an
+ * out-of-band account setting. This module pins every price-bearing variant
+ * parameter the model declares, so the billed variant is a deterministic
+ * function of ExecutionConfig.service_tier:
+ *
+ * - STANDARD: every price-bearing boolean pinned to its base value
+ *   (fast=false, thinking=false where the parameter exists).
+ * - FAST: fast=true, thinking still pinned false.
+ * - Price-neutral parameters (e.g. effort) are deliberately NOT pinned —
+ *   they follow the catalog default and do not change the bill.
+ *
+ * Parameter bundles come from Cursor.models.list() (worker-cached): the
+ * catalog is the only source of a model's parameter ids, and the fetch
+ * 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.
+ */
+
+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;
+
+/**
+ * Catalog ids that mean "Cursor picks the model" (Auto). Auto's single
+ * catalog variant has an empty parameter set — there is no tier dimension
+ * to pin, a documented v1 limitation. Create-time validation refuses FAST
+ * without a pinned model, so FAST can only reach Auto through registry
+ * drift — handled as a loud failure below.
+ */
+const AUTO_MODEL_IDS = new Set(["default", "auto"]);
+
+/**
+ * Variant parameter ids that change the per-token price. Pinning exactly
+ * these keeps the bill deterministic while leaving latency/effort knobs on
+ * their catalog defaults. Sourced from the Cursor catalog survey
+ * (stigmer-cloud _projects/2026-08/20260806.04.model-service-tier).
+ */
+const FAST_PARAM_ID = "fast";
+const THINKING_PARAM_ID = "thinking";
+
+const CATALOG_CACHE_TTL_MS = 3_600_000; // 1 hour, matching the pricing table TTL
+
+interface CatalogCache {
+  readonly apiKey: string;
+  readonly models: readonly ModelListItem[];
+  readonly expiresAt: number;
+}
+
+let catalogCache: CatalogCache | null = null;
+// Keyed by apiKey: a worker normally serves one org's key, but nothing
+// enforces that — handing execution A a catalog fetched under execution B's
+// key would leak another account's model availability into A's translation.
+let inflightCatalogFetch: { readonly apiKey: string; readonly promise: Promise<readonly ModelListItem[]> } | null = null;
+
+/** Test-only: drop the worker-level catalog cache. */
+export function resetCatalogCacheForTests(): void {
+  catalogCache = null;
+  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) {
+    return catalogCache.models;
+  }
+  if (inflightCatalogFetch?.apiKey === apiKey) return inflightCatalogFetch.promise;
+
+  let entry: { apiKey: string; promise: Promise<readonly ModelListItem[]> } | null = null;
+  const promise = (async () => {
+    try {
+      const models = await Cursor.models.list({ apiKey });
+      catalogCache = { apiKey, models, expiresAt: Date.now() + CATALOG_CACHE_TTL_MS };
+      return models;
+    } finally {
+      // Clear only our own entry — a concurrent fetch under another key may
+      // have replaced it.
+      if (inflightCatalogFetch === entry) {
+        inflightCatalogFetch = null;
+      }
+    }
+  })();
+  entry = { apiKey, promise };
+  inflightCatalogFetch = entry;
+  return promise;
+}
+
+function findCatalogModel(
+  models: readonly ModelListItem[],
+  modelId: string,
+): ModelListItem | undefined {
+  return models.find((m) => m.id === modelId || m.aliases?.includes(modelId));
+}
+
+export interface ResolveServiceTierParamsOptions {
+  readonly apiKey: string;
+  /** Validated model id the execution runs on (may be "default" for Auto). */
+  readonly modelId: string;
+  readonly tier: EffectiveServiceTier;
+  /** For log correlation only. */
+  readonly executionId: string;
+}
+
+/**
+ * Translate the effective tier into the explicit variant parameters to send
+ * with every Agent.create/resume for this execution.
+ *
+ * Fail-closed posture: FAST with no pinnable fast dimension is an error,
+ * never a silent downgrade — create-time validation makes this unreachable
+ * unless the registry and the provider catalog have drifted, and that drift
+ * must be heard about, not absorbed.
+ *
+ * STANDARD degrades to empty params on catalog failures rather than failing
+ * the execution — but be clear about what that costs: an unpinned selection
+ * falls to the catalog default variant, which for several models IS the
+ * fast/thinking variant at multiples of base rates (the incident this module
+ * exists to prevent). Failing every standard execution whenever the catalog
+ * endpoint blips would be the worse trade; the WARN below plus billing's
+ * requested-vs-billed mismatch alarm (which catches exactly this window)
+ * are the compensating controls.
+ */
+export async function resolveServiceTierParams(
+  options: ResolveServiceTierParamsOptions,
+): Promise<ModelParameterValue[]> {
+  const { apiKey, modelId, tier, executionId } = options;
+  const tierName = serviceTierLabel(tier);
+
+  if (AUTO_MODEL_IDS.has(modelId)) {
+    if (tier === ServiceTier.FAST) {
+      throw new Error(
+        `service_tier=fast requires a pinned model — Auto ("${modelId}") has no ` +
+        `tier dimension. Execution ${executionId} should have been refused at ` +
+        `create time; the model registry and provider catalog may have drifted.`,
+      );
+    }
+    console.log(
+      `ServiceTier: execution=${executionId} model=${modelId} tier=${tierName} — ` +
+      `Auto has no variant parameters; Cursor picks the model and variant ` +
+      `(documented v1 limitation).`,
+    );
+    return [];
+  }
+
+  let models: readonly ModelListItem[];
+  try {
+    models = await listCatalogModels(apiKey);
+  } catch (err) {
+    if (tier === ServiceTier.FAST) {
+      throw new Error(
+        `service_tier=fast for execution ${executionId} needs the Cursor model ` +
+        `catalog to resolve variant params for "${modelId}", and the catalog ` +
+        `fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    console.warn(
+      `ServiceTier UNPINNED: execution=${executionId} model=${modelId} tier=${tierName} — ` +
+      `catalog fetch failed (${err instanceof Error ? err.message : err}); ` +
+      `sending no variant params, so the catalog DEFAULT variant decides the ` +
+      `price for this execution (fast/thinking on several models — the ` +
+      `expensive direction). Billing's requested-vs-billed mismatch alarm ` +
+      `covers this window.`,
+    );
+    return [];
+  }
+
+  const model = findCatalogModel(models, modelId);
+  if (!model) {
+    if (tier === ServiceTier.FAST) {
+      throw new Error(
+        `service_tier=fast requested for "${modelId}" (execution ${executionId}) ` +
+        `but the Cursor catalog does not list that model — cannot pin a fast ` +
+        `variant. The model registry and provider catalog have drifted.`,
+      );
+    }
+    console.warn(
+      `ServiceTier UNPINNED: execution=${executionId} model=${modelId} tier=${tierName} — ` +
+      `model not in the Cursor catalog; sending no variant params, so the ` +
+      `catalog DEFAULT variant decides the price for this execution.`,
+    );
+    return [];
+  }
+
+  const params: ModelParameterValue[] = [];
+  for (const def of model.parameters ?? []) {
+    if (def.id === FAST_PARAM_ID) {
+      params.push({ id: FAST_PARAM_ID, value: tier === ServiceTier.FAST ? "true" : "false" });
+    } else if (def.id === THINKING_PARAM_ID) {
+      params.push({ id: THINKING_PARAM_ID, value: "false" });
+    }
+    // Any other parameter (e.g. effort) is price-neutral: left to the
+    // catalog default variant on purpose.
+  }
+
+  if (tier === ServiceTier.FAST && !params.some((p) => p.id === FAST_PARAM_ID)) {
+    throw new Error(
+      `service_tier=fast requested for "${modelId}" (execution ${executionId}) ` +
+      `but the Cursor catalog declares no "fast" parameter for it. The model ` +
+      `registry prices a fast variant the provider no longer offers — refusing ` +
+      `rather than silently billing an unknown variant.`,
+    );
+  }
+
+  params.sort((a, b) => a.id.localeCompare(b.id));
+  console.log(
+    `ServiceTier: execution=${executionId} model=${modelId} tier=${tierName} ` +
+    `params=${JSON.stringify(params)}`,
+  );
+  return params;
+}

package/src/activities/execute-cursor/session-lifecycle.ts

@@ -40,7 +40,12 @@ import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 
 import { Agent } from "@cursor/sdk";
-import type { SDKAgent, CursorAgentPlatformOptions, AgentDefinition } from "@cursor/sdk";
+import type {
+  SDKAgent,
+  CursorAgentPlatformOptions,
+  AgentDefinition,
+  ModelParameterValue,
+} from "@cursor/sdk";
 import { withTimeout, TimeoutError } from "../../shared/with-timeout.js";
 import type { CursorMcpServerConfig } from "./mcp-resolver.js";
 
@@ -83,6 +88,15 @@ const LOCAL_SETTING_SOURCES = ["project"] as const;
 export interface CreateAgentOptions {
   apiKey: string;
   model: string;
+  /**
+   * Explicit variant parameters sent with the model selection on every
+   * create AND resume (stigmer/stigmer#357). A bare `{ id }` lets the
+   * Cursor catalog's default variant pick the price, so the caller always
+   * supplies the pinned params from resolveServiceTierParams — possibly
+   * empty (Auto, or a model with no price-bearing parameters), but never
+   * absent by accident.
+   */
+  modelParams?: ModelParameterValue[];
   workspaceDirs: string[];
   sessionId: string;
   /** Durable workspace volume root; the SDK state store lives under it. */
@@ -112,6 +126,8 @@ export interface ResumeAgentOptions {
   /** Durable workspace volume root; the SDK state store lives under it. */
   workspaceRootDir: string;
   model?: string;
+  /** Explicit variant parameters — see {@link CreateAgentOptions.modelParams}. */
+  modelParams?: ModelParameterValue[];
   mcpServers?: Record<string, CursorMcpServerConfig>;
   /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
   agents?: Record<string, AgentDefinition>;
@@ -129,6 +145,8 @@ export interface CloudRepo {
 export interface CreateCloudAgentOptions {
   apiKey: string;
   model?: string;
+  /** Explicit variant parameters — see {@link CreateAgentOptions.modelParams}. */
+  modelParams?: ModelParameterValue[];
   repos: CloudRepo[];
   sessionId: string;
   mcpServers?: Record<string, CursorMcpServerConfig>;
@@ -140,6 +158,8 @@ export interface ResumeCloudAgentOptions {
   apiKey: string;
   agentId: string;
   model?: string;
+  /** Explicit variant parameters — see {@link CreateAgentOptions.modelParams}. */
+  modelParams?: ModelParameterValue[];
   mcpServers?: Record<string, CursorMcpServerConfig>;
   /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
   agents?: Record<string, AgentDefinition>;
@@ -245,7 +265,9 @@ export async function createAgent(options: CreateAgentOptions): Promise<SDKAgent
 
   return Agent.create({
     apiKey: options.apiKey,
-    model: { id: options.model },
+    // Always a full selection — id AND params. A bare { id } would let the
+    // catalog's default variant (account-influenced) pick the price (#357).
+    model: { id: options.model, params: options.modelParams },
     local: { cwd, settingSources: [...LOCAL_SETTING_SOURCES] },
     mcpServers: options.mcpServers as Record<string, any>,
     agents: options.agents,
@@ -273,7 +295,11 @@ export async function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent
 
   return Agent.resume(options.agentId, {
     apiKey: options.apiKey,
-    model: options.model ? { id: options.model } : undefined,
+    // Variant params must be re-supplied on resume exactly like mcpServers:
+    // explicit params hold across resume (verified against the billing
+    // ledger, #357), but an id-only resume would fall back to the catalog
+    // default variant for the new turns.
+    model: options.model ? { id: options.model, params: options.modelParams } : undefined,
     // Neither cwd nor settingSources survive Agent.resume(); both must be
     // re-supplied every turn. Omitting cwd makes the SDK fall back to
     // process.cwd(), which re-roots the agent in the runner's own working
@@ -307,7 +333,7 @@ export async function createCloudAgent(options: CreateCloudAgentOptions): Promis
 
   return Agent.create({
     apiKey: options.apiKey,
-    model: options.model ? { id: options.model } : undefined,
+    model: options.model ? { id: options.model, params: options.modelParams } : undefined,
     cloud: { repos: options.repos },
     mcpServers: options.mcpServers as Record<string, any>,
     agents: options.agents,
@@ -328,7 +354,7 @@ export async function resumeCloudAgent(options: ResumeCloudAgentOptions): Promis
 
   return Agent.resume(options.agentId, {
     apiKey: options.apiKey,
-    model: options.model ? { id: options.model } : undefined,
+    model: options.model ? { id: options.model, params: options.modelParams } : undefined,
     mcpServers: options.mcpServers as Record<string, any>,
     agents: options.agents,
   });
@@ -372,6 +398,7 @@ export async function resolveAgent(
             apiKey: options.apiKey,
             agentId: harnessStateId,
             model: options.model,
+            modelParams: options.modelParams,
             mcpServers: options.mcpServers,
             agents: options.agents,
           })
@@ -382,6 +409,7 @@ export async function resolveAgent(
             workspaceDirs: (options as CreateAgentOptions).workspaceDirs,
             workspaceRootDir: (options as CreateAgentOptions).workspaceRootDir,
             model: options.model,
+            modelParams: options.modelParams,
             mcpServers: options.mcpServers,
             agents: options.agents,
           });

package/src/activities/execute-cursor/usage-accumulator.ts

@@ -13,7 +13,10 @@
  * wire via ProxyUsageReporter once traffic routing (Task 5B) is complete.
  */
 
-import { getCursorModelPricing, computeTurnCost } from "./model-pricing.js";
+import type { ModelParameterValue } from "@cursor/sdk";
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { getCursorModelPricingForVariant, computeTurnCost } from "./model-pricing.js";
 
 export interface TurnUsage {
   readonly inputTokens?: number;
@@ -32,6 +35,10 @@ export interface UsageSnapshot {
   readonly estimatedCostUsd: number;
   readonly model: string;
   readonly observedAt: string;
+  /** Tier the runner requested — always explicit post-translation (#357). */
+  readonly requestedServiceTier: ServiceTier;
+  /** JSON-encoded ModelSelection.params the runner sent; "" when none. */
+  readonly requestedModelParams: string;
 }
 
 const EMPTY_SNAPSHOT: UsageSnapshot = {
@@ -44,6 +51,8 @@ const EMPTY_SNAPSHOT: UsageSnapshot = {
   estimatedCostUsd: 0,
   model: "",
   observedAt: "",
+  requestedServiceTier: ServiceTier.UNSPECIFIED,
+  requestedModelParams: "",
 };
 
 export interface TurnRecord {
@@ -64,7 +73,22 @@ export class UsageAccumulator {
   private observedAt = "";
   private readonly turnRecords: TurnRecord[] = [];
 
-  constructor(private readonly model: string) {}
+  /** JSON-encoded params the runner sent with the model selection (#357). */
+  private readonly requestedModelParams: string;
+
+  constructor(
+    private readonly model: string,
+    /**
+     * The explicit tier the runner requested from the provider. Recorded
+     * verbatim into status as the audit trail that the account default was
+     * never left in control (#357).
+     */
+    private readonly requestedServiceTier: ServiceTier = ServiceTier.UNSPECIFIED,
+    requestedModelParams: readonly ModelParameterValue[] = [],
+  ) {
+    this.requestedModelParams =
+      requestedModelParams.length > 0 ? JSON.stringify(requestedModelParams) : "";
+  }
 
   addTurn(usage: TurnUsage): void {
     const input = usage.inputTokens ?? 0;
@@ -86,7 +110,13 @@ export class UsageAccumulator {
       cacheWriteTokens: cacheWrite,
     });
 
-    const pricing = getCursorModelPricing(this.model);
+    // Estimate at the rates of the variant we explicitly requested — a
+    // FAST run priced at base rates would understate the display estimate
+    // ~4x relative to the authoritative bill (#357).
+    const pricing = getCursorModelPricingForVariant(
+      this.model,
+      this.requestedServiceTier === ServiceTier.FAST ? "fast" : null,
+    );
     this.estimatedCostUsd += computeTurnCost(
       pricing, input, output, cacheWrite, cacheRead,
     );
@@ -122,6 +152,8 @@ export class UsageAccumulator {
       estimatedCostUsd: this.estimatedCostUsd,
       model: this.model,
       observedAt: this.observedAt,
+      requestedServiceTier: this.requestedServiceTier,
+      requestedModelParams: this.requestedModelParams,
     };
   }
 }

package/src/activities/execute-deep-agent/__tests__/mcp-gate.test.ts

@@ -0,0 +1,42 @@
+/**
+ * The deep-agent MCP gate, arm by arm. A missing arm here means a tool
+ * source silently dropped for exactly the agents whose only source it
+ * is — the failure DD-006 D7 documented for channel messaging and the
+ * reason the predicate lives in its own testable module instead of
+ * inline in setup.ts (whose import graph forbids a setup.test.ts).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { shouldConnectMcp } from "../mcp-gate.js";
+
+const nothing = {
+  mcpServerUsageCount: 0,
+  datastoreUsageCount: 0,
+  channelMessagingCount: 0,
+  conversationChannelId: undefined,
+};
+
+describe("shouldConnectMcp", () => {
+  it("skips the MCP block when no tool source exists", () => {
+    expect(shouldConnectMcp(nothing)).toBe(false);
+  });
+
+  it("enters on declared MCP server usages alone", () => {
+    expect(shouldConnectMcp({ ...nothing, mcpServerUsageCount: 1 })).toBe(true);
+  });
+
+  it("enters on datastore usages alone (the records attachment)", () => {
+    expect(shouldConnectMcp({ ...nothing, datastoreUsageCount: 1 })).toBe(true);
+  });
+
+  it("enters on a serving proactive channel alone (the channels attachment)", () => {
+    expect(shouldConnectMcp({ ...nothing, channelMessagingCount: 1 })).toBe(true);
+  });
+
+  it("enters on a channel conversation alone (the conversation attachment)", () => {
+    // The reply-only pilot shape: no declared servers, no datastores,
+    // no proactive channel — the escalation tool is the ONLY source.
+    expect(shouldConnectMcp({ ...nothing, conversationChannelId: "agch_1" })).toBe(true);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/prompt-builder.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { buildEnhancedSystemPrompt } from "../prompt-builder.js";
+import { buildEnhancedSystemPrompt, composeUserMessage } from "../prompt-builder.js";
 import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
 import { SourceType } from "../../../shared/workspace/types.js";
 import type { ProvisionResult } from "../../../shared/workspace/types.js";
@@ -408,3 +408,41 @@ describe("buildEnhancedSystemPrompt", () => {
     });
   });
 });
+
+describe("composeUserMessage (conversation catchup, cloud DD-006 / A27)", () => {
+  const MESSAGE = "where is my order?";
+  const DIGEST =
+    "Customer: I want a refund\nTeammate: I've refunded you in full.";
+
+  it("prepends the framed catchup to the turn's user message — history durability rides the checkpointer, not the rebuilt system prompt", () => {
+    const composed = composeUserMessage(MESSAGE, DIGEST);
+
+    expect(composed.endsWith(MESSAGE)).toBe(true);
+    expect(composed).toContain(DIGEST);
+    expect(composed).toContain("you have not seen");
+    expect(composed.indexOf(DIGEST)).toBeLessThan(composed.indexOf(MESSAGE));
+  });
+
+  it("separates the catchup from the customer's message with a horizontal rule", () => {
+    expect(composeUserMessage(MESSAGE, DIGEST)).toContain("\n\n---\n\n");
+  });
+
+  it("leaves the message untouched when there is no catchup — most turns carry none", () => {
+    expect(composeUserMessage(MESSAGE, undefined)).toBe(MESSAGE);
+  });
+
+  it("never renders in the system prompt — the rebuilt-per-invocation lane would forget the digest one turn later", () => {
+    const prompt = buildEnhancedSystemPrompt({
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "/workspace",
+      injectedFiles: [],
+    });
+
+    expect(prompt).not.toContain("Conversation catchup");
+    expect(prompt).not.toContain("you have not seen");
+  });
+});

package/src/activities/execute-deep-agent/mcp-gate.ts

@@ -0,0 +1,37 @@
+/**
+ * The deep-agent harness's MCP gate: whether this execution enters MCP
+ * resolution at all (resolve, backfill, synthesized-attachment
+ * injection, connect). Unlike the Cursor harness — which resolves MCP
+ * unconditionally — deep-agent skips the whole block when no tool
+ * source exists, so EVERY tool source must appear here or its tools are
+ * silently dropped for exactly the agents whose only source it is
+ * (proactive-messaging DD-006 D7 learned this for channel messaging).
+ *
+ * Extracted from setup.ts as a pure function because setup.ts is
+ * untestable at file load (its import graph is why no setup.test.ts
+ * exists); the gate is the one piece whose regression is silent, so it
+ * gets its own module and an arm-by-arm test.
+ */
+
+/** One flag per tool source. Adding a source? It gates here or it is dropped. */
+export interface McpToolSources {
+  /** Declared MCP server usages (agent spec + session spec). */
+  readonly mcpServerUsageCount: number;
+  /** Declared datastore usages (the records attachment, T05). */
+  readonly datastoreUsageCount: number;
+  /** Serving proactive-messaging channels (the channels attachment, DD-006). */
+  readonly channelMessagingCount: number;
+  /** The serving channel id when this session IS a live channel
+   *  conversation (the conversation attachment, DD-008). */
+  readonly conversationChannelId: string | undefined;
+}
+
+/** True when any tool source demands MCP resolution and connect. */
+export function shouldConnectMcp(sources: McpToolSources): boolean {
+  return (
+    sources.mcpServerUsageCount > 0 ||
+    sources.datastoreUsageCount > 0 ||
+    sources.channelMessagingCount > 0 ||
+    sources.conversationChannelId !== undefined
+  );
+}

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -11,6 +11,7 @@ import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecuti
 import type { ProvisionResult, GitMetadata } from "../../shared/workspace/types.js";
 import { SourceType } from "../../shared/workspace/types.js";
 import { formatContextBridgeText } from "../../shared/context-bridge.js";
+import { formatConversationCatchupText } from "../../shared/conversation-catchup.js";
 import {
   formatSenderIdentityText,
   type SenderIdentity,
@@ -241,9 +242,28 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   return prompt;
 }
 
+/**
+ * Compose the turn's USER MESSAGE for the graph invocation: the framed
+ * conversation catchup (cloud DD-006), when present, prepended to the
+ * customer's message. In the user message and never the system prompt (A27):
+ * the system prompt is rebuilt per invocation and would forget the digest one
+ * turn later, while a message enters the checkpointer with the turn and
+ * persists in history — the same durability the cursor harness gets from its
+ * prompt prefix. The caller's `spec.message` is never mutated; the prepend
+ * exists only in the graph input.
+ */
+export function composeUserMessage(
+  message: string,
+  conversationCatchup: string | undefined,
+): string {
+  return conversationCatchup
+    ? `${formatConversationCatchupText(conversationCatchup)}\n\n---\n\n${message}`
+    : message;
+}
+
 function buildWorkspacePromptSection(
-  provisionResults: ProvisionResult[],
-  containerRoot: string,
+    provisionResults: ProvisionResult[],
+    containerRoot: string,
 ): string {
   if (provisionResults.length === 0) return "";