relay-companion 0.1.151 → 0.1.153

package/overlay/inbox.html

@@ -249,6 +249,16 @@
   .scroll::-webkit-scrollbar { width:10px; }
   .scroll::-webkit-scrollbar-thumb { background:var(--edge); border-radius:var(--r-pill); border:3px solid var(--bg); background-clip:padding-box; }
   .scroll::-webkit-scrollbar-thumb:hover { background:var(--edge); background-clip:padding-box; }
+  /* The list must NEVER scroll sideways. overflow-y:auto computes overflow-x
+     to auto, so any row whose min-content crosses the width (the custom
+     scrollbar already eats 10px of it) sprouted a horizontal scrollbar — and
+     with both bars present, the UNSTYLED scrollbar corner painted as a white
+     square over the card's bottom-right (field report, 2026-08-12). Rows
+     already ellipsize/wrap internally; sideways overflow is always a bug, so
+     clip it categorically and keep the corner transparent as belt-and-braces. */
+  .scroll { overflow-x:hidden; }
+  .scroll::-webkit-scrollbar:horizontal { height:0; }
+  .scroll::-webkit-scrollbar-corner { background:transparent; }
   .view.hidden { display:none; }
 
   /* ---- group headers (Tasks) ---- */
@@ -546,6 +556,10 @@
 
   /* attachment chips (markup emitted by attachmentChips helper) */
   .td-att { display:flex; align-items:center; gap:7px; margin-top:8px; padding:6px 9px; border:1px solid var(--hair); border-radius:var(--r-2); min-width:0; background:color-mix(in srgb, var(--bg) 60%, transparent); }
+  /* clickable variant: same chip, rendered as a real button that opens the file */
+  button.td-att { width:100%; font:inherit; color:inherit; text-align:left; cursor:pointer; }
+  button.td-att:hover { border-color:var(--muted-2); background:color-mix(in srgb, var(--bg) 85%, transparent); }
+  button.td-att:disabled { opacity:.55; cursor:default; }
   .td-att svg { flex:none; opacity:.75; }
   .td-att-name { font-size:12px; font-weight:600; color:var(--ink); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; min-width:0; }
   .td-att-meta { margin-left:auto; flex:none; font-family:var(--mono); font-size:10px; color:var(--muted-2); }
@@ -1709,18 +1723,56 @@
     if (n >= 1024) return `${Math.round(n / 1024)} KB`;
     return n > 0 ? `${n} B` : "";
   }
-  function attachmentChips(attachments) {
+  // Handles both attachment shapes: task-message files ({filename, sizeBytes})
+  // and relay attachments ({name, bytes}). With a relayId the chip becomes a
+  // button that opens the file via main (local copy, or download-then-open);
+  // without one it stays the plain readout.
+  function attachmentChips(attachments, { relayId = "" } = {}) {
     const list = Array.isArray(attachments) ? attachments : [];
     return list.map((a) => {
-      const size = fmtBytes(a.sizeBytes);
+      const name = a.filename || a.name || "file";
+      const size = fmtBytes(a.sizeBytes != null ? a.sizeBytes : a.bytes);
+      const inner = `
+          ${fileIconSvg(fileFamilyOf(name, a.contentType))}
+          <span class="td-att-name">${esc(name)}</span>
+          ${size ? `<span class="td-att-meta">${esc(size)}</span>` : ""}`;
+      if (relayId && a.id) {
+        return `
+        <button class="td-att td-att-open" type="button" data-att-relay="${esc(relayId)}" data-att-id="${esc(a.id)}" data-stop="1" title="Open ${esc(name)}" aria-label="Open attachment ${esc(name)}">${inner}</button>`;
+      }
       return `
-        <div class="td-att">
-          ${fileIconSvg(fileFamilyOf(a.filename, a.contentType))}
-          <span class="td-att-name">${esc(a.filename || "file")}</span>
-          ${size ? `<span class="td-att-meta">${esc(size)}</span>` : ""}
-        </div>`;
+        <div class="td-att">${inner}</div>`;
     }).join("");
   }
+
+  // One delegated wiring pass per rebuilt container: chip click -> main opens
+  // the file. Never toggles the row (data-stop) and reports failures into the
+  // same .row-err slot every other row action uses.
+  function wireAttachmentChips(root) {
+    for (const chip of root.querySelectorAll("[data-att-relay]")) {
+      chip.addEventListener("click", async (event) => {
+        event.stopPropagation();
+        if (chip.disabled) return;
+        chip.disabled = true;
+        const relayId = chip.getAttribute("data-att-relay");
+        showRowError(relayId, "");
+        try {
+          const res = await window.relay.openAttachment(relayId, chip.getAttribute("data-att-id"));
+          if (!res || res.ok === false) showRowError(relayId, (res && res.error) || "Could not open this attachment.");
+        } catch {
+          showRowError(relayId, "Could not open this attachment.");
+        } finally {
+          chip.disabled = false;
+        }
+      });
+    }
+  }
+
+  // Attachments for one relay row, straight from the current payload.
+  function relayAttachmentsForId(id) {
+    const row = (payload.relays || []).find((r) => r.id === id);
+    return row && Array.isArray(row.attachments) ? row.attachments : [];
+  }
   // Tasks/share approvals are hidden from the pill until that product surface is ready.
   const RELAY_HIDDEN_KINDS = new Set(["task_request", "share_approval"]);
   function isRelayListKind(row) { return !RELAY_HIDDEN_KINDS.has(row && row.relayNotificationKind); }
@@ -2116,6 +2168,7 @@
         </div>
         <div class="rk-subject${kind === "human_question" ? " q" : ""}">${esc(subject)}</div>
         ${previewHtml}
+        ${expanded ? attachmentChips(r.attachments, { relayId: r.id }) : ""}
         ${actions}
         ${openCard}
         <div class="row-err${rowNotes.get(r.id)?.cls === "ok" ? " ok" : ""}" data-err="${esc(r.id)}">${esc(rowNotes.get(r.id)?.text || "")}</div>
@@ -2233,6 +2286,7 @@
     for (const z of relaysListEl.querySelectorAll('[data-stop="1"]')) {
       z.addEventListener("click", (e) => e.stopPropagation());
     }
+    wireAttachmentChips(relaysListEl);
     for (const ta of relaysListEl.querySelectorAll(".qr-input")) {
       // Keep the window focusable the whole time the reply field is focused so no keystroke is
       // ever dropped; only release focusability on blur.
@@ -3524,6 +3578,7 @@
           <span class="th-time">${esc(timeAgo(m.at))}</span>
         </span>
         <span class="th-msg-title">${esc(m.title)}</span>
+        ${expanded ? attachmentChips(relayAttachmentsForId(m.id), { relayId: m.id }) : ""}
         ${menu}
         <div class="row-err${rowNotes.get(m.id)?.cls === "ok" ? " ok" : ""}" data-err="${esc(m.id)}" data-stop="1">${esc(rowNotes.get(m.id)?.text || "")}</div>
       </div>`;
@@ -3551,6 +3606,7 @@
     for (const z of thHistoryEl.querySelectorAll('[data-stop="1"]')) {
       z.addEventListener("click", (e) => e.stopPropagation());
     }
+    wireAttachmentChips(thHistoryEl);
     for (const el of thHistoryEl.querySelectorAll(".th-msg")) {
       const id = el.getAttribute("data-msg");
       if (openingIds.has(id)) el.classList.add("opening");

package/overlay/main.cjs

@@ -789,6 +789,20 @@ function readRelays() {
       expectedVersion: p.expectedVersion || null,
       humanAnswered: Boolean(p.humanAnswered),
       humanAnswerMarkdown: p.humanAnswerMarkdown || null,
+      // Metadata only, never content: no localPath, no signed URL (the rule at
+      // previewPayloadForPacket applies here too). The chip click goes back
+      // through main, which resolves the local copy itself.
+      attachments: Array.isArray(p.attachments)
+        ? p.attachments
+            .filter((a) => a && typeof a === "object")
+            .map((a) => ({
+              id: a.id || "",
+              name: a.name || a.filename || "file",
+              bytes: Number(a.bytes || a.sizeBytes) || 0,
+              contentType: a.contentType || "",
+              hasLocalCopy: Boolean(a.localPath),
+            }))
+        : [],
     }))
     .sort((a, b) => {
       if (a.unread !== b.unread) return a.unread ? -1 : 1; // unread always on top
@@ -2612,6 +2626,72 @@ function openUrlTarget(url) {
   shell.openExternal(target).catch((error) => console.error("[overlay] open failed:", error && error.message));
 }
 
+/**
+ * Open one relay attachment from the pill chip. The renderer only ever holds
+ * attachment metadata (id/name/bytes), so the click comes back here and main
+ * resolves the actual target: the ingest-prefetched local copy when it exists
+ * (containment-checked against the attachments store), else a download NOW —
+ * with a URL refresh, since any staged signed URL is long expired — then the
+ * same local open. `shell.openPath` is the file:// path: self-contained HTML
+ * opens perfectly from disk, where the web origin can never render it.
+ */
+async function openRelayAttachment(relayId, attachmentId) {
+  const id = String(relayId || "").trim();
+  const attId = String(attachmentId || "").trim();
+  if (!id || !attId) return { ok: false, error: "missing id" };
+  const store = readStore();
+  const row = (store.packets || {})[id];
+  if (!row) return { ok: false, error: "relay not found" };
+  const attachments = Array.isArray(row.attachments) ? row.attachments : [];
+  const attachment = attachments.find((a) => a && a.id === attId);
+  if (!attachment) return { ok: false, error: "attachment not found" };
+
+  const attachmentsRoot = path.join(RELAY_HOME, "attachments");
+  const containedLocalPath = (candidate) => {
+    const clean = String(candidate || "").trim();
+    if (!clean) return "";
+    const resolved = path.resolve(clean);
+    // Never openPath something outside the store: `localPath` lives in a state
+    // file other processes write, so treat it as data, not as authority.
+    if (!resolved.startsWith(attachmentsRoot + path.sep)) return "";
+    return fs.existsSync(resolved) ? resolved : "";
+  };
+
+  let target = containedLocalPath(attachment.localPath);
+  if (!target) {
+    try {
+      const { materializeAttachmentFiles } = await import(
+        pathToFileURL(path.join(__dirname, "..", "src", "materializer.js")).href
+      );
+      const materialized = await materializeAttachmentFiles(
+        { id, attachments, attachmentUrls: row.attachmentUrls || {} },
+        { log: (m) => console.error(`[overlay] ${m}`) },
+      );
+      const fresh = (materialized.attachments || []).find((a) => a && a.id === attId);
+      target = containedLocalPath(fresh && fresh.localPath);
+      if (target) {
+        withJsonLock(STATE_PATH, () => {
+          const state = readStore();
+          if (state.packets && state.packets[id]) {
+            state.packets[id].attachments = materialized.attachments;
+            writeStateAtomic(state);
+          }
+        });
+      }
+    } catch (error) {
+      console.error("[overlay] attachment download failed:", error && error.message);
+    }
+  }
+  if (!target) return { ok: false, error: "attachment unavailable — download failed" };
+  if (process.env.RELAY_OVERLAY_TEST_NO_HOST_OPEN === "1") {
+    console.error("[overlay] test seam: suppressed attachment open:", target);
+    return { ok: true, path: target, suppressed: true };
+  }
+  const openError = await shell.openPath(target);
+  if (openError) return { ok: false, error: openError };
+  return { ok: true, path: target };
+}
+
 // ---- window placement / visibility ---------------------------------------
 
 function anchorTopRight() {
@@ -3925,6 +4005,7 @@ ipcMain.handle("relay:preview:steer", (event, input) => {
 });
 ipcMain.on("relay:openTask", (_e, taskId) => openTaskDetail(taskId));
 ipcMain.on("relay:openUrl", (_e, url) => openUrlTarget(url));
+ipcMain.handle("relay:openAttachment", (_e, relayId, attachmentId) => openRelayAttachment(relayId, attachmentId));
 ipcMain.on("relay:ack", (_e, id) => ackPacket(id));
 ipcMain.handle("relay:delete", (_e, id) => deletePacket(id));
 ipcMain.handle("relay:markAllRead", () => markAllVisibleRelaysRead());

package/overlay/preload.cjs

@@ -40,6 +40,9 @@ contextBridge.exposeInMainWorld("relay", {
   deleteRelay: (id) => ipcRenderer.invoke("relay:delete", id),
   markAllRead: () => ipcRenderer.invoke("relay:markAllRead"),
   openUrl: (url) => ipcRenderer.send("relay:openUrl", url),
+  // Attachment chip click: main resolves the local copy (or downloads it) and
+  // opens it; the renderer never sees paths or URLs. Returns { ok, error? }.
+  openAttachment: (relayId, attachmentId) => ipcRenderer.invoke("relay:openAttachment", relayId, attachmentId),
   refreshSent: () => ipcRenderer.invoke("relay:refreshSent"),
 
   // task mutations (return { ok, error?, conflict? })

package/overlay/preview.html

@@ -640,8 +640,14 @@
       <p class="reply-note" id="replyNote">Press Enter to send, Shift + Enter for a new line.</p>
       <!-- The task composer's caption: the runtime as words, tap to change.
            Shown only on an unstarted task face; replyNote keeps carrying
-           errors and hints for every face. -->
-      <p class="reply-note runtime-note gone" id="taskRuntimeNote">
+           errors and hints for every face.
+
+           A DIV, never a <p>: this caption contains the runtime popover, and
+           an HTML parser auto-closes a <p> at the first block child — which
+           ejected the popover and every node after it OUT of the element
+           carrying `gone`, so the trailing sentence rendered in every preview
+           and the popover lost its positioning anchor. -->
+      <div class="reply-note runtime-note gone" id="taskRuntimeNote">
         <span>Runs on</span>
         <span class="rt-anchor">
           <button class="runtime-btn" id="runtimeBtn" type="button" aria-haspopup="menu" aria-expanded="false">
@@ -665,7 +671,7 @@
           </div>
         </span>
         <span>— on your machine. The sender sees when it starts and what you send back.</span>
-      </p>
+      </div>
     </footer>
   </section>
   <script src="./preview-renderer.js"></script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.151",
+  "version": "0.1.153",
   "description": "Companion CLI for Relay (sendrelays.com): pairs this machine with your Relay account so coding agents like Claude Code and Codex can send and receive Relay messages.",
   "homepage": "https://sendrelays.com",
   "repository": {

package/src/links.js

@@ -0,0 +1,83 @@
+// Send-time scan for links that will not survive the trip to the recipient.
+//
+// Two families, one symptom (the recipient clicks and gets a login wall, a 404,
+// or an expired signature — and tells the sender Relay is broken):
+//
+//   1. Provider-scoped links: claude.ai artifacts/chats, ChatGPT canvases,
+//      private Notion pages. Scoped to the SENDER's account; the recipient's
+//      browser has no session that can see them.
+//   2. Relay's own signed /storage URLs: valid for anyone, but only for ~15
+//      minutes — long dead by the time a person reads the message.
+//
+// Advisory by design, sibling to attachments.js's refuse-and-warn model but
+// softer: the send is never blocked (agents attach public links in legitimate
+// shapes we cannot enumerate), the warning rides back on the send result's
+// agentInstruction so the agent can repair the message it just sent — attach
+// the file, or paste the content — while the moment is still live.
+
+const FRAGILE_LINK_RULES = [
+  {
+    kind: "claude",
+    // claude.ai/public/* artifacts are the one shareable shape; everything
+    // else under claude.ai is account-scoped.
+    test: (url) => /^https?:\/\/(?:www\.)?claude\.ai\//i.test(url) && !/claude\.ai\/public\//i.test(url),
+    describe: (url) => `${url} is a Claude link scoped to YOUR account — the recipient will hit a login wall or a 404.`,
+  },
+  {
+    kind: "chatgpt",
+    // chatgpt.com/share/* links are published; canvases and chats are not.
+    test: (url) =>
+      /^https?:\/\/(?:www\.)?(?:chatgpt\.com|chat\.openai\.com)\//i.test(url) &&
+      !/(?:chatgpt\.com|chat\.openai\.com)\/share\//i.test(url),
+    describe: (url) => `${url} is a ChatGPT link scoped to YOUR account — the recipient will hit a login wall.`,
+  },
+  {
+    kind: "notion",
+    // notion.site is Notion's publish-to-web domain and is genuinely public;
+    // notion.so pages are workspace-scoped unless shared, which we can't see.
+    test: (url) => /^https?:\/\/(?:www\.)?notion\.so\//i.test(url),
+    describe: (url) => `${url} is a Notion workspace link — it only opens for the recipient if that page is explicitly shared with them.`,
+  },
+  {
+    kind: "signed-storage",
+    test: (url) => /\/storage\/[^\s]*[?&](?:sig|expires)=/i.test(url),
+    describe: (url) => `${url} is a signed Relay storage URL that expires in minutes — it will be dead when the recipient reads this.`,
+  },
+];
+
+const URL_RE = /https?:\/\/[^\s<>"')\]]+/gi;
+
+/** Every fragile link in a markdown body, with why it is fragile. */
+export function scanFragileLinks(bodyMarkdown) {
+  const body = String(bodyMarkdown || "");
+  const findings = [];
+  const seen = new Set();
+  for (const match of body.matchAll(URL_RE)) {
+    const url = match[0].replace(/[.,;:!?]+$/, "");
+    if (seen.has(url)) continue;
+    seen.add(url);
+    for (const rule of FRAGILE_LINK_RULES) {
+      if (rule.test(url)) {
+        findings.push({ kind: rule.kind, url, message: rule.describe(url) });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * The agentInstruction paragraph for a body's fragile links, or "" when clean.
+ * Attaching the file is the remedy we point at: attachments download locally
+ * on the recipient's machine and carry durable links everywhere else.
+ */
+export function fragileLinkWarning(bodyMarkdown) {
+  const findings = scanFragileLinks(bodyMarkdown);
+  if (!findings.length) return "";
+  const details = findings.map((f) => f.message).join(" ");
+  return (
+    `WARNING — this message contains ${findings.length === 1 ? "a link" : "links"} the recipient likely cannot open: ${details} ` +
+    "The message was still sent. Repair it now: send a follow-up that attaches the actual file (relay_send's attachments) " +
+    "or pastes the relevant content, instead of the link."
+  );
+}

package/src/materializer.js

@@ -350,6 +350,13 @@ async function materializeRowInHost({
     openable = Boolean(cwd),
   } = resolveCwd({ row, rowState, requestedCwd, allowUnanchoredFallback });
   log(`relay open cwd: ${cwd || "<unresolved>"} (${cwdReason}${repoName ? `: ${repoName}` : ""}${workspaceKey ? ` ${workspaceKey}` : ""})`);
+  // Attachments are delivery, not routing: land the local copies BEFORE the
+  // routing gate. A relay that cannot open in a host (workspace-unmapped) must
+  // still put its files on disk — otherwise the pill chip and the seed link
+  // have nothing to point at, and the only remaining route is a signed URL
+  // that expires in minutes. This ran after the gate once, which silently
+  // stripped attachments from every unopenable relay.
+  const rowWithAttachments = await materializeAttachmentFiles(row, { log });
   if (!openable || !cwd) {
     rememberRow(id, {
       relayThreadId: row?.threadId || id,
@@ -359,6 +366,9 @@ async function materializeRowInHost({
       openWorkspaceKey: workspaceKey,
       materializationError: cwdReason,
       materializedAt: new Date().toISOString(),
+      // Keep the downloaded local copies (no signature keys: signatures are
+      // open-time state, and this row did not open).
+      ...(hasAttachments(rowWithAttachments) ? { attachments: rowWithAttachments.attachments } : {}),
     });
     return {
       id,
@@ -381,7 +391,6 @@ async function materializeRowInHost({
   // Neither host can retarget a live session's model either — a different
   // requested model re-forges exactly like a cwd change does.
   const modelChanged = Boolean(model) && Boolean(rowState.openModel) && String(rowState.openModel) !== String(model);
-  const rowWithAttachments = await materializeAttachmentFiles(row, { log });
   const materializationSignature = rowMaterializationSignature(rowWithAttachments);
   const materializationSignatureKey = attachmentSignatureKeyForHost(cleanHost);
   // forceFresh ("Open in new chat"): deliberately ignore the remembered native
@@ -527,17 +536,19 @@ async function materializeRowInHost({
   return { id, host: cleanHost, url, openedInHost, skipExternalOpen, claudeFreshlyForged, cwd, cwdReason, workspaceKey };
 }
 
-async function materializeAttachmentFiles(row, { log = () => {} } = {}) {
+export async function materializeAttachmentFiles(row, { log = () => {}, refreshUrls = defaultRefreshAttachmentUrls } = {}) {
   const attachments = Array.isArray(row?.attachments) ? row.attachments : [];
   if (!attachments.length) return row;
   const attachmentUrls = row?.attachmentUrls && typeof row.attachmentUrls === "object" ? row.attachmentUrls : {};
   const dir = path.join(storeDir(), "attachments", safeFileStem(row?.id || row?.relayId || "relay"));
   const materialized = [];
+  let misses = 0;
   for (const [index, attachment] of attachments.entries()) {
     if (!attachment || typeof attachment !== "object") continue;
     const name = String(attachment.name || attachment.filename || `attachment-${index + 1}`).trim() || `attachment-${index + 1}`;
     const url = String(attachmentUrls[attachment.id] || attachment.openUrl || "").trim();
     const localPath = await ensureAttachmentLocalCopy({ attachment, url, dir, name, index, log });
+    if (!localPath && attachment.id) misses += 1;
     materialized.push({
       ...attachment,
       name,
@@ -546,9 +557,41 @@ async function materializeAttachmentFiles(row, { log = () => {} } = {}) {
       ...(localPath ? { localPath } : {}),
     });
   }
+  // The signed URLs in `attachmentUrls` go stale ~15 minutes after the packet
+  // was fetched, so a lazy open days later downloads nothing. When anything is
+  // still missing, re-fetch the packet ONCE for fresh URLs and retry just the
+  // misses; failures still degrade to the durable openUrl in the seed.
+  if (misses && typeof refreshUrls === "function") {
+    let fresh = null;
+    try {
+      fresh = await refreshUrls(row);
+    } catch (error) {
+      log(`relay attachment URL refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (fresh && typeof fresh === "object") {
+      for (const [index, attachment] of materialized.entries()) {
+        if (!attachment || attachment.localPath || !attachment.id) continue;
+        const url = String(fresh[attachment.id] || "").trim();
+        if (!url) continue;
+        const localPath = await ensureAttachmentLocalCopy({ attachment, url, dir, name: attachment.name, index, log });
+        if (localPath) materialized[index] = { ...attachment, localPath };
+      }
+    }
+  }
   return { ...row, attachments: materialized };
 }
 
+/** Fresh signed attachment URLs for one staged row, via a single packet re-fetch. */
+async function defaultRefreshAttachmentUrls(row) {
+  const id = String(row?.id || row?.relayId || "").trim();
+  if (!id) return null;
+  const { RelayClient } = await import("./client.js");
+  const client = new RelayClient();
+  const response = await client.fetchRelayPackets([id]);
+  const entry = response?.packets?.[id];
+  return entry && entry.attachmentUrls && typeof entry.attachmentUrls === "object" ? entry.attachmentUrls : null;
+}
+
 async function ensureAttachmentLocalCopy({ attachment, url, dir, name, index, log }) {
   const existing = String(attachment.localPath || "").trim();
   if (existing && fs.existsSync(existing) && sizeMatches(existing, attachment.bytes)) return existing;
@@ -583,6 +626,37 @@ async function ensureAttachmentLocalCopy({ attachment, url, dir, name, index, lo
 // lying Content-Length). 200MB is generous for real attachments.
 const ATTACHMENT_DOWNLOAD_CAP = 200 * 1024 * 1024;
 
+/** How long a downloaded attachment dir may sit untouched before the sweep removes it. */
+const ATTACHMENT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Age out old local attachment copies. Attachments now download at ingest for
+ * every arriving relay (not only on open), so without retention the store grows
+ * with the inbox forever. Directory mtime is the signal: a re-download or a new
+ * file in the dir refreshes it. Runs at daemon start; failures never propagate.
+ */
+export function sweepStaleAttachmentFiles({ maxAgeMs = ATTACHMENT_RETENTION_MS, nowMs = Date.now(), log = () => {} } = {}) {
+  const root = path.join(storeDir(), "attachments");
+  const removed = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return removed;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(root, entry.name);
+    try {
+      if (nowMs - fs.statSync(dir).mtimeMs <= maxAgeMs) continue;
+      fs.rmSync(dir, { recursive: true, force: true });
+      removed.push(entry.name);
+    } catch {}
+  }
+  if (removed.length) log(`swept ${removed.length} stale attachment dir(s)`);
+  return removed;
+}
+
 function sizeMatches(filePath, expectedBytes) {
   if (!Number.isFinite(Number(expectedBytes))) return true;
   try {

package/src/mcp.js

@@ -3,6 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { prepareOrdinaryRelayAttachments, prepareTaskMessageAttachments, prepareTaskResult } from "./attachments.js";
 import { workspacePassportFromDeclaration } from "./repo-identity.js";
+import { fragileLinkWarning } from "./links.js";
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { RelayClient } from "./client.js";
@@ -866,14 +867,17 @@ function replyTitleFromBody(body) {
   return title.length > 120 ? `${title.slice(0, 119).trimEnd()}…` : title;
 }
 
-function relaySendResultForAgent(result) {
+function relaySendResultForAgent(result, { linkWarning = "" } = {}) {
   // Servers that predate threading hints simply omit the field, so an older API
   // keeps working and only loses the nudge.
   const hint = result?.threadingHint;
   const contactNeedsWork = Boolean(result?.contact?.autoCreated);
-  if (!hint && !contactNeedsWork) return result;
+  if (!hint && !contactNeedsWork && !linkWarning) return result;
 
   const instructions = [];
+  // Broken-for-the-recipient links come first: the repair (attach the file)
+  // has the shortest useful window.
+  if (linkWarning) instructions.push(linkWarning);
   if (hint?.message) instructions.push(hint.message);
   if (contactNeedsWork) {
     instructions.push(
@@ -975,7 +979,7 @@ export async function handleCall(client, name, args, { mode = DEFAULT_COMPANION_
           ...(args.threadTitle ? { threadTitle: args.threadTitle } : {}),
           ...(args.type ? { type: args.type } : {}),
           idempotencyKey: args.idempotencyKey,
-        })),
+        }), { linkWarning: fragileLinkWarning(args.bodyMarkdown) }),
       );
     case "relay_contacts_search":
       return text(await client.searchContacts(args.query));
@@ -1101,6 +1105,7 @@ export async function handleCall(client, name, args, { mode = DEFAULT_COMPANION_
             ...(args.threadTitle ? { threadTitle: args.threadTitle } : {}),
             idempotencyKey: args.idempotencyKey,
           }),
+          { linkWarning: fragileLinkWarning(bodyMarkdown) },
         ),
       );
     }

package/src/notifications.js

@@ -600,6 +600,24 @@ export function reconcileAnsweredQuestions(relays = [], { statePath = companionS
   });
 }
 
+/**
+ * Patch a staged row's attachments in place (the ingest prefetch writes the
+ * acquired localPath values back after download). Deliberately writes ONLY the
+ * attachments array — never the materialization-signature keys, which are
+ * open-time state owned by the materializer.
+ */
+export function updateStagedRelayAttachments(relayId, attachments, { statePath = companionStatePath() } = {}) {
+  if (!relayId || !Array.isArray(attachments)) return false;
+  return withJsonLock(statePath, () => {
+    const state = readCompanionState(statePath);
+    const row = state.packets && state.packets[relayId];
+    if (!row) return false;
+    row.attachments = attachments;
+    writeCompanionState(statePath, state);
+    return true;
+  });
+}
+
 export function stagePlainRelayItem(
   { item, packet, attachmentUrls = {} },
   { statePath = companionStatePath(), forceUnread = false } = {},

package/src/task-daemon.js

@@ -18,6 +18,7 @@ import {
   removeSuppressedCompanionItems,
   reconcileAnsweredQuestions,
   stagePlainRelayItem as defaultStagePlainRelayItem,
+  updateStagedRelayAttachments,
 } from "./notifications.js";
 import { createAutoUpdater } from "./auto-update.js";
 import { startLogRotation } from "./log-rotate.js";
@@ -200,6 +201,31 @@ async function fetchPacketsForItems({ client, items, log }) {
   return byId;
 }
 
+/**
+ * Download a freshly staged relay's attachments NOW, while the packet's signed
+ * URLs are seconds old, and patch the acquired localPaths onto the staged row.
+ * Ingest is the one moment the URLs are guaranteed live — a lazy download on a
+ * click days later starts from an expired signature. Failures only log: the
+ * open path re-runs the same idempotent download (with a URL refresh) anyway.
+ */
+async function prefetchStagedRelayAttachments({ item, packet, attachmentUrls, log }) {
+  const attachments = Array.isArray(packet?.attachments) ? packet.attachments : [];
+  if (!attachments.length) return;
+  try {
+    const { materializeAttachmentFiles } = await import("./materializer.js");
+    const materialized = await materializeAttachmentFiles(
+      { id: item.relayId, attachments, attachmentUrls: attachmentUrls || {} },
+      { log },
+    );
+    const withLocal = (materialized.attachments || []).filter((a) => a && a.localPath).length;
+    if (withLocal && updateStagedRelayAttachments(item.relayId, materialized.attachments)) {
+      log(`prefetched ${withLocal}/${attachments.length} attachment(s) for ${item.relayId}`);
+    }
+  } catch (err) {
+    log(`attachment prefetch failed for ${item.relayId}: ${err && err.message ? err.message : err}`);
+  }
+}
+
 async function pollPlainInbox({ client, ledger, stagePlainRelay, log, persistLedger = () => {} }) {
   if (typeof client.inbox !== "function" || typeof client.fetchRelay !== "function") return [];
   try {
@@ -242,6 +268,18 @@ async function pollPlainInbox({ client, ledger, stagePlainRelay, log, persistLed
         log(`ordinary Relay staging failed for ${item.relayId}: ${err.message}`);
       }
     }
+    // Prefetch attachments only after every stage + ledger commit has landed,
+    // so a slow download can never delay the relays queued behind it.
+    for (const item of staged) {
+      const relay = packets.get(item.relayId);
+      if (!relay || !relay.packet) continue;
+      await prefetchStagedRelayAttachments({
+        item,
+        packet: relay.packet,
+        attachmentUrls: relay.attachmentUrls || {},
+        log,
+      });
+    }
     staged.inboxOk = true;
     return staged;
   } catch (err) {
@@ -522,6 +560,14 @@ export async function runOrdinaryRelayDaemon({ intervalMs = 4000 } = {}) {
   // Keep the always-on logs bounded. The daemon is the single long-lived owner on
   // the machine, so it is the natural place to cap files that nothing else prunes.
   startLogRotation({ log });
+  // Age out downloaded attachment copies; ingest prefetch would otherwise grow
+  // ~/.relay-companion/attachments with the inbox forever.
+  try {
+    const { sweepStaleAttachmentFiles } = await import("./materializer.js");
+    sweepStaleAttachmentFiles({ log });
+  } catch (err) {
+    log(`attachment sweep failed: ${err && err.message ? err.message : err}`);
+  }
   // Re-register Windows autostart tasks that have gone missing. Without them the
   // machine has no logon start at all, and (before the updater stopped depending on
   // them) every self-update rolled itself back. Cheap query, no-ops off win32.
@@ -619,6 +665,14 @@ export async function runTaskDaemon({ intervalMs = 4000 } = {}) {
   // Keep the always-on logs bounded. The daemon is the single long-lived owner on
   // the machine, so it is the natural place to cap files that nothing else prunes.
   startLogRotation({ log });
+  // Age out downloaded attachment copies; ingest prefetch would otherwise grow
+  // ~/.relay-companion/attachments with the inbox forever.
+  try {
+    const { sweepStaleAttachmentFiles } = await import("./materializer.js");
+    sweepStaleAttachmentFiles({ log });
+  } catch (err) {
+    log(`attachment sweep failed: ${err && err.message ? err.message : err}`);
+  }
   // Re-register Windows autostart tasks that have gone missing. Without them the
   // machine has no logon start at all, and (before the updater stopped depending on
   // them) every self-update rolled itself back. Cheap query, no-ops off win32.