@stigmer/runner 3.11.0 → 3.12.0

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

@@ -41,7 +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 type { AgentResolution, CreateAgentOptions, CreateCloudAgentOptions } from "./session-lifecycle.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";
 import { MessageAccumulator, cancelInProgressSubAgentProtos, collapseRedundantToolCallTwins } from "./message-translator.js";
@@ -72,7 +72,6 @@ import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/stre
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
 import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mcp-resolver.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
-import { synthesizeDatastoreAttachment } from "../../shared/datastore-attachment.js";
 import {
   discoverChannelMessaging,
   synthesizeChannelAttachment,
@@ -92,7 +91,8 @@ import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
 import { resolveSkills } from "./skill-resolver.js";
 import { removeStigmerSymlink } from "../../shared/workspace/stigmer-link.js";
 import { resolveAttachments } from "./attachment-resolver.js";
-import { buildEnhancedPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { buildEnhancedPrompt, buildHitlRecoveryPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { composeTurnRecoveryDigest } from "./turn-recovery.js";
 import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
 import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import {
@@ -664,35 +664,16 @@ async function executeCursorInner(
       ?? config.stigmerTokenRef?.current
       ?? config.stigmerToken;
 
-    // Phase 4a2: Synthesize the datastore records attachment (T05).
-    // Deliberately AFTER resolve + backfill: the attachment has no
-    // McpServerUsage and reports discovered capabilities, so the
-    // backfill's destructiveHint tightener can never force-gate
-    // delete_record (which on channels would be silently skipped).
-    // Empty approval maps keep it approval-free by construction.
-    if (blueprint.datastoreUsages.length > 0) {
-      const attachment = synthesizeDatastoreAttachment(blueprint.datastoreUsages, {
-        bridgeEndpoint: config.mcpBridgeEndpoint,
-        credential: attachmentCredential,
-        backendEndpoint: config.stigmerBackendEndpoint,
-      });
-      if (attachment) {
-        const resolvedServers = injectSynthesizedAttachment(
-          mcpResolution.resolvedServers, attachment, "datastore records",
-        );
-        mcpResolution = {
-          resolvedServers,
-          cursorConfig: toCursorMcpConfig(resolvedServers),
-        };
-      }
-    }
-
-    // Phase 4a3: Synthesize the channel messaging attachment (DD-006
-    // D7/D8), the records attachment's twin. The discovery read is the
-    // attachment decision — the control plane runs the SAME candidate
-    // computation the send authorization uses — and every failure mode
-    // (no channel, OSS, registry down, pre-3a control plane) degrades
-    // to honest absence: no tool, no section, execution unharmed.
+    // Phase 4a2: Synthesize the channel messaging attachment (DD-006
+    // D7/D8). Deliberately AFTER resolve + backfill: the attachment has
+    // no McpServerUsage and reports discovered capabilities, so the
+    // backfill's destructiveHint tightener can never force-gate its
+    // tools; empty approval maps keep it approval-free by construction.
+    // The discovery read is the attachment decision — the control plane
+    // runs the SAME candidate computation the send authorization uses —
+    // and every failure mode (no channel, OSS, registry down, pre-3a
+    // control plane) degrades to honest absence: no tool, no section,
+    // execution unharmed.
     const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
     if (channelMessaging.length > 0) {
       const attachment = synthesizeChannelAttachment(channelMessaging, {
@@ -801,6 +782,7 @@ async function executeCursorInner(
     const attachmentEntries = attachmentResults.map((a) => ({
       path: a.relativePath,
       ...(a.renamedFrom !== undefined ? { renamedFrom: a.renamedFrom } : {}),
+      ...(a.downloadUrl !== undefined ? { downloadUrl: a.downloadUrl } : {}),
     }));
     // Vision facts, derived once from the single resolution result: the
     // images the model will see inline (in attachment order) and the ones
@@ -1146,13 +1128,13 @@ async function executeCursorInner(
       instructions: blueprint.instructions,
       userMessage: spec.message,
       skills: skillMetadata,
-      datastoreUsages: blueprint.datastoreUsages,
       channelMessaging,
       subAgents: blueprint.subAgents,
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
       attachments: attachmentEntries,
       vision: visionPromptInfo,
+      downloadUrlKind: artifactStorage?.downloadUrlKind,
       pendingApprovals: adjudicatedApprovals,
       appliedToolCallIds,
       interactionMode,
@@ -1161,28 +1143,43 @@ async function executeCursorInner(
       senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
       sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
       conversationCatchup: readConversationCatchup(spec.conversationCatchup),
+      // The turn's recorded transcript, seeded from the persisted execution
+      // on a reinvocation (Phase 3). Consumed only by the HITL-recovery
+      // shape — reached from HERE when the stored handle failed to resume
+      // at resolution time (issue #366 crossing 2).
+      turnRecoveryDigest: isReinvocation
+        ? composeTurnRecoveryDigest(status.messages)
+        : undefined,
     });
 
-    // Phase 10a: Inject structured output instruction for Cursor harness
-    let effectivePrompt = prompt;
-    if (structuredOutputSchema) {
-      const schemaStr = JSON.stringify(structuredOutputSchema, null, 2);
-      effectivePrompt += `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
-    }
+    // Phase 10a: Inject the structured output instruction for the Cursor
+    // harness. A per-turn directive, so like buildFromPlan it must ride every
+    // prompt this turn sends — the primary AND the poisoned-handle recovery
+    // rebuild (the transport retry re-sends effectivePrompt and inherits it).
+    const withStructuredOutputDirective = (basePrompt: string): string =>
+      appendStructuredOutputDirective(basePrompt, structuredOutputSchema);
+    const effectivePrompt = withStructuredOutputDirective(prompt);
 
     // Phase 10a1: The turn's vision payload. The invariant is "images
-    // accompany the user's turn message — where the message goes, they go":
-    // every send that delivers this turn's message carries them (the primary
-    // send and both fresh-agent recovery retries, whose empty conversations
-    // genuinely need the re-send), while a HITL re-invocation — whose prompt
-    // carries no user message and whose resumed agent already holds the
-    // images in its native conversation — carries none. Computed ONCE here so
-    // all send sites agree by construction.
-    const turnImages = isHitlReinvocation(approvalDecisions)
-      ? []
-      : toCursorImages(visionImages);
-    const toSendMessage = (sendPrompt: string): string | SDKUserMessage =>
-      turnImages.length > 0 ? { text: sendPrompt, images: turnImages } : sendPrompt;
+    // accompany the user's turn message, wherever the conversation does not
+    // already hold them" (primarySendCarriesImages): the ONLY send that
+    // skips them is a HITL re-invocation of a successfully RESUMED agent,
+    // whose native conversation carries the images from the original send.
+    // Every send that starts an empty conversation re-delivers them — the
+    // ordinary first/fresh-agent primary send, the HITL primary send after a
+    // resolution-time resume failure, and both mid-send recovery retries
+    // (which always run on a fresh agent, so their sites pass turnImages
+    // unconditionally). Attachments re-resolve on every invocation
+    // (Phase 5b), so the bytes are in hand even on a re-invocation.
+    const turnImages = toCursorImages(visionImages);
+    const primarySendImages = primarySendCarriesImages(approvalDecisions, resolution.reason)
+      ? turnImages
+      : [];
+    const toSendMessage = (
+      sendPrompt: string,
+      images: { data: string; mimeType: string }[],
+    ): string | SDKUserMessage =>
+      images.length > 0 ? { text: sendPrompt, images } : sendPrompt;
 
     // Phase 10a2: Log Stigmer preamble size for context trimming diagnostics
     const promptChars = effectivePrompt.length;
@@ -1298,7 +1295,7 @@ async function executeCursorInner(
     // The stall watchdog is armed inside consumeCursorTurnStream (it needs the
     // run to cancel), stored on turnState.stallWatchdog so this shared onDelta can
     // reset it and the activity's finally can stop it as a backstop.
-    const run = await resolution.agent.send(toSendMessage(effectivePrompt), {
+    const run = await resolution.agent.send(toSendMessage(effectivePrompt, primarySendImages), {
       onDelta: (event) => {
         if (!turnFirstEventEmitted) {
           turnFirstEventEmitted = true;
@@ -1669,10 +1666,11 @@ async function executeCursorInner(
       // poisoned-handle path leaked the fresh agent — it closed the stale one.)
       resolution = { ...resolution, agent: freshAgent, agentId: freshAgent.agentId, isNew: true };
       turnState.streamErrorMessage = undefined;
-      // The retry carries the turn's images too (same toSendMessage): the
-      // fresh agent's conversation is empty, so skipping them here would
-      // silently lose the user's photo on a recovered turn.
-      const retryRun = await freshAgent.send(toSendMessage(retryPrompt), {
+      // The retry always carries the turn's full image payload — never the
+      // primary send's HITL-trimmed set: the fresh agent's conversation is
+      // empty, so skipping them here would silently lose the user's photo on
+      // a recovered turn (issue #366's vision corollary).
+      const retryRun = await freshAgent.send(toSendMessage(retryPrompt, turnImages), {
         onDelta: makeCursorTurnOnDelta(onDeltaDeps),
       });
       await consumeCursorTurnStream(retryRun, streamDeps);
@@ -1804,14 +1802,18 @@ async function executeCursorInner(
             instructions: blueprint.instructions,
             userMessage: spec.message,
             skills: skillMetadata,
-            datastoreUsages: blueprint.datastoreUsages,
             channelMessaging,
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachments: attachmentEntries,
             vision: visionPromptInfo,
+            downloadUrlKind: artifactStorage?.downloadUrlKind,
             pendingApprovals: adjudicatedApprovals,
+            // Without the applied set, the HITL-recovery prompt would tell
+            // the fresh agent to carry out writes the runner already
+            // exact-applied (the primary call at Phase 10 passes it too).
+            appliedToolCallIds,
             interactionMode,
             // buildFromPlan was silently dropped here until T03 Sitting 3 —
             // a build turn that hit handle recovery lost its directive. The
@@ -1822,6 +1824,10 @@ async function executeCursorInner(
             senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
             sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
             conversationCatchup: readConversationCatchup(spec.conversationCatchup),
+            // Composed fresh (not reused from Phase 10): the failed primary
+            // stream may have appended partial work onto status.messages,
+            // and the replacement agent should know about that too.
+            turnRecoveryDigest: composeTurnRecoveryDigest(status.messages),
           });
 
           console.log(
@@ -1837,7 +1843,14 @@ async function executeCursorInner(
             console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
           }
 
-          const outcome = await runRecoveryStream(freshAgent, freshPrompt);
+          // Same per-turn directive rule as buildFromPlan above: a
+          // structured-output turn keeps its output contract on the rebuilt
+          // prompt (the transport retry re-sends effectivePrompt and
+          // inherits it without help).
+          const outcome = await runRecoveryStream(
+            freshAgent,
+            withStructuredOutputDirective(freshPrompt),
+          );
           if (!outcome.proceeded) {
             if (outcome.terminal.kind === "return") return slimStatus(status);
             throw new CancelledFailure(outcome.terminal.message);
@@ -2335,8 +2348,6 @@ export interface BuildPromptInput {
   instructions: string;
   userMessage: string;
   skills: import("./prompt-builder.js").SkillMetadata[];
-  /** Datastores attached via `datastore_usages` — the `<available_datastores>` section. */
-  datastoreUsages?: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").DatastoreUsage[];
   /**
    * Serving proactive channels + their templates (the DD-006 D2
    * discovery read) — the `<available_channel_templates>` section.
@@ -2356,6 +2367,12 @@ export interface BuildPromptInput {
    * catchup — it rides both the enhanced prompt and a resumed turn's prefix.
    */
   vision?: import("./prompt-builder.js").VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — keys
+   * the input-files hand-off wording. Sourced from the resolved
+   * artifactStorage's self-description; absent when no storage resolved.
+   */
+  downloadUrlKind?: import("../../shared/attachment-download-urls.js").DownloadUrlKind;
   pendingApprovals: import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb").PendingApproval[];
   /**
    * Approved whole-file writes the runner already applied itself (exact-apply).
@@ -2400,6 +2417,15 @@ export interface BuildPromptInput {
    * usually blank.
    */
   conversationCatchup?: string;
+  /**
+   * The turn's recorded transcript rendered as digest lines
+   * (turn-recovery.ts), composed from `status.messages` at the call site.
+   * Consumed ONLY by the HITL-recovery shape — a fresh agent that replaced
+   * a lost one mid-HITL needs the story of the work it no longer remembers
+   * (issue #366); every other shape either has native context or no prior
+   * work to tell.
+   */
+  turnRecoveryDigest?: string;
 }
 
 /**
@@ -2411,20 +2437,28 @@ export interface BuildPromptInput {
  * volume, or cloud server-side state) — there is no separate continuation
  * store. The prompt therefore depends only on how the agent was resolved:
  *
- * 1. HITL reinvocation        -> buildReinvocationPrompt (approval decisions;
- *                                 the resumed agent's native context carries
- *                                 the prior conversation)
- * 2. resumed_successfully      -> raw userMessage (native context carries it)
- * 3. first execution / fresh   -> buildEnhancedPrompt (full instructions +
+ * 1. HITL reinvocation,        -> buildReinvocationPrompt (approval decisions
+ *    resumed agent                 only; the resumed agent's native context
+ *                                  carries the prior conversation)
+ * 2. HITL reinvocation,        -> buildHitlRecoveryPrompt (full context +
+ *    fresh agent after            the turn's recorded transcript + decisions;
+ *    resume failure               the replacement agent's conversation is
+ *                                 empty, and both fresh-agent crossings —
+ *                                 resolution-time resume failure and mid-send
+ *                                 poisoned-handle recovery — land here by
+ *                                 keying on the reason, issue #366)
+ * 3. resumed_successfully      -> raw userMessage (native context carries it)
+ * 4. first execution / fresh   -> buildEnhancedPrompt (full instructions +
  *    agent after resume failure   skills; no prior conversation to inherit)
  */
 /**
  * Whether this activity invocation is a HITL re-invocation — the turn resumes
  * an agent purely to convey approval decisions, carrying NO user message.
- * The single discriminator for everything that must ride with the user's
- * message and nothing else: the reinvocation prompt shape (below) and the
- * vision payload (images accompany the message; a resumed agent already holds
- * them in its native conversation).
+ * Discriminates the two surfaces that depend on the agent already holding
+ * this turn's content natively — the prompt shape (below) and the primary
+ * send's vision payload — but never alone: both pair it with
+ * `resolution.reason`, because a FRESH agent mid-HITL holds nothing and
+ * needs the full re-delivery (issue #366).
  */
 export function isHitlReinvocation(
   approvalDecisions: Map<string, ApprovalAction> | undefined,
@@ -2432,6 +2466,39 @@ export function isHitlReinvocation(
   return approvalDecisions !== undefined && approvalDecisions.size > 0;
 }
 
+/**
+ * Whether the PRIMARY send delivers the turn's vision payload. The invariant
+ * is "images accompany the user's turn message, wherever the conversation
+ * does not already hold them" — so the only send that skips them is a HITL
+ * re-invocation of a successfully RESUMED agent, whose native conversation
+ * carries the images from the original send. A fresh agent mid-HITL
+ * (resolution-time resume failure — issue #366's vision corollary) holds
+ * nothing and needs the re-delivery. The mid-send recovery retries always
+ * run on a fresh agent, so their send sites carry the payload
+ * unconditionally rather than consulting this.
+ */
+export function primarySendCarriesImages(
+  approvalDecisions: Map<string, ApprovalAction> | undefined,
+  reason: AgentResolutionReason,
+): boolean {
+  return !(isHitlReinvocation(approvalDecisions) && reason === "resumed_successfully");
+}
+
+/**
+ * Append the structured-output contract to a prompt when the execution
+ * requests one. A per-turn directive (the buildFromPlan rule): it must ride
+ * every prompt this turn sends — the primary send AND the poisoned-handle
+ * recovery rebuild, which previously lost it (issue #366 ride-along).
+ */
+export function appendStructuredOutputDirective(
+  basePrompt: string,
+  schema: Record<string, unknown> | undefined,
+): string {
+  if (!schema) return basePrompt;
+  const schemaStr = JSON.stringify(schema, null, 2);
+  return basePrompt + `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
+}
+
 export function buildPrompt(input: BuildPromptInput): string {
   const {
     resolution,
@@ -2448,10 +2515,44 @@ export function buildPrompt(input: BuildPromptInput): string {
     conversationCatchup,
   } = input;
 
-  // HITL reinvocation: the agent is resumed, so its native context carries the
-  // prior conversation; the reinvocation prompt conveys the approval decisions
-  // (and which approved writes the runner already exact-applied).
+  // HITL reinvocation: the decisions-only prompt is correct ONLY while the
+  // agent's native context still carries the prior conversation — which only
+  // resumed_successfully guarantees. Any other reason means a fresh agent
+  // mid-HITL (in practice created_after_resume_failure: the stored handle
+  // failed to resume, or a poisoned handle was replaced mid-send), which
+  // gets the full recovery shape instead — enhanced context + the turn's
+  // recorded transcript + the same decisions — because the bare decisions on
+  // an empty conversation strand the agent with instructions and no story,
+  // and the session inherits that amnesia permanently (issue #366).
   if (isHitlReinvocation(approvalDecisions)) {
+    if (resolution.reason !== "resumed_successfully") {
+      return buildHitlRecoveryPrompt(
+        {
+          instructions,
+          userMessage,
+          skills,
+          channelMessaging: input.channelMessaging ?? [],
+          subAgents,
+          workspaceDirs,
+          workspaceFileRefs,
+          attachments,
+          vision: input.vision,
+          downloadUrlKind: input.downloadUrlKind,
+          interactionMode,
+          buildFromPlan,
+          contextBridge: input.contextBridge,
+          senderIdentity: input.senderIdentity,
+          sessionContext: input.sessionContext,
+          conversationCatchup,
+        },
+        {
+          turnDigest: input.turnRecoveryDigest,
+          pendingApprovals: input.pendingApprovals,
+          approvalDecisions,
+          appliedToolCallIds: input.appliedToolCallIds,
+        },
+      );
+    }
     return buildReinvocationPrompt(
       input.pendingApprovals,
       approvalDecisions,
@@ -2478,7 +2579,7 @@ export function buildPrompt(input: BuildPromptInput): string {
       formatInteractionModePrefix(interactionMode),
       formatImplementPlanSection(buildFromPlan, attachments),
       attachments.length > 0
-        ? formatInputFiles(attachments, input.vision)
+        ? formatInputFiles(attachments, input.vision, input.downloadUrlKind)
         : undefined,
       conversationCatchup !== undefined
         ? formatConversationCatchupSection(conversationCatchup)
@@ -2496,13 +2597,13 @@ export function buildPrompt(input: BuildPromptInput): string {
     instructions,
     userMessage,
     skills,
-    datastoreUsages: input.datastoreUsages ?? [],
     channelMessaging: input.channelMessaging ?? [],
     subAgents,
     workspaceDirs,
     workspaceFileRefs,
     attachments,
     vision: input.vision,
+    downloadUrlKind: input.downloadUrlKind,
     interactionMode,
     buildFromPlan,
     contextBridge: input.contextBridge,

package/src/activities/execute-cursor/model-pricing-data.ts

@@ -8,7 +8,12 @@
  * endpoint is unreachable.
  */
 
-import { resolveModelRegistryUrl, buildRegistryHeaders } from "../../shared/registry-endpoint.js";
+import {
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  REGISTRY_RETRY_POLICY,
+} from "../../shared/registry-endpoint.js";
+import { fetchWithRetry } from "../../shared/http-retry.js";
 
 /** Per-million rates for a speed/mode variant (e.g. "fast") of a base model. */
 export interface CursorVariantPricing {
@@ -53,6 +58,10 @@ interface RegistryEntry {
 }
 
 const CACHE_TTL_MS = 3_600_000; // 1 hour
+// Failed fetches are cached much shorter than successes (the model-registry.ts
+// policy): a transient failure must not pin DEFAULT_PRICING — wrong rates for
+// cost tracking — for a full hour.
+const FAILURE_CACHE_TTL_MS = 60_000;
 
 const DEFAULT_PRICING: CursorModelPricing = {
   model: "unknown",
@@ -104,7 +113,11 @@ function parseVariants(
 }
 
 async function fetchFromApi(): Promise<readonly CursorModelPricing[]> {
-  const res = await fetch(resolveModelRegistryUrl(), { headers: buildRegistryHeaders() });
+  const res = await fetchWithRetry(
+    resolveModelRegistryUrl(),
+    { headers: buildRegistryHeaders() },
+    REGISTRY_RETRY_POLICY,
+  );
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   const table = parsePricingTable(data);
@@ -138,7 +151,7 @@ export async function getPricingTable(): Promise<readonly CursorModelPricing[]>
         `Failed to fetch model registry from API, using default pricing: ${err}`,
       );
       const fallback = [DEFAULT_PRICING];
-      cache = { data: fallback, expiresAt: Date.now() + CACHE_TTL_MS };
+      cache = { data: fallback, expiresAt: Date.now() + FAILURE_CACHE_TTL_MS };
       return fallback;
     })
     .finally(() => {
@@ -148,4 +161,10 @@ export async function getPricingTable(): Promise<readonly CursorModelPricing[]>
   return inflightFetch;
 }
 
+/** Exposed for testing — resets the in-memory cache. */
+export function _resetPricingCache(): void {
+  cache = null;
+  inflightFetch = null;
+}
+
 export { DEFAULT_PRICING };

package/src/activities/execute-cursor/prompt-builder.ts

@@ -17,12 +17,11 @@
  */
 
 import { resolve } from "node:path";
-import type { DatastoreUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { formatContextBridgeText } from "../../shared/context-bridge.js";
 import { formatConversationCatchupText } from "../../shared/conversation-catchup.js";
-import { formatDatastoresSection } from "../../shared/datastore-attachment.js";
 import {
   formatChannelTemplatesSection,
   type ChannelMessagingInfo,
@@ -36,6 +35,11 @@ import {
   visionDisclosureLines,
   type NotViewableEntry,
 } from "../../shared/attachment-vision.js";
+import {
+  downloadUrlDisclosureLine,
+  type DownloadUrlKind,
+} from "../../shared/attachment-download-urls.js";
+import { formatTurnRecoveryText } from "./turn-recovery.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -81,21 +85,18 @@ export interface AttachmentPromptEntry {
   path: string;
   /** Original filename, present only when a duplicate name was renamed. */
   renamedFrom?: string;
+  /**
+   * Download URL for the attachment's stored object, when one was minted
+   * (shared/attachment-download-urls.ts) — rendered beside the path so the
+   * agent can hand the file to tools that cannot read this filesystem.
+   */
+  downloadUrl?: string;
 }
 
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
   skills: SkillMetadata[];
-  /**
-   * Datastores attached via `datastore_usages` — rendered as the
-   * `<available_datastores>` section (DD-005 SD-5, skills precedent)
-   * pointing the model at the synthesized record tools. Always the healthy
-   * rendering here: the Cursor SDK connects MCP itself, so this harness can
-   * never observe the live roster — the section's standing
-   * failure-disclosure instruction is its whole coverage (issue #325).
-   */
-  datastoreUsages?: DatastoreUsage[];
   /**
    * Serving proactive channels + their approved templates — rendered as
    * the `<available_channel_templates>` section (proactive-messaging
@@ -108,6 +109,12 @@ export interface EnhancedPromptOptions {
   attachments: AttachmentPromptEntry[];
   /** Inline/degraded image facts for the input-files section (T04 vision). */
   vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints — keys the input-files
+   * section's hand-off wording (attachment-download-urls.ts). One turn-level
+   * fact: all attachments ride the one configured storage.
+   */
+  downloadUrlKind?: DownloadUrlKind;
   interactionMode?: InteractionMode;
   /**
    * The execution is a Build-from-plan turn (spec.execution_config
@@ -182,10 +189,6 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatSkillsSection(options.skills));
   }
 
-  if (options.datastoreUsages !== undefined && options.datastoreUsages.length > 0) {
-    sections.push(formatDatastoresSection(options.datastoreUsages));
-  }
-
   if (options.channelMessaging !== undefined && options.channelMessaging.length > 0) {
     // "" when nothing is sendable — the tool alone still serves text
     // sends inside a 24-hour window (DD-006 D6).
@@ -211,7 +214,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
   }
 
   if (options.attachments.length > 0) {
-    sections.push(formatInputFiles(options.attachments, options.vision));
+    sections.push(formatInputFiles(options.attachments, options.vision, options.downloadUrlKind));
   }
 
   if (options.workspaceFileRefs.length > 0) {
@@ -338,6 +341,56 @@ export function buildReinvocationPrompt(
   return parts.join("\n\n");
 }
 
+/**
+ * Build the prompt for a fresh agent that replaced a lost one MID-HITL —
+ * the stored handle failed to resume when the approval landed, or the
+ * resumed handle proved poisoned mid-send (issue #366, both crossings).
+ *
+ * A resumed agent gets {@link buildReinvocationPrompt} alone because its
+ * native conversation carries everything else. A replacement agent's
+ * conversation is EMPTY, so the bare decisions prompt would strand it with
+ * instructions and no story — and, because recovery repoints the session at
+ * the new agent, every later turn would inherit that amnesia. This prompt
+ * rebuilds the whole story in chronological-narrative order:
+ *
+ * 1. the full enhanced prompt (blueprint, standing context, protocol, and
+ *    the turn's ORIGINAL user message as `<user_request>`),
+ * 2. `<turn_recovery>` — the state-loss disclosure plus the recorded
+ *    transcript of the turn so far (turn-recovery.ts; rendered even with no
+ *    transcript, since without the disclosure the decisions below would read
+ *    as reactions to proposals this agent never made),
+ * 3. the reinvocation decisions verbatim — already-applied / approved /
+ *    skipped semantics byte-identical to the resumed path, ending on its
+ *    "continue the task" directive.
+ *
+ * Appending past `<user_request>` is the chronology speaking (request →
+ * work done → decisions → continue), the same shape as the activity-level
+ * structured-output suffix.
+ */
+export function buildHitlRecoveryPrompt(
+  options: EnhancedPromptOptions,
+  recovery: {
+    turnDigest: string | undefined;
+    pendingApprovals: PendingApproval[];
+    approvalDecisions: Map<string, ApprovalAction>;
+    appliedToolCallIds?: ReadonlySet<string>;
+  },
+): string {
+  return [
+    buildEnhancedPrompt(options),
+    formatTurnRecoverySection(recovery.turnDigest),
+    buildReinvocationPrompt(
+      recovery.pendingApprovals,
+      recovery.approvalDecisions,
+      recovery.appliedToolCallIds,
+    ),
+  ].join("\n\n---\n\n");
+}
+
+export function formatTurnRecoverySection(digest: string | undefined): string {
+  return `<turn_recovery>\n${formatTurnRecoveryText(digest)}\n</turn_recovery>`;
+}
+
 /**
  * Render a pending approval as a short human-readable action description for the
  * reinvocation prompt. Prefers the already-resolved approval message; falls back
@@ -497,15 +550,28 @@ export function formatWorkspaceContext(dirs: string[]): string {
 export function formatInputFiles(
   attachments: readonly AttachmentPromptEntry[],
   vision?: VisionPromptInfo,
+  downloadUrlKind?: DownloadUrlKind,
 ): string {
   // A duplicate-renamed file (attachment-naming.ts) discloses its original
   // name so the agent can connect "the two report.pdfs" in the user's
-  // message to distinct files on disk.
-  const entries = attachments.map((a) =>
-    a.renamedFrom !== undefined
-      ? `- \`${a.path}\` (renamed from duplicate '${a.renamedFrom}')`
-      : `- \`${a.path}\``,
-  );
+  // message to distinct files on disk. A file with a minted download URL
+  // (attachment-download-urls.ts) lists it beside the path for the remote
+  // hand-off story.
+  const entries = attachments.map((a) => {
+    const rename =
+      a.renamedFrom !== undefined
+        ? ` (renamed from duplicate '${a.renamedFrom}')`
+        : "";
+    const url = a.downloadUrl !== undefined ? ` — download URL: ${a.downloadUrl}` : "";
+    return `- \`${a.path}\`${rename}${url}`;
+  });
+  // The URL hand-off line (shared wording, attachment-download-urls.ts)
+  // renders only when some listed file actually carries a URL — its wording
+  // keys on what kind of URL the storage backend mints.
+  const urlDisclosure =
+    downloadUrlKind !== undefined && attachments.some((a) => a.downloadUrl !== undefined)
+      ? [downloadUrlDisclosureLine(downloadUrlKind)]
+      : [];
   // The vision lines (shared wording, attachment-vision.ts) tell the model
   // which of these files it can already SEE inline versus which degraded to
   // path-only — without them an agent silently ignores a photo the user
@@ -517,6 +583,7 @@ export function formatInputFiles(
     "<input_files>",
     "The following files have been provided as inputs. Read them when relevant to the task:",
     ...entries,
+    ...urlDisclosure,
     ...disclosure,
     "</input_files>",
   ].join("\n");