@stigmer/runner 3.11.1-dev.20260812192248 → 3.12.1

package/src/activities/execute-deep-agent/attachment-injector.ts

@@ -5,13 +5,23 @@
  * validates ZIP archives with security guards, and writes files into the
  * workspace via the platform mount namespace (.stigmer/inputs/).
  *
- * Security model: attachments are untrusted user uploads. All ZIP content
- * is validated for path traversal, zip bombs, and format integrity before
- * any extraction occurs.
+ * Security model: attachments are untrusted user uploads. ZIP archives are
+ * parsed from the central directory — the format's authoritative index —
+ * via the shared structural layer (shared/zip-structure.ts; issue #567,
+ * which killed this module's local-header walk: it silently truncated
+ * stored streaming entries and rejected Go-default archives outright).
+ * Every entry is validated for path traversal, zip bombs, and format
+ * integrity BEFORE any extraction occurs, and because the central
+ * directory's sizes are declarations an attacker controls, decompression
+ * re-enforces them: an entry whose actual output disagrees with its
+ * declared size aborts the injection.
  *
  * Error model: fail-hard. Any attachment failure aborts the entire injection
  * and propagates a descriptive error. Attachments are explicit user inputs —
- * running with partial inputs produces silently incorrect results.
+ * running with partial inputs produces silently incorrect results. This is
+ * deliberately the OPPOSITE policy from the skill-artifact reader
+ * (shared/zip-extract.ts, non-fatal empty return): skill artifacts were
+ * structurally vouched for by the push gates, attachments never are.
  *
  * Duplicate names are NOT a failure (issue #364): a default-derived mount
  * path that collides is renamed with the platform's `stem-2.ext` semantics
@@ -27,19 +37,24 @@ import { posix } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { mintAttachmentDownloadUrl } from "../../shared/attachment-download-urls.js";
 import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import type {
   VisionBudget,
   VisionDegradedReason,
   VisionImage,
 } from "../../shared/attachment-vision.js";
+import {
+  EOCD_MIN_SIZE,
+  parseZipStructure,
+  type ZipStructuralEntry,
+} from "../../shared/zip-structure.js";
 
 // ── Constants ────────────────────────────────────────────────────────
 
 const MAX_ZIP_FILES = 1000;
 const MAX_ZIP_EXTRACTED_SIZE = 100 * 1024 * 1024; // 100 MB
 const DEFAULT_INPUTS_PREFIX = ".stigmer/inputs";
-const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 
 export { MAX_ZIP_FILES, MAX_ZIP_EXTRACTED_SIZE };
 
@@ -66,6 +81,17 @@ export interface InjectedFile {
    * Attachments that were never image-shaped carry neither field.
    */
   readonly visionDegraded?: VisionDegradedReason;
+  /**
+   * A download URL for the attachment's stored object, listed in the system
+   * prompt's Input Files section so the agent can hand the file to a tool
+   * whose backend cannot read the sandbox filesystem (issue #532). Minted
+   * whenever the attachment has a `storageKey` and a usable storage; never
+   * present on extracted ZIP entries (no attachment-level object). Absent
+   * when there is nothing to mint or the mint failed (non-fatal — policy,
+   * degrade log, and prompt wording live in
+   * shared/attachment-download-urls.ts).
+   */
+  readonly downloadUrl?: string;
 }
 
 export interface InjectAttachmentsOptions {
@@ -120,126 +146,117 @@ export class AttachmentValidationError extends Error {
   }
 }
 
-// ── ZIP Validation (pure function) ───────────────────────────────────
+// ── ZIP Validation (pure functions) ──────────────────────────────────
 
 /**
  * Validate a ZIP archive for safe extraction. Returns the manifest of
  * file entries (directories excluded) if the archive passes all checks.
  *
  * Security checks enforced:
- * 1. Valid ZIP format (local file header signature present)
+ * 1. Valid ZIP format (readable central directory; fail-hard, see module doc)
  * 2. No absolute paths (entries starting with / or \)
  * 3. No path traversal (.. components)
  * 4. No null bytes in filenames
- * 5. Non-empty archive (at least one file entry)
- * 6. File count within limits (max 1000)
- * 7. Total uncompressed size within limits (max 100 MB)
+ * 5. No duplicate entry paths (a contradictory manifest)
+ * 6. Only supported compression methods (stored, deflate) — checked here
+ *    so an unsupported entry can never abort extraction after earlier
+ *    entries were already written
+ * 7. Non-empty archive (at least one file entry)
+ * 8. File count within limits (max 1000)
+ * 9. Total declared uncompressed size within limits (max 100 MB) —
+ *    declarations are re-enforced against actual output at decompression
  */
 export function validateZipForExtraction(
   zipData: Buffer,
   sourceFilename: string,
 ): ZipEntryInfo[] {
-  if (zipData.length < 4) {
+  return parseAndValidateZip(zipData, sourceFilename).map(
+    ({ relativePath, uncompressedSize }) => ({ relativePath, uncompressedSize }),
+  );
+}
+
+/**
+ * A validated file entry, still carrying its payload slice. Validation and
+ * extraction share these records — parsing happens exactly once, so "the
+ * manifest promised a file extraction cannot find" is unrepresentable
+ * (the old two-walker design silently skipped such entries).
+ */
+interface ValidatedZipEntry extends ZipEntryInfo {
+  readonly compressionMethod: number;
+  readonly compressedData: Uint8Array;
+}
+
+function parseAndValidateZip(
+  zipData: Buffer,
+  sourceFilename: string,
+): ValidatedZipEntry[] {
+  if (zipData.length < EOCD_MIN_SIZE) {
     throw new AttachmentValidationError(
       sourceFilename,
       "not a valid ZIP archive (file too small)",
     );
   }
 
-  const view = new DataView(zipData.buffer, zipData.byteOffset, zipData.byteLength);
-  const firstSignature = view.getUint32(0, true);
-
-  if (firstSignature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) {
+  let structural: ZipStructuralEntry[];
+  try {
+    structural = parseZipStructure(zipData);
+  } catch (err) {
     throw new AttachmentValidationError(
       sourceFilename,
-      "not a valid ZIP archive (invalid header signature)",
+      `not a valid ZIP archive (${err instanceof Error ? err.message : String(err)})`,
     );
   }
 
-  const entries: ZipEntryInfo[] = [];
+  const entries: ValidatedZipEntry[] = [];
+  const seenPaths = new Set<string>();
   let totalUncompressed = 0;
-  let offset = 0;
-
-  while (offset < zipData.length - 4) {
-    const signature = view.getUint32(offset, true);
-    if (signature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) break;
 
-    if (offset + 30 > zipData.length) {
+  for (const entry of structural) {
+    if (entry.name.includes("\u0000")) {
       throw new AttachmentValidationError(
         sourceFilename,
-        "not a valid ZIP archive (truncated local file header)",
+        "contains a filename with null bytes and cannot be safely extracted",
       );
     }
 
-    const compressionMethod = view.getUint16(offset + 8, true);
-    const compressedSize = view.getUint32(offset + 18, true);
-    const uncompressedSize = view.getUint32(offset + 22, true);
-    const fileNameLength = view.getUint16(offset + 26, true);
-    const extraFieldLength = view.getUint16(offset + 28, true);
+    if (entry.isDirectory) continue;
 
-    const fileNameStart = offset + 30;
-    const fileNameEnd = fileNameStart + fileNameLength;
-
-    if (fileNameEnd > zipData.length) {
+    if (entry.name.startsWith("/") || entry.name.startsWith("\\")) {
       throw new AttachmentValidationError(
         sourceFilename,
-        "not a valid ZIP archive (truncated filename)",
+        `contains an absolute path entry and cannot be safely extracted: ${entry.name}`,
       );
     }
 
-    const fileNameBytes = zipData.subarray(fileNameStart, fileNameEnd);
-
-    for (let i = 0; i < fileNameBytes.length; i++) {
-      if (fileNameBytes[i] === 0x00) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          "contains a filename with null bytes and cannot be safely extracted",
-        );
-      }
+    if (hasPathTraversal(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains a path traversal entry and cannot be safely extracted: ${entry.name}`,
+      );
     }
 
-    const fileName = new TextDecoder().decode(fileNameBytes);
-
-    const isDirectory = fileName.endsWith("/");
-
-    if (!isDirectory) {
-      if (fileName.startsWith("/") || fileName.startsWith("\\")) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          `contains an absolute path entry and cannot be safely extracted: ${fileName}`,
-        );
-      }
-
-      if (hasPathTraversal(fileName)) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          `contains a path traversal entry and cannot be safely extracted: ${fileName}`,
-        );
-      }
-
-      entries.push({ relativePath: fileName, uncompressedSize });
-      totalUncompressed += uncompressedSize;
+    if (seenPaths.has(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains duplicate entry '${entry.name}' and cannot be safely extracted`,
+      );
     }
+    seenPaths.add(entry.name);
 
-    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
-
-    // Handle data descriptor (bit 3 of general purpose flag)
-    const generalFlags = view.getUint16(offset + 6, true);
-    let dataSize = compressedSize;
-
-    if ((generalFlags & 0x08) !== 0 && compressedSize === 0) {
-      // Data descriptor follows compressed data — scan for next header
-      // This is a simplified approach; for untrusted inputs we require
-      // sizes in the local header. Reject archives that use streaming.
-      if (!isDirectory && compressionMethod !== 0) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          "uses streaming (data descriptors without sizes) which is not supported for security validation",
-        );
-      }
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.name}' uses unsupported compression method ${entry.compressionMethod}`,
+      );
     }
 
-    offset = dataStart + dataSize;
+    entries.push({
+      relativePath: entry.name,
+      uncompressedSize: entry.uncompressedSize,
+      compressionMethod: entry.compressionMethod,
+      compressedData: entry.compressedData,
+    });
+    totalUncompressed += entry.uncompressedSize;
   }
 
   if (entries.length === 0) {
@@ -294,13 +311,16 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
     const { path: mountPath, renamedFrom } = mountPaths.get(attachment)!;
 
     if (attachment.extract) {
-      const entries = validateZipForExtraction(content, attachment.filename);
+      const entries = parseAndValidateZip(content, attachment.filename);
       const extracted = await extractZipToWorkspace(
-        content, entries, mountPath, backend,
+        entries, mountPath, backend, attachment.filename,
       );
       // A renamed mount DIR is visible through every extracted path; the
       // entries themselves were not renamed, so they carry no renamedFrom
-      // (per-file disclosure would misattribute the rename).
+      // (per-file disclosure would misattribute the rename). Extracted
+      // entries also carry no downloadUrl: the stored object is the ZIP, not
+      // any listed file, and a URL to bytes that differ from the listing
+      // would be a false promise.
       injectedFiles.push(...extracted);
     } else {
       await backend.writeFileBuffer(mountPath, content);
@@ -313,6 +333,9 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
       // the vision budget before they go out of scope (the sniff decides
       // eligibility; the budget owns every size/count rule).
       const vision = visionBudget?.offer(filename, attachment.contentType, content);
+      const downloadUrl = await mintAttachmentDownloadUrl(
+        storage, attachment.storageKey, filename,
+      );
       injectedFiles.push({
         filename,
         path: mountPath,
@@ -320,6 +343,7 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
         ...(renamedFrom !== undefined ? { renamedFrom } : {}),
         ...(vision?.kind === "accepted" ? { vision: vision.image } : {}),
         ...(vision?.kind === "degraded" ? { visionDegraded: vision.reason } : {}),
+        ...(downloadUrl !== undefined ? { downloadUrl } : {}),
       });
     }
   }
@@ -505,20 +529,16 @@ async function downloadAttachment(
 }
 
 async function extractZipToWorkspace(
-  zipData: Buffer,
-  entries: readonly ZipEntryInfo[],
+  entries: readonly ValidatedZipEntry[],
   mountDir: string,
   backend: WorkspaceBackend,
+  sourceFilename: string,
 ): Promise<InjectedFile[]> {
   const cleanMountDir = mountDir.replace(/\/+$/, "");
   const injected: InjectedFile[] = [];
-  const parsedEntries = parseZipFileData(zipData);
 
   for (const entry of entries) {
-    const fileData = parsedEntries.get(entry.relativePath);
-    if (!fileData) continue;
-
-    const content = await decompressEntry(fileData);
+    const content = await decompressEntry(entry, sourceFilename);
     const targetPath = `${cleanMountDir}/${entry.relativePath}`;
 
     await backend.writeFileBuffer(targetPath, content);
@@ -532,63 +552,66 @@ async function extractZipToWorkspace(
   return injected;
 }
 
-interface RawZipEntry {
-  compressedData: Buffer;
-  compressionMethod: number;
-}
-
-function parseZipFileData(zipData: Buffer): Map<string, RawZipEntry> {
-  const result = new Map<string, RawZipEntry>();
-  const view = new DataView(zipData.buffer, zipData.byteOffset, zipData.byteLength);
-  let offset = 0;
-
-  while (offset < zipData.length - 4) {
-    const signature = view.getUint32(offset, true);
-    if (signature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) break;
-
-    const compressionMethod = view.getUint16(offset + 8, true);
-    const compressedSize = view.getUint32(offset + 18, true);
-    const fileNameLength = view.getUint16(offset + 26, true);
-    const extraFieldLength = view.getUint16(offset + 28, true);
-
-    const fileNameStart = offset + 30;
-    const fileName = new TextDecoder().decode(
-      zipData.subarray(fileNameStart, fileNameStart + fileNameLength),
-    );
-
-    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
-    const compressedData = zipData.subarray(dataStart, dataStart + compressedSize);
-
-    if (!fileName.endsWith("/")) {
-      result.set(fileName, {
-        compressedData: Buffer.from(compressedData),
-        compressionMethod,
-      });
-    }
-
-    offset = dataStart + compressedSize;
-  }
-
-  return result;
-}
+/**
+ * Decompress a validated entry, enforcing its declared uncompressed size.
+ *
+ * The size cap in parseAndValidateZip budgets *declared* sizes, which the
+ * archive author controls — a crafted archive can declare 1 KB and inflate
+ * to gigabytes. Enforcement is therefore two-sided and fail-hard: inflation
+ * aborts the moment output exceeds the declaration, and an undershoot (or a
+ * stored payload whose length disagrees) fails too, because a manifest that
+ * misdescribes its own contents is exactly the corrupt-input class this
+ * module must never extract from.
+ */
+async function decompressEntry(
+  entry: ValidatedZipEntry,
+  sourceFilename: string,
+): Promise<Buffer> {
+  const declared = entry.uncompressedSize;
 
-async function decompressEntry(entry: RawZipEntry): Promise<Buffer> {
   if (entry.compressionMethod === 0) {
-    return entry.compressedData;
+    if (entry.compressedData.length !== declared) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.relativePath}' payload is ${entry.compressedData.length} bytes ` +
+        `but the archive declares ${declared} — corrupt or crafted archive`,
+      );
+    }
+    return Buffer.from(entry.compressedData);
   }
 
-  if (entry.compressionMethod === 8) {
-    return new Promise<Buffer>((resolve, reject) => {
-      const inflate = createInflateRaw();
-      const chunks: Buffer[] = [];
-      inflate.on("data", (chunk: Buffer) => chunks.push(chunk));
-      inflate.on("end", () => resolve(Buffer.concat(chunks)));
-      inflate.on("error", reject);
-      inflate.end(entry.compressedData);
+  // Deflate — the only other method parseAndValidateZip admits.
+  return new Promise<Buffer>((resolve, reject) => {
+    const inflate = createInflateRaw();
+    const chunks: Buffer[] = [];
+    let produced = 0;
+    inflate.on("data", (chunk: Buffer) => {
+      produced += chunk.length;
+      if (produced > declared) {
+        inflate.destroy();
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompresses past its declared size of ` +
+          `${declared} bytes — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      chunks.push(chunk);
     });
-  }
-
-  throw new Error(`Unsupported ZIP compression method: ${entry.compressionMethod}`);
+    inflate.on("end", () => {
+      if (produced !== declared) {
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompressed to ${produced} bytes ` +
+          `but the archive declares ${declared} — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      resolve(Buffer.concat(chunks));
+    });
+    inflate.on("error", reject);
+    inflate.end(Buffer.from(entry.compressedData));
+  });
 }
 
 function hasPathTraversal(filePath: string): boolean {

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

@@ -32,7 +32,6 @@ import {
 } from "../../shared/workspace/stigmer-link.js";
 import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
-import { formatDatastoreDegradationNotice } from "../../shared/datastore-attachment.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import {
   POLICY_ENGINE_VERSION,
@@ -153,24 +152,6 @@ export function createDeepAgentActivities(config: Config) {
           ? seedStatusFromExecution(setup.execution)
           : create(AgentExecutionStatusSchema, {});
 
-        // Datastore degradation disclosure, operator half (issue #325): the
-        // prompt already tells the agent to disclose the outage; this makes
-        // it visible on the execution record without reading a transcript.
-        // Appended to initialStatus BEFORE streaming (not via a status
-        // builder): both the v2 and v3 stream paths construct their own
-        // builder around this same proto and only ever append messages, so
-        // this row survives whichever path runs and rides every persist.
-        if (setup.datastoreToolsMissing.length > 0) {
-          initialStatus.messages.push(create(AgentMessageSchema, {
-            type: MessageType.MESSAGE_SYSTEM,
-            content: formatDatastoreDegradationNotice(
-              setup.agent.spec?.datastoreUsages?.length ?? 0,
-              setup.datastoreToolsMissing,
-            ),
-            timestamp: utcTimestamp(),
-          }));
-        }
-
         const statusBuilder = new StatusBuilder(executionId, initialStatus);
 
         statusBuilder.setApprovalProvider({

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

@@ -17,8 +17,6 @@
 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
@@ -30,7 +28,6 @@ export interface McpToolSources {
 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

@@ -21,6 +21,10 @@ import {
   visionDisclosureLines,
   type NotViewableEntry,
 } from "../../shared/attachment-vision.js";
+import {
+  downloadUrlDisclosureLine,
+  type DownloadUrlKind,
+} from "../../shared/attachment-download-urls.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -99,14 +103,6 @@ export interface PromptBuilderInput {
   provisionResults: ProvisionResult[];
   containerRoot: string;
   skillsPromptSection: string;
-  /**
-   * The datastores section (shared/datastore-attachment.ts
-   * formatDatastoresSection): `<available_datastores>` when the connected
-   * record-tool roster is complete, `<unavailable_datastores>` when setup's
-   * reconciliation found record tools missing (issue #325). Empty when the
-   * agent uses no datastores.
-   */
-  datastoresPromptSection?: string;
   /**
    * The `<available_channel_templates>` section
    * (shared/channel-attachment.ts formatChannelTemplatesSection); absent
@@ -122,6 +118,12 @@ export interface PromptBuilderInput {
    * Rendered inside the Input Files section.
    */
   vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — 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;
   /**
    * The execution's interaction mode. PLAN appends the shared plan-mode
    * directive so the model knows the turn's deliverable is a plan document.
@@ -201,10 +203,6 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += input.skillsPromptSection;
   }
 
-  if (input.datastoresPromptSection) {
-    prompt += "\n\n" + input.datastoresPromptSection;
-  }
-
   if (input.channelTemplatesPromptSection) {
     prompt += "\n\n" + input.channelTemplatesPromptSection;
   }
@@ -220,7 +218,9 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   }
 
   if (input.injectedFiles.length > 0) {
-    prompt += buildInjectedFilesSection(input.injectedFiles, input.vision);
+    prompt += buildInjectedFilesSection(
+      input.injectedFiles, input.vision, input.downloadUrlKind,
+    );
   }
 
   if (input.senderIdentity) {
@@ -251,7 +251,17 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   // reads. (PLAN and build_from_plan are mutually exclusive in practice —
   // the build turn is always an Agent-mode execution.)
   if (input.interactionMode === InteractionMode.PLAN) {
-    prompt += "\n\n## Plan mode\n\n" + PLAN_MODE_DIRECTIVE;
+    // The read-boundary sentence is native-harness-only, appended OUTSIDE the
+    // shared directive: PLAN_MODE_DIRECTIVE also serves the Cursor harness,
+    // which has no tool-level read boundary — there the sentence would be
+    // false. Here it is enforced fact (shared/plan-mode-permissions.ts,
+    // issue #528), stated so the model doesn't burn rounds probing paths the
+    // rules will refuse.
+    prompt +=
+      "\n\n## Plan mode\n\n" +
+      PLAN_MODE_DIRECTIVE +
+      "\n- File reads are limited to your workspace (including its " +
+      "`.stigmer/` directory); paths outside it are refused.";
   }
 
   if (input.buildFromPlan) {
@@ -401,6 +411,7 @@ function buildReferencedFilesSection(
 function buildInjectedFilesSection(
   files: readonly InjectedFile[],
   vision?: VisionPromptInfo,
+  downloadUrlKind?: DownloadUrlKind,
 ): string {
   let section = "\n\n## Input Files\n\n";
   section +=
@@ -416,12 +427,23 @@ function buildInjectedFilesSection(
     const sizeInfo = ` (${f.sizeBytes} bytes)`;
     // 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.
+    // 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 renameInfo =
       f.renamedFrom !== undefined
         ? ` (renamed from duplicate '${f.renamedFrom}')`
         : "";
-    section += `- \`${f.path}\`${sizeInfo}${renameInfo}\n`;
+    const urlInfo =
+      f.downloadUrl !== undefined ? ` — download URL: ${f.downloadUrl}` : "";
+    section += `- \`${f.path}\`${sizeInfo}${renameInfo}${urlInfo}\n`;
+  }
+
+  // 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.
+  if (downloadUrlKind !== undefined && files.some((f) => f.downloadUrl !== undefined)) {
+    section += "\n" + downloadUrlDisclosureLine(downloadUrlKind) + "\n";
   }
 
   // The vision lines (shared wording, attachment-vision.ts) tell the model