@stigmer/runner 3.7.0 → 3.9.0

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

@@ -29,10 +29,17 @@
  * the execution with an actionable error.
  */
 
-import { mkdir, copyFile, writeFile } from "node:fs/promises";
+import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import {
+  isVisionCandidate,
+  type VisionBudget,
+  type VisionDegradedReason,
+  type VisionImage,
+  type VisionOutcome,
+} from "../../shared/attachment-vision.js";
 import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
 import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 
@@ -42,6 +49,15 @@ export interface ResolvedAttachment {
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /** Present when the attachment was accepted into the turn's vision payload. */
+  vision?: VisionImage;
+  /**
+   * Present when the attachment was plausibly an image but could not ride
+   * inline (see {@link VisionDegradedReason}) — disclosed in the prompt so the
+   * agent never silently ignores a photo the user believes it can see.
+   * Attachments that were never image-shaped carry neither field.
+   */
+  visionDegraded?: VisionDegradedReason;
 }
 
 export interface AttachmentResolverOptions {
@@ -54,6 +70,12 @@ export interface AttachmentResolverOptions {
    * then fails with an actionable error rather than a silent skip.
    */
   storage: ArtifactStorage | undefined;
+  /**
+   * The turn's vision selector (attachment-vision.ts owns all policy).
+   * `undefined` disables inline image delivery; file materialization is
+   * identical either way — vision is strictly additive.
+   */
+  visionBudget?: VisionBudget;
 }
 
 export class AttachmentResolutionError extends Error {
@@ -109,9 +131,10 @@ async function resolveAttachment(
 ): Promise<ResolvedAttachment> {
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const filename = attachment.filename || basename(attachment.localPath);
+    const filename = safeInputName(attachment.filename || attachment.localPath);
+    let vision: VisionOutcome | undefined;
     try {
-      await copyFile(attachment.localPath, join(inputsDir, filename));
+      vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
     } catch (err) {
       throw new AttachmentResolutionError(
         attachment.filename,
@@ -122,6 +145,7 @@ async function resolveAttachment(
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      ...visionOutcomeFields(vision),
     };
   }
 
@@ -140,7 +164,7 @@ async function resolveAttachment(
     );
   }
 
-  const filename = attachment.filename || basename(attachment.storageKey);
+  const filename = safeInputName(attachment.filename || attachment.storageKey);
   let content: Buffer;
   try {
     content = await options.storage.download(attachment.storageKey);
@@ -153,8 +177,70 @@ async function resolveAttachment(
   }
   await writeFile(join(inputsDir, filename), content);
 
+  // The bytes are already in hand for the file write — offer them to the
+  // vision budget before they go out of scope (the sniff decides eligibility;
+  // no pre-filter needed on this branch).
+  const vision = options.visionBudget?.offer(filename, attachment.contentType, content);
+
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+    ...visionOutcomeFields(vision),
   };
 }
+
+/**
+ * Materialize a local-path attachment, reading the bytes only when they are
+ * plausibly a vision candidate within the per-image cap — a 25 MB PDF (or an
+ * oversized image, detected by stat) keeps the plain `copyFile` and never
+ * enters memory. Returns the vision outcome, or `undefined` when vision is
+ * disabled or the file is not a candidate.
+ */
+async function materializeLocalFile(
+  attachment: Attachment,
+  filename: string,
+  inputsDir: string,
+  visionBudget: VisionBudget | undefined,
+): Promise<VisionOutcome | undefined> {
+  const dest = join(inputsDir, filename);
+  if (!visionBudget || !isVisionCandidate(attachment.contentType, filename)) {
+    await copyFile(attachment.localPath, dest);
+    return undefined;
+  }
+  const info = await stat(attachment.localPath);
+  if (visionBudget.exceedsImageCap(info.size)) {
+    await copyFile(attachment.localPath, dest);
+    return visionBudget.offerOversized();
+  }
+  const content = await readFile(attachment.localPath);
+  await writeFile(dest, content);
+  return visionBudget.offer(filename, attachment.contentType, content);
+}
+
+function visionOutcomeFields(
+  outcome: VisionOutcome | undefined,
+): Pick<ResolvedAttachment, "vision" | "visionDegraded"> {
+  if (outcome === undefined || outcome.kind === "skipped") return {};
+  return outcome.kind === "accepted"
+    ? { vision: outcome.image }
+    : { visionDegraded: outcome.reason };
+}
+
+/**
+ * Reduce a caller-influenced name to a single, safe path component for writing
+ * under the inputs dir. The name (an attachment's original filename, or a
+ * storage key's tail) is untrusted — a value like `../../evil.md` would steer
+ * the write outside `.stigmer/inputs/`. Taking the basename strips any path
+ * structure; the residual `.`/`..`/empty cases (which basename does not strip)
+ * are rejected loudly so the write target is always a real file inside inputs.
+ */
+function safeInputName(raw: string): string {
+  const name = basename(raw);
+  if (name === "" || name === "." || name === "..") {
+    throw new AttachmentResolutionError(
+      raw,
+      `'${raw}' does not yield a usable filename for materialization`,
+    );
+  }
+  return name;
+}

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

@@ -35,7 +35,7 @@ import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agent
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionControlSignal, ExecutionPhase, FileChangeSetStatus, InteractionMode, MessageType, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { Run, ConversationTurn } from "@cursor/sdk";
+import type { Run, ConversationTurn, SDKUserMessage } from "@cursor/sdk";
 
 import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
@@ -48,6 +48,7 @@ import { MessageAccumulator, cancelInProgressSubAgentProtos, collapseRedundantTo
 import { utcTimestamp, persistStatus, reportSetupProgress, slimStatus } from "../../shared/status.js";
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
+import { readConversationCatchup } from "../../shared/conversation-catchup.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
 import {
   injectCallerIdentityEnv,
@@ -57,6 +58,12 @@ import { readSessionContext } from "../../shared/session-context.js";
 import { withholdSecretContentFromMessages } from "../../shared/tool-row.js";
 import { StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
 import { resolveUsableArtifactStorage, loadArtifactStorageConfig, type ArtifactStorage } from "../../shared/artifact-storage.js";
+import {
+  CURSOR_VISION_PROFILE,
+  VisionBudget,
+  toCursorImages,
+  type NotViewableEntry,
+} from "../../shared/attachment-vision.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -69,6 +76,10 @@ import {
   discoverChannelMessaging,
   synthesizeChannelAttachment,
 } from "../../shared/channel-attachment.js";
+import {
+  readChannelConversationId,
+  synthesizeConversationAttachment,
+} from "../../shared/conversation-attachment.js";
 import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
 import { mergeApprovalPolicies } from "./approval-policy.js";
 import { deriveActiveLeases, isUnattendedApprovalMode } from "../../shared/approval-policy.js";
@@ -79,7 +90,7 @@ 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, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { buildEnhancedPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
 import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
 import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import {
@@ -685,6 +696,31 @@ async function executeCursorInner(
         };
       }
     }
+
+    // Phase 4a4: Synthesize the conversation participation attachment
+    // (channel-conversations DD-008 D-c) — the third sibling. The
+    // channel-id session label IS the attachment decision (stamped
+    // server-side on every channel session; a free local read, unlike
+    // the channels discovery RPC above). HTTP-only: synthesize answers
+    // undefined with no bridge endpoint by design (see
+    // shared/conversation-attachment.ts).
+    const conversationAttachment = synthesizeConversationAttachment(
+      readChannelConversationId(session.metadata?.labels),
+      {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: attachmentCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+      },
+    );
+    if (conversationAttachment) {
+      const resolvedServers = injectSynthesizedAttachment(
+        mcpResolution.resolvedServers, conversationAttachment, "conversation participation",
+      );
+      mcpResolution = {
+        resolvedServers,
+        cursorConfig: toCursorMcpConfig(resolvedServers),
+      };
+    }
     const mcpConfig = mcpResolution.cursorConfig;
 
     // Phase 4b: Merge approval policies from all layers.
@@ -731,14 +767,38 @@ async function executeCursorInner(
 
     // Phase 5b: Resolve attachments (fail-hard — explicit user inputs; see
     // attachment-resolver.ts). Downloads by storage key through the same
-    // artifactStorage resolved for status offload above.
+    // artifactStorage resolved for status offload above. The vision budget
+    // rides along so image attachments are selected for inline delivery while
+    // their bytes are already in hand (attachment-vision.ts owns all policy).
+    const visionBudget = new VisionBudget(CURSOR_VISION_PROFILE);
     const attachmentResults = await resolveAttachments(spec.attachments, {
       sessionId,
       primaryWorkspaceDir,
       mode: config.mode,
       storage: artifactStorage,
+      visionBudget,
     });
     const attachmentPaths = attachmentResults.map((a) => a.relativePath);
+    // Vision facts, derived once from the single resolution result: the
+    // images the model will see inline (in attachment order) and the ones
+    // that degraded to path-only, disclosed in the prompt.
+    const visionImages = attachmentResults.flatMap((a) => (a.vision ? [a.vision] : []));
+    const visionNotViewable: NotViewableEntry[] = attachmentResults.flatMap((a) =>
+      a.visionDegraded ? [{ path: a.relativePath, reason: a.visionDegraded }] : [],
+    );
+    const visionPromptInfo = visionImages.length > 0 || visionNotViewable.length > 0
+      ? {
+          inlineFilenames: visionImages.map((v) => v.filename),
+          notViewable: visionNotViewable,
+        }
+      : undefined;
+    if (visionPromptInfo) {
+      console.log(
+        `[attachment-vision] execution=${executionId} inline=${visionImages.length} ` +
+        `(${visionImages.reduce((n, v) => n + v.byteSize, 0)} bytes) ` +
+        `degraded=${JSON.stringify(visionNotViewable.map((d) => `${d.path}:${d.reason}`))}`,
+      );
+    }
     setupTiming.mark("resolve_attachments");
 
     // Phase 5b3: Exact-apply approved whole-file writes (HITL "what you approve
@@ -1064,6 +1124,7 @@ async function executeCursorInner(
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
       attachmentPaths,
+      vision: visionPromptInfo,
       pendingApprovals: adjudicatedApprovals,
       appliedToolCallIds,
       interactionMode,
@@ -1071,6 +1132,7 @@ async function executeCursorInner(
       contextBridge: readContextBridge(blueprint.sessionSpec.metadata),
       senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
       sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
+      conversationCatchup: readConversationCatchup(spec.conversationCatchup),
     });
 
     // Phase 10a: Inject structured output instruction for Cursor harness
@@ -1080,6 +1142,20 @@ async function executeCursorInner(
       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 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;
+
     // Phase 10a2: Log Stigmer preamble size for context trimming diagnostics
     const promptChars = effectivePrompt.length;
     const promptEstimatedTokens = Math.ceil(promptChars / 4);
@@ -1194,7 +1270,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(effectivePrompt, {
+    const run = await resolution.agent.send(toSendMessage(effectivePrompt), {
       onDelta: (event) => {
         if (!turnFirstEventEmitted) {
           turnFirstEventEmitted = true;
@@ -1565,7 +1641,10 @@ 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;
-      const retryRun = await freshAgent.send(retryPrompt, {
+      // 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), {
         onDelta: makeCursorTurnOnDelta(onDeltaDeps),
       });
       await consumeCursorTurnStream(retryRun, streamDeps);
@@ -1704,11 +1783,18 @@ async function executeCursorInner(
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachmentPaths,
+            vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             interactionMode,
+            // buildFromPlan was silently dropped here until T03 Sitting 3 —
+            // a build turn that hit handle recovery lost its directive. The
+            // fresh prompt must carry every per-turn directive the original
+            // did.
+            buildFromPlan,
             contextBridge: readContextBridge(blueprint.sessionSpec.metadata),
             senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
             sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
+            conversationCatchup: readConversationCatchup(spec.conversationCatchup),
           });
 
           console.log(
@@ -2273,6 +2359,12 @@ export interface BuildPromptInput {
   workspaceDirs: string[];
   workspaceFileRefs: string[];
   attachmentPaths: string[];
+  /**
+   * Vision facts for the input-files section (T04): which attachments the
+   * model sees inline and which degraded to path-only. PER-TURN like the
+   * catchup — it rides both the enhanced prompt and a resumed turn's prefix.
+   */
+  vision?: import("./prompt-builder.js").VisionPromptInfo;
   pendingApprovals: import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb").PendingApproval[];
   /**
    * Approved whole-file writes the runner already applied itself (exact-apply).
@@ -2305,6 +2397,18 @@ export interface BuildPromptInput {
    * turn.
    */
   sessionContext?: string;
+  /**
+   * Conversation catchup from the execution spec's `conversation_catchup`
+   * (cloud DD-006): what happened on the channel conversation that the
+   * agent has not seen. PER-TURN, so unlike the three standing values
+   * above it rides BOTH prompt paths — the enhanced prompt and a resumed
+   * turn's prefix (the `interaction_mode` shape). Handback lands
+   * mid-session on a resumed agent: the resumed path is the one that
+   * matters. Once delivered, the digest persists in the agent's own
+   * conversation store; the next turn's field is composed fresh and is
+   * usually blank.
+   */
+  conversationCatchup?: string;
 }
 
 /**
@@ -2323,6 +2427,20 @@ export interface BuildPromptInput {
  * 3. 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).
+ */
+export function isHitlReinvocation(
+  approvalDecisions: Map<string, ApprovalAction> | undefined,
+): approvalDecisions is Map<string, ApprovalAction> {
+  return approvalDecisions !== undefined && approvalDecisions.size > 0;
+}
+
 export function buildPrompt(input: BuildPromptInput): string {
   const {
     resolution,
@@ -2336,14 +2454,13 @@ export function buildPrompt(input: BuildPromptInput): string {
     attachmentPaths,
     interactionMode,
     buildFromPlan,
+    conversationCatchup,
   } = input;
 
-  const isHitlReinvocation = approvalDecisions !== undefined && approvalDecisions.size > 0;
-
   // 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).
-  if (isHitlReinvocation) {
+  if (isHitlReinvocation(approvalDecisions)) {
     return buildReinvocationPrompt(
       input.pendingApprovals,
       approvalDecisions,
@@ -2353,15 +2470,28 @@ export function buildPrompt(input: BuildPromptInput): string {
 
   // A successfully resumed agent carries its own conversation context via the
   // SDK's native store — send the raw user message with no preamble. The
-  // exceptions are the per-EXECUTION directives, which never inherit from the
+  // exceptions are the per-EXECUTION values, which never inherit from the
   // session's first turn: the interaction-mode prefix (a follow-up can switch
   // Agent→Plan mid-session, and for Cursor the prompt is the only plan-mode
-  // enforcement) and the implement-plan directive (the build turn is usually
-  // a follow-up on a resumed agent).
+  // enforcement), the implement-plan directive (the build turn is usually a
+  // follow-up on a resumed agent), THIS turn's attachments (spec.attachments
+  // is per-execution — a file sent on a follow-up turn materializes for this
+  // turn and would otherwise never be announced at all), and the conversation
+  // catchup (handback ALWAYS lands mid-session on a resumed agent — this
+  // prefix is the property the metadata lane structurally cannot deliver,
+  // cloud DD-006). Catchup last: it is context, and context sits closest to
+  // the task (the enhanced prompt's own ordering doctrine); the input files
+  // precede it because they are this turn's payload, not background.
   if (resolution.reason === "resumed_successfully") {
     const prefixes = [
       formatInteractionModePrefix(interactionMode),
       formatImplementPlanSection(buildFromPlan, attachmentPaths),
+      attachmentPaths.length > 0
+        ? formatInputFiles(attachmentPaths, input.vision)
+        : undefined,
+      conversationCatchup !== undefined
+        ? formatConversationCatchupSection(conversationCatchup)
+        : undefined,
     ].filter((p): p is string => p !== undefined);
     return prefixes.length > 0
       ? [...prefixes, userMessage].join("\n\n")
@@ -2381,11 +2511,13 @@ export function buildPrompt(input: BuildPromptInput): string {
     workspaceDirs,
     workspaceFileRefs,
     attachmentPaths,
+    vision: input.vision,
     interactionMode,
     buildFromPlan,
     contextBridge: input.contextBridge,
     senderIdentity: input.senderIdentity,
     sessionContext: input.sessionContext,
+    conversationCatchup,
   });
 }
 

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

@@ -21,6 +21,7 @@ import type { DatastoreUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agenti
 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,
@@ -31,6 +32,10 @@ import {
   type SenderIdentity,
 } from "../../shared/sender-identity.js";
 import { formatSessionContextText } from "../../shared/session-context.js";
+import {
+  visionDisclosureLines,
+  type NotViewableEntry,
+} from "../../shared/attachment-vision.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -55,6 +60,17 @@ export interface SkillMetadata {
   path: string;
 }
 
+/**
+ * Vision facts about this turn's attachments, rendered inside the
+ * input-files section: which images the model can see inline (in send
+ * order) and which degraded to the file-pointer story. Derived per turn
+ * from the resolved attachments — never carried across turns.
+ */
+export interface VisionPromptInfo {
+  inlineFilenames: string[];
+  notViewable: NotViewableEntry[];
+}
+
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
@@ -75,6 +91,8 @@ export interface EnhancedPromptOptions {
   workspaceDirs: string[];
   workspaceFileRefs: string[];
   attachmentPaths: string[];
+  /** Inline/degraded image facts for the input-files section (T04 vision). */
+  vision?: VisionPromptInfo;
   interactionMode?: InteractionMode;
   /**
    * The execution is a Build-from-plan turn (spec.execution_config
@@ -107,6 +125,16 @@ export interface EnhancedPromptOptions {
    * store — the context is constant for the session's lifetime.
    */
   sessionContext?: string;
+  /**
+   * Conversation catchup (cloud DD-006): what happened on the channel
+   * conversation that the agent has not seen, read from the execution
+   * spec's `conversation_catchup`. PER-TURN, unlike the three standing
+   * siblings above: it rides BOTH prompt paths — this enhanced prompt and
+   * a resumed turn's prefix (the `interaction_mode` shape) — because
+   * handback lands mid-session on a resumed agent, the exact case the
+   * metadata lane cannot reach.
+   */
+  conversationCatchup?: string;
 }
 
 /**
@@ -168,7 +196,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
   }
 
   if (options.attachmentPaths.length > 0) {
-    sections.push(formatInputFiles(options.attachmentPaths));
+    sections.push(formatInputFiles(options.attachmentPaths, options.vision));
   }
 
   if (options.workspaceFileRefs.length > 0) {
@@ -200,6 +228,14 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatContextBridgeSection(options.contextBridge));
   }
 
+  // Catchup after the bridge (DD-007 D-d: bridge first, catchup second) —
+  // the bridge carries the pre-takeover conversation, the catchup the human
+  // episode, strictly newer by construction; recency puts it closer to the
+  // task.
+  if (options.conversationCatchup) {
+    sections.push(formatConversationCatchupSection(options.conversationCatchup));
+  }
+
   // Always last before the task: the platform's tool-approval protocol. Placed
   // here for recency so it outweighs any "ask the user first" guidance Cursor
   // surfaces from a connected MCP server (see formatToolApprovalProtocol).
@@ -345,6 +381,10 @@ export function formatSessionContextSection(context: string): string {
   return `<session_context>\n${formatSessionContextText(context)}\n</session_context>`;
 }
 
+export function formatConversationCatchupSection(digest: string): string {
+  return `<conversation_catchup>\n${formatConversationCatchupText(digest)}\n</conversation_catchup>`;
+}
+
 export function formatSkillsSection(skills: SkillMetadata[]): string {
   const entries = skills.map(
     (s) => `- **${s.name}**: ${s.description}\n  Path: \`${s.path}\``,
@@ -439,12 +479,20 @@ export function formatWorkspaceContext(dirs: string[]): string {
   ].join("\n");
 }
 
-export function formatInputFiles(paths: string[]): string {
+export function formatInputFiles(paths: string[], vision?: VisionPromptInfo): string {
   const entries = paths.map((p) => `- \`${p}\``);
+  // 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
+  // believes it can see.
+  const disclosure = vision
+    ? visionDisclosureLines(vision.inlineFilenames, vision.notViewable)
+    : [];
   return [
     "<input_files>",
     "The following files have been provided as inputs. Read them when relevant to the task:",
     ...entries,
+    ...disclosure,
     "</input_files>",
   ].join("\n");
 }