@stigmer/runner 3.7.0 → 3.9.0

package/README.md

@@ -170,8 +170,8 @@ All configuration is environment-driven. Names and defaults below are verified a
 | Variable | Applies to | Required | Default | Purpose |
 |----------|-----------|----------|---------|---------|
 | `ARTIFACT_STORAGE_TYPE` | All | No | `proxy` if `STIGMER_PROXY_ENDPOINT` is set, else `local` | Selects the artifact backend: `local` (filesystem, served by the Stigmer backend) or `proxy` (presigned URLs via the proxy). An explicit value always wins. Storage follows transport, not execution location. |
-| `LOCAL_ARTIFACT_PATH` | Local storage | No | `/var/stigmer/artifacts` | Filesystem path for the local artifact backend. |
-| `LOCAL_ARTIFACT_SERVE_URL` | Local storage | No | `http://localhost:7235` | Base URL the local backend uses to construct artifact download URLs. |
+| `LOCAL_ARTIFACT_PATH` | Local storage | No | `~/.stigmer/data/artifacts` | Filesystem root of the local artifact store. **Must equal the stigmer-server's `ARTIFACT_LOCAL_BASE_PATH`** — in local mode the server writes an artifact to `<ARTIFACT_LOCAL_BASE_PATH>/<key>` and the runner reads it from `<LOCAL_ARTIFACT_PATH>/<key>`, so a mismatch makes every storage-key attachment and offload fail to resolve. The defaults align out of the box; the CLI local daemon sets both explicitly. |
+| `LOCAL_ARTIFACT_SERVE_URL` | Local storage | No | `http://localhost:7235` | Base URL of the server's artifact HTTP file server (its `ARTIFACT_HTTP_PORT`, default `GRPC_PORT + 1`). Used for blob downloads; the runner's own read-back goes straight to disk. |
 
 ### Claim-check (large Temporal payloads)
 

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"f59012b1fb99fae0","builtAt":"2026-08-07T07:55:08.387Z","fileCount":271}
+{"hash":"46c0fe996f031eda","builtAt":"2026-08-09T21:11:53.007Z","fileCount":275}

package/dist/activities/execute-cursor/attachment-resolver.d.ts

@@ -30,10 +30,20 @@
  */
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { type VisionBudget, type VisionDegradedReason, type VisionImage } from "../../shared/attachment-vision.js";
 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 {
     sessionId: string;
@@ -45,6 +55,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 declare class AttachmentResolutionError extends Error {
     readonly attachmentFilename: string;

package/dist/activities/execute-cursor/attachment-resolver.js

@@ -28,8 +28,9 @@
  * found" class of failure). Any attachment that cannot be materialized aborts
  * 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 { isVisionCandidate, } 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";
 const INPUTS_SUBDIR = "inputs";
@@ -70,9 +71,10 @@ export async function resolveAttachments(attachments, options) {
 async function resolveAttachment(attachment, inputsDir, options) {
     // 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;
         try {
-            await copyFile(attachment.localPath, join(inputsDir, filename));
+            vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
         }
         catch (err) {
             throw new AttachmentResolutionError(attachment.filename, `failed to copy local file '${attachment.localPath}': ` +
@@ -81,6 +83,7 @@ async function resolveAttachment(attachment, inputsDir, options) {
         return {
             filename,
             relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+            ...visionOutcomeFields(vision),
         };
     }
     // Universal path: download the uploaded content by storage key.
@@ -91,7 +94,7 @@ async function resolveAttachment(attachment, inputsDir, options) {
         throw new AttachmentResolutionError(attachment.filename, `artifact storage is unavailable, so this attachment ` +
             `(key: ${attachment.storageKey}) cannot be downloaded`);
     }
-    const filename = attachment.filename || basename(attachment.storageKey);
+    const filename = safeInputName(attachment.filename || attachment.storageKey);
     let content;
     try {
         content = await options.storage.download(attachment.storageKey);
@@ -101,9 +104,58 @@ async function resolveAttachment(attachment, inputsDir, options) {
             `${err instanceof Error ? err.message : String(err)}`);
     }
     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, filename, inputsDir, visionBudget) {
+    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) {
+    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) {
+    const name = basename(raw);
+    if (name === "" || name === "." || name === "..") {
+        throw new AttachmentResolutionError(raw, `'${raw}' does not yield a usable filename for materialization`);
+    }
+    return name;
+}
 //# sourceMappingURL=attachment-resolver.js.map

package/dist/activities/execute-cursor/attachment-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachment-resolver.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/attachment-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attachment-resolver.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/attachment-resolver.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/index.d.ts

@@ -53,6 +53,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).
@@ -85,6 +91,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;
 }
 /**
  * Select and build the appropriate prompt based on resolution reason and
@@ -102,4 +120,13 @@ 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 declare function isHitlReinvocation(approvalDecisions: Map<string, ApprovalAction> | undefined): approvalDecisions is Map<string, ApprovalAction>;
 export declare function buildPrompt(input: BuildPromptInput): string;

package/dist/activities/execute-cursor/index.js

@@ -40,12 +40,14 @@ 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, resolveCallerIdentity, } from "../../shared/caller-identity.js";
 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 } from "../../shared/artifact-storage.js";
+import { CURSOR_VISION_PROFILE, VisionBudget, toCursorImages, } from "../../shared/attachment-vision.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -55,6 +57,7 @@ import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mc
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
 import { synthesizeDatastoreAttachment } from "../../shared/datastore-attachment.js";
 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";
@@ -65,7 +68,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 { acquireWorkspaceLock, WorkspaceLockCancelledError, WorkspaceLockTimeoutError, } from "../../shared/workspace/workspace-lock.js";
@@ -578,6 +581,25 @@ turnSeq) {
                 };
             }
         }
+        // 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.
         //
@@ -610,14 +632,34 @@ turnSeq) {
         setupTiming.mark("resolve_skills");
         // 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 = 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
         // is what gets applied"). The Cursor deny-only harness reinvokes the model,
@@ -896,6 +938,7 @@ turnSeq) {
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachmentPaths,
+            vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             appliedToolCallIds,
             interactionMode,
@@ -903,6 +946,7 @@ turnSeq) {
             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
         let effectivePrompt = prompt;
@@ -910,6 +954,18 @@ turnSeq) {
             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 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) => 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);
@@ -1010,7 +1066,7 @@ turnSeq) {
         // 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;
@@ -1327,7 +1383,10 @@ turnSeq) {
             // 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);
@@ -1443,11 +1502,18 @@ turnSeq) {
                         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(`ExecuteCursor retry with fresh agent: execution=${executionId}, ` +
                         `newAgentId=${freshAgent.agentId}`);
@@ -1926,26 +1992,49 @@ import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
  * 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) {
+    return approvalDecisions !== undefined && approvalDecisions.size > 0;
+}
 export function buildPrompt(input) {
-    const { resolution, approvalDecisions, instructions, userMessage, skills, subAgents, workspaceDirs, workspaceFileRefs, attachmentPaths, interactionMode, buildFromPlan, } = input;
-    const isHitlReinvocation = approvalDecisions !== undefined && approvalDecisions.size > 0;
+    const { resolution, approvalDecisions, instructions, userMessage, skills, subAgents, workspaceDirs, workspaceFileRefs, attachmentPaths, interactionMode, buildFromPlan, 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).
-    if (isHitlReinvocation) {
+    if (isHitlReinvocation(approvalDecisions)) {
         return buildReinvocationPrompt(input.pendingApprovals, approvalDecisions, input.appliedToolCallIds);
     }
     // 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 !== undefined);
         return prefixes.length > 0
             ? [...prefixes, userMessage].join("\n\n")
@@ -1964,11 +2053,13 @@ export function buildPrompt(input) {
         workspaceDirs,
         workspaceFileRefs,
         attachmentPaths,
+        vision: input.vision,
         interactionMode,
         buildFromPlan,
         contextBridge: input.contextBridge,
         senderIdentity: input.senderIdentity,
         sessionContext: input.sessionContext,
+        conversationCatchup,
     });
 }
 // ---------------------------------------------------------------------------