@olares/lares-core 0.15.7 → 0.15.9

package/files/preview-workspace.js

@@ -1,3 +1,4 @@
+import { filesPathAfterPrefix, isFilesPath, parseFilesPath } from "../drive/files-path.js";
 import { closeTab, openTab, touchTab } from "./preview-tabs.js";
 
 export class NullScrollport {
@@ -22,18 +23,51 @@ function errorCode(payload) {
   return payload?.error?.code || "file_preview_failed";
 }
 
-export async function fetchPreview(sessionId, path) {
+const PREVIEW_KINDS = new Set([
+  "image", "video", "audio", "model3d", "pdf", "markdown", "text", "unsupported",
+]);
+
+export function isPreviewPayload(payload) {
+  return Boolean(
+    payload
+    && typeof payload === "object"
+    && typeof payload.path === "string"
+    && payload.path !== ""
+    && typeof payload.name === "string"
+    && PREVIEW_KINDS.has(payload.kind)
+    && Number.isSafeInteger(payload.size)
+    && payload.size >= 0
+    && (payload.modifiedAt === undefined || Number.isFinite(payload.modifiedAt))
+    && (!["text", "markdown"].includes(payload.kind) || typeof payload.text === "string"),
+  );
+}
+
+/**
+ * The path the preview should ask the Host for. dsh already joined a relative
+ * target onto the session cwd; a Files address must go back to its own
+ * namespace before it becomes a tab key or a query.
+ */
+export function previewOpenPath(cwd, path) {
+  const requested = String(path ?? "");
+  if (isFilesPath(requested)) return parseFilesPath(requested);
+  return filesPathAfterPrefix(cwd, requested) ?? requested;
+}
+
+export async function fetchPreview(sessionId, path, options = {}) {
   const query = new URLSearchParams({ sessionId, path });
-  const response = await fetch(`/api/lares/file-preview/preview?${query}`);
+  const response = await fetch(`/api/lares/file-preview/preview?${query}`, {
+    signal: options.signal,
+  });
   const payload = await response.json().catch(() => null);
   if (!response.ok) throw new Error(errorCode(payload));
+  if (!isPreviewPayload(payload)) throw new Error("file_preview_failed");
   return payload;
 }
 
-export async function fetchPreviewMap(sessionId, paths) {
+export async function fetchPreviewMap(sessionId, paths, options = {}) {
   const entries = await Promise.all(paths.map(async (path) => {
     try {
-      return [path, await fetchPreview(sessionId, path)];
+      return [path, await fetchPreview(sessionId, path, options)];
     } catch {
       return [path, null];
     }
@@ -52,9 +86,54 @@ export function workspaceLinkClickPath(sessionId, event) {
   return rawUrlPath(sessionId, anchor.getAttribute("href"));
 }
 
-export async function interceptOpenPath(workspace, path, openNative) {
-  if (await workspace.openCurrent(path)) return;
-  await openNative(path);
+/**
+ * The agent Reads the application overlay (`/app/packages/…`). That is source,
+ * not a user file: the preview cannot serve it, and treating the path as an
+ * openable chip only produces a dead tab. `/app/name.ext` still probes because
+ * the workspace aliases that basename.
+ */
+export function isUnpreviewableOpenPath(path) {
+  const text = String(path ?? "").trim().replace(/\\/g, "/");
+  if (!text.startsWith("/app")) return false;
+  if (text === "/app" || text === "/app/") return true;
+  const rest = text.slice("/app/".length);
+  return rest.includes("/");
+}
+
+const FILE_ADDRESS_PREFIX = "dsh-resource://file/session/";
+
+/**
+ * The session and path behind dsh's session file address
+ * (`dsh-resource://file/session/<id>/<path>`), or null for any other resource.
+ * Query and fragment suffixes are dsh's navigation parameters, not the path.
+ * An empty path names the session's workspace root — a directory the preview
+ * never serves — so it reads as no file address at all.
+ */
+export function parseSessionFileAddress(address) {
+  const text = String(address ?? "");
+  if (!text.startsWith(FILE_ADDRESS_PREFIX)) return null;
+  const end = text.search(/[?#]/);
+  const body = text.slice(FILE_ADDRESS_PREFIX.length, end === -1 ? undefined : end);
+  const [id, ...segments] = body.split("/");
+  if (!id || segments.length === 0) return null;
+  let decoded;
+  try {
+    decoded = { sessionId: decodeURIComponent(id), path: segments.map(decodeURIComponent).join("/") };
+  } catch {
+    return null;
+  }
+  return decoded.path === "" ? null : decoded;
+}
+
+/**
+ * @param target - the session and path a Host open request decoded to.
+ * @param openNative - the Host's own opener for a request the preview declines.
+ */
+export async function interceptOpenPath(workspace, target, openNative) {
+  if (target.sessionId !== workspace.boundSession()) return openNative();
+  if (isUnpreviewableOpenPath(target.path)) return;
+  if (await workspace.openCurrent(target.path)) return;
+  await openNative();
 }
 
 const RAW_ROUTE = "/api/lares/file-preview/raw";
@@ -65,9 +144,15 @@ export function previewMetaUrl(sessionId, path) {
   return `/api/lares/file-preview/preview?${query}`;
 }
 
-export function rawFileUrl(sessionId, path, modifiedAt) {
+/**
+ * @param size - ask the files backend for a rendition of this size instead of
+ * the stored bytes. Honored for images on the files backend and ignored
+ * everywhere else, so a caller that wants a small copy may always ask.
+ */
+export function rawFileUrl(sessionId, path, modifiedAt, size) {
   const query = new URLSearchParams({ sessionId, path });
   if (modifiedAt !== undefined) query.set("v", String(modifiedAt));
+  if (size) query.set("size", size);
   return `${RAW_ROUTE}?${query}`;
 }
 
@@ -139,25 +224,41 @@ export class FilePreviewWorkspace {
     return () => state.listeners.delete(listener);
   }
 
-  bindCurrent(sessionId) {
-    const binding = { sessionId };
+  bindCurrent(sessionId, cwd) {
+    const binding = { sessionId, cwd, openVersion: 0 };
     this.current = binding;
     return () => {
       if (this.current === binding) this.current = null;
     };
   }
 
+  /** The session the on-screen conversation mounted, or null while none is. */
+  boundSession() {
+    return this.current?.sessionId ?? null;
+  }
+
   /**
    * Claim a Host open request, or decline it. The preview serves regular files
    * only, so the target is resolved before any tab exists: a directory stays
    * with the Host's own opener instead of becoming a tab that can never load.
+   * Overlay source is declined without a fetch or a tab — claiming it is what
+   * turned Read rows like `/app/packages/…` into a clickable preview that then
+   * failed. Files errors (auth included) still open a tab so the chat view's
+   * successful claim is not a silent click; Host does not native-open.
    */
   async openCurrent(path) {
     if (!this.current) return false;
-    const { sessionId } = this.current;
-    const content = await this.fetchContent(sessionId, path);
+    const binding = this.current;
+    const { sessionId, cwd } = binding;
+    const version = ++binding.openVersion;
+    const target = previewOpenPath(cwd, path);
+    if (isUnpreviewableOpenPath(target)) return false;
+    const content = await this.fetchContent(sessionId, target);
+    // A later click or session switch owns the surface. The old request was
+    // still claimed, but must not steal focus or open a stale native panel.
+    if (this.current !== binding || binding.openVersion !== version) return true;
     if (content.status === "error" && content.message === "path_not_file") return false;
-    this.open(sessionId, path, content);
+    this.open(sessionId, target, content);
     return true;
   }
 

package/files/preview.js

@@ -1,7 +1,8 @@
 import { open, stat } from "node:fs/promises";
 import { basename, extname, relative } from "node:path";
-import { isFilesPath, parseFilesPath } from "../drive/files-path.js";
-import { statFilesFile } from "../drive/ls.js";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { filesPathAfterPrefix, isFilesNamespace, parseFilesPath } from "../drive/files-path.js";
 import { HttpError } from "../tools/http.js";
 import {
   resolveExistingWorkspacePath,
@@ -9,7 +10,7 @@ import {
   workspaceCandidate,
   workspaceFileAlias,
 } from "../workspace/path.js";
-import { materializeFilesFile } from "./preview-cache.js";
+import { resolveLocalPreviewFile } from "./preview-local.js";
 
 export const MAX_PREVIEW_TEXT_BYTES = 1024 * 1024;
 export const MAX_RAW_BYTES = 200 * 1024 * 1024;
@@ -39,8 +40,6 @@ const AUDIO_TYPES = new Map([
 ]);
 const MODEL3D_TYPES = new Map([
   [".glb", "model/gltf-binary"],
-  [".gltf", "model/gltf+json"],
-  [".obj", "model/obj"],
 ]);
 const TEXT_EXTENSIONS = new Set([
   "",
@@ -50,6 +49,7 @@ const TEXT_EXTENSIONS = new Set([
   ".go", ".java", ".kt", ".c", ".h", ".cpp", ".hpp", ".sql", ".r", ".rb",
   ".php", ".swift", ".vue", ".svelte", ".mdx", ".gitignore", ".dockerignore",
   ".editorconfig", ".srt", ".vtt", ".ass", ".ssa",
+  ".gltf", ".obj",
 ]);
 
 export function previewQueryFromUrl(reqUrl) {
@@ -77,7 +77,10 @@ export async function resolveFilesPreviewFile(requestedPath, deps = {}) {
     throw new HttpError("path_invalid", 400, error instanceof Error ? error.message : String(error));
   }
   try {
-    const info = await (deps.stat ?? statFilesFile)(source, deps);
+    if (typeof deps.stat !== "function") {
+      throw new HttpError("files_unavailable", 503, "Olares Files client is unavailable");
+    }
+    const info = await deps.stat(source, deps);
     return {
       origin: "files",
       path: info.path,
@@ -91,23 +94,33 @@ export async function resolveFilesPreviewFile(requestedPath, deps = {}) {
   }
 }
 
+function joinedFilesAddress(workspacePath, root, requestedPath) {
+  return filesPathAfterPrefix(workspacePath, requestedPath)
+    ?? filesPathAfterPrefix(root, requestedPath);
+}
+
 export async function fileFromPreviewRequest(reqUrl, resolveWorkspace, deps = {}) {
   const { path, sessionId } = previewQueryFromUrl(reqUrl);
-  if (isFilesPath(path)) return resolveFilesPreviewFile(path, deps);
+  if (isFilesNamespace(path)) return resolveFilesPreviewFile(path, deps);
+  const local = await (deps.resolveLocal ?? resolveLocalPreviewFile)(path, deps);
+  if (local) return { ...local, ...previewTypeForName(local.absolutePath) };
   const workspace = await resolveWorkspace(sessionId);
-  return resolveWorkspaceFile(workspace.path, path);
+  const root = await resolveWorkspaceRoot(workspace.path);
+  try {
+    return await resolveWorkspaceFile(root, path);
+  } catch (error) {
+    // A real workspace file of the same name wins. dsh joins Files addresses
+    // onto cwd; that prefix may be the lexical workspace path or its realpath.
+    const joined = error?.code === "file_not_found" || error?.code === "path_forbidden";
+    const address = joined ? joinedFilesAddress(workspace.path, root, path) : null;
+    if (address === null) throw error;
+    return resolveFilesPreviewFile(address, deps);
+  }
 }
 
 async function ensurePreviewBytes(file, deps = {}) {
   if (file.absolutePath) return file;
-  if (file.origin !== "files") {
-    throw new HttpError("file_preview_failed", 500, "file has no local path");
-  }
-  try {
-    return await (deps.materialize ?? materializeFilesFile)(file, deps);
-  } catch (error) {
-    throw asPreviewHttpError(error);
-  }
+  throw new HttpError("file_preview_failed", 500, "file has no local path");
 }
 
 export function previewTypeForName(name) {
@@ -191,6 +204,37 @@ export async function buildPreview(file, deps) {
   };
   const knownText = ["text", "markdown"].includes(file.kind);
   if (!knownText && file.kind !== "unsupported") return metadata;
+  if (file.origin === "files") {
+    if (typeof deps?.readFilesRaw !== "function") {
+      throw new HttpError("files_unavailable", 503, "Olares Files client is unavailable");
+    }
+    let raw;
+    try {
+      raw = await deps.readFilesRaw(file.path, MAX_PREVIEW_TEXT_BYTES + 1);
+    } catch (error) {
+      throw asPreviewHttpError(error);
+    }
+    const truncated = file.size > MAX_PREVIEW_TEXT_BYTES || raw.truncated;
+    const read = raw.bytes.subarray(0, MAX_PREVIEW_TEXT_BYTES);
+    const body = truncated ? trimPartialUtf8(read) : read;
+    try {
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+      if (!knownText && !looksLikeText(text)) return metadata;
+      return {
+        ...metadata,
+        kind: knownText ? file.kind : "text",
+        mediaType: knownText ? file.mediaType : "text/plain; charset=utf-8",
+        text,
+        truncated,
+      };
+    } catch (error) {
+      if (error instanceof TypeError) {
+        if (!knownText) return metadata;
+        throw new HttpError("file_not_text", 415, "file is not valid UTF-8 text");
+      }
+      throw error;
+    }
+  }
   const local = await ensurePreviewBytes(file, deps);
   const handle = await openVerified(local);
   try {
@@ -306,6 +350,113 @@ async function sendFile(req, res, file, disposition) {
   stream.pipe(res);
 }
 
+function filesDispositionHeaders(file, disposition) {
+  return {
+    "accept-ranges": "bytes",
+    "cache-control": "private, no-cache",
+    "content-type": file.mediaType,
+    "content-disposition": `${disposition}; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+    "x-content-type-options": "nosniff",
+  };
+}
+
+async function sendFilesFile(req, res, file, disposition, deps = {}) {
+  // Validate against the metadata we just resolved before forwarding. This
+  // keeps malformed and out-of-bounds ranges from becoming an opaque Files 502.
+  parseRange(req.headers.range, file.size);
+  // HEAD is answered from the listing we already did. Files has no HEAD verb;
+  // a 1-byte GET probe must not become the download preflight's size.
+  if (req.method === "HEAD") {
+    const range = parseRange(req.headers.range, file.size);
+    const start = range?.start ?? 0;
+    const end = range?.end ?? Math.max(0, file.size - 1);
+    const headers = {
+      ...filesDispositionHeaders(file, disposition),
+      "content-length": String(file.size === 0 ? 0 : end - start + 1),
+    };
+    if (range) headers["content-range"] = `bytes ${start}-${end}/${file.size}`;
+    res.writeHead(range ? 206 : 200, headers);
+    res.end();
+    return;
+  }
+  if (typeof deps.openFilesRaw !== "function") {
+    throw new HttpError("files_unavailable", 503, "Olares Files client is unavailable");
+  }
+  let response;
+  try {
+    response = await deps.openFilesRaw(file.path, {
+      method: "GET",
+      range: req.headers.range,
+    });
+  } catch (error) {
+    throw asPreviewHttpError(error);
+  }
+  const headers = filesDispositionHeaders(file, disposition);
+  for (const name of ["accept-ranges", "content-length", "content-range"]) {
+    const value = response.headers.get(name);
+    if (value) headers[name] = value;
+  }
+  res.writeHead(response.status, headers);
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  await pipeline(Readable.fromWeb(response.body), res);
+}
+
+/**
+ * The rendition this request asked for, or null for the stored bytes.
+ *
+ * Only an image on the files backend has one, because only there does a
+ * resized copy already exist: the backend renders it once and caches it. A
+ * conversation showing a 4000px generation at a few hundred pixels wide is
+ * the case this exists for. Opening the file and downloading it both stay on
+ * the original, so what is displayed and what is kept stay separate choices.
+ */
+export function previewSizeFromUrl(reqUrl, file) {
+  if (file?.origin !== "files" || file?.kind !== "image") return null;
+  const size = new URL(reqUrl ?? "/", "http://x").searchParams.get("size");
+  return ["thumb", "big"].includes(size) ? size : null;
+}
+
+/**
+ * A rendition is not the stored bytes, so it carries neither the original's
+ * length nor byte ranges. HEAD is answered without fetching one: the only
+ * honest length is the rendered one, and rendering a copy to describe and
+ * then discard is worse than omitting a header HEAD does not require.
+ */
+async function sendFilesRendition(req, res, file, size, deps = {}) {
+  const headers = {
+    "cache-control": "private, no-cache",
+    "content-type": file.mediaType,
+    "content-disposition": `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+    "x-content-type-options": "nosniff",
+  };
+  if (req.method === "HEAD") {
+    res.writeHead(200, headers);
+    res.end();
+    return;
+  }
+  if (typeof deps.openFilesPreview !== "function") {
+    throw new HttpError("files_unavailable", 503, "Olares Files client is unavailable");
+  }
+  let response;
+  try {
+    response = await deps.openFilesPreview(file.path, { size });
+  } catch (error) {
+    throw asPreviewHttpError(error);
+  }
+  headers["content-type"] = response.headers.get("content-type") || file.mediaType;
+  const length = response.headers.get("content-length");
+  if (length) headers["content-length"] = length;
+  res.writeHead(response.status, headers);
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  await pipeline(Readable.fromWeb(response.body), res);
+}
+
 export async function sendRawFile(req, res, file, deps) {
   if (!["image", "video", "audio", "pdf", "model3d"].includes(file.kind)) {
     throw new HttpError("preview_unsupported", 415, "raw preview is not supported for this file");
@@ -315,6 +466,9 @@ export async function sendRawFile(req, res, file, deps) {
   if (["image", "pdf", "model3d"].includes(file.kind) && file.size > MAX_RAW_BYTES) {
     throw new HttpError("file_too_large", 413, `file exceeds ${MAX_RAW_BYTES} bytes`);
   }
+  const size = previewSizeFromUrl(req.url, file);
+  if (size) return sendFilesRendition(req, res, file, size, deps);
+  if (file.origin === "files") return sendFilesFile(req, res, file, "inline", deps);
   return sendFile(req, res, await ensurePreviewBytes(file, deps), "inline");
 }
 
@@ -324,5 +478,6 @@ export async function sendRawFile(req, res, file, deps) {
  * about what the user may keep a copy of.
  */
 export async function sendFileDownload(req, res, file, deps) {
+  if (file.origin === "files") return sendFilesFile(req, res, file, "attachment", deps);
   return sendFile(req, res, await ensurePreviewBytes(file, deps), "attachment");
 }

package/files/produced-gate.js

@@ -0,0 +1,197 @@
+import { stat } from "node:fs/promises";
+import { isFilesPath } from "../drive/files-path.js";
+import {
+  durablePathFromToolCall,
+  parseToolArguments,
+  toolResultIsError,
+} from "./published-tools.js";
+import { isMediaDeliverablePath } from "./preview-groups.js";
+import {
+  resolveExistingWorkspacePath,
+  resolveWorkspaceRoot,
+  workspaceCandidate,
+} from "../workspace/path.js";
+
+export const PRODUCED_GATE_PLUGIN = "lares-produced-gate";
+export const MAX_PRODUCED_GATE_STEERS = 2;
+
+export { durablePathFromToolCall, parseToolArguments } from "./published-tools.js";
+
+/**
+ * Successful mutation paths for one turn, in tool order, deduped.
+ * @param {Iterable<{ type?: string, data?: any }>} events
+ */
+export function durableProducedPathsFromEvents(events, turn) {
+  const pending = new Map();
+  const paths = [];
+  const seen = new Set();
+  for (const event of events) {
+    if (event?.data?.turn !== turn) continue;
+    if (event.type === "tool/call") {
+      const callId = String(event.data.callId ?? "");
+      const name = String(event.data.name ?? "");
+      const path = durablePathFromToolCall(name, parseToolArguments(event.data.arguments));
+      if (callId && path) pending.set(callId, path);
+      continue;
+    }
+    if (event.type !== "tool/result") continue;
+    if (toolResultIsError(event)) continue;
+    const callId = String(event.data?.message?.source?.callId ?? "");
+    const path = pending.get(callId);
+    if (!path || seen.has(path)) continue;
+    seen.add(path);
+    paths.push(path);
+  }
+  return paths;
+}
+
+function resultTexts(value, texts = []) {
+  if (Array.isArray(value)) {
+    for (const item of value) resultTexts(item, texts);
+    return texts;
+  }
+  if (!value || typeof value !== "object") return texts;
+  if (typeof value.text === "string") texts.push(value.text);
+  if ("content" in value) resultTexts(value.content, texts);
+  return texts;
+}
+
+function parseResultJson(text) {
+  const source = String(text ?? "").trim();
+  if (!source) return null;
+  try {
+    return JSON.parse(source);
+  } catch {
+    const start = source.indexOf("{");
+    const end = source.lastIndexOf("}");
+    if (start === -1 || end <= start) return null;
+    try {
+      return JSON.parse(source.slice(start, end + 1));
+    } catch {
+      return null;
+    }
+  }
+}
+
+function collectFilesPaths(value, paths) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectFilesPaths(item, paths);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  const status = typeof value.status === "string" ? value.status.toLowerCase() : "";
+  if ([
+    "queued", "pending", "submitted", "starting", "processing", "in_progress", "running",
+    "failed", "error", "canceled", "cancelled",
+  ].includes(status)) {
+    return;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if ((key === "files_path" || key === "filesPath") && typeof item === "string") {
+      const path = item.trim().replace(/\\/g, "/");
+      if (isFilesPath(path) && isMediaDeliverablePath(path)) paths.push(path);
+      continue;
+    }
+    collectFilesPaths(item, paths);
+  }
+}
+
+/**
+ * Generation is performed through bash/curl, so dsh has no native artifact
+ * event for its result. Recover media addresses from successful tool output and
+ * require the agent to declare each one through workspace_publish.
+ */
+export function unpublishedMediaPathsFromEvents(events, turn) {
+  const published = new Set(durableProducedPathsFromEvents(events, turn));
+  const paths = [];
+  const seen = new Set();
+  for (const event of events) {
+    if (event?.type !== "tool/result" || event?.data?.turn !== turn) continue;
+    if (toolResultIsError(event)) continue;
+    for (const text of resultTexts(event.data?.message?.content)) {
+      const parsed = parseResultJson(text);
+      if (parsed === null) continue;
+      const found = [];
+      collectFilesPaths(parsed, found);
+      for (const path of found) {
+        if (published.has(path) || seen.has(path)) continue;
+        seen.add(path);
+        paths.push(path);
+      }
+    }
+  }
+  return paths;
+}
+
+export function unpublishedMediaSteerText(paths) {
+  const list = paths.map((path) => `- \`${path}\``).join("\n");
+  return [
+    "A completed media generation returned files that are not published to this turn:",
+    list,
+    "Call workspace_publish once for each exact files_path above before replying.",
+    "Do not regenerate, download, or copy these files; they already exist in Olares Files.",
+    "Only claim that the preview is available after workspace_publish succeeds.",
+  ].join("\n");
+}
+
+async function pathIsOpenable(workspaceRoot, path, deps = {}) {
+  // Olares Files requires the browser credential carried by an interactive
+  // preview request. A background turn-stopping hook must not reuse the last
+  // process-global CLI identity or block a turn because that token expired.
+  if (isFilesPath(path)) return true;
+  try {
+    const root = await (deps.resolveWorkspaceRoot ?? resolveWorkspaceRoot)(workspaceRoot);
+    const absolute = await (deps.resolveExistingWorkspacePath ?? resolveExistingWorkspacePath)(
+      root,
+      workspaceCandidate(root, path),
+    );
+    const info = await (deps.stat ?? stat)(absolute);
+    return info.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {Promise<string[]>} paths that cannot be opened for preview.
+ */
+export async function findUnopenableProducedPaths(workspaceRoot, paths, deps = {}) {
+  const missing = [];
+  for (const path of paths) {
+    if (!(await pathIsOpenable(workspaceRoot, path, deps))) missing.push(path);
+  }
+  return missing;
+}
+
+export function producedGateSteerText(missing) {
+  const list = missing.map((path) => `- \`${path}\``).join("\n");
+  return [
+    "Produced-file openability check failed before this turn could close.",
+    "These paths were offered as deliverables but cannot be opened right now:",
+    list,
+    "Restore or rewrite each file at that exact path, or workspace_publish a",
+    "replacement path and name only openable finals in your reply.",
+    "Do not claim a file is ready until it opens. Research fetches under",
+    "downloads/ (git/API JSON, chart YAML, READMEs) are scratch — delete them",
+    "freely, but keep image / video / audio / 3D media and final write/edit outputs.",
+  ].join("\n");
+}
+
+/**
+ * Per-agent turn budget so a stuck restore cannot loop forever.
+ */
+export function createProducedGateBudget(max = MAX_PRODUCED_GATE_STEERS) {
+  const attempts = new Map();
+  return {
+    remaining(agentId, turn) {
+      const key = `${agentId}:${turn}`;
+      return Math.max(0, max - (attempts.get(key) ?? 0));
+    },
+    consume(agentId, turn) {
+      const key = `${agentId}:${turn}`;
+      const next = (attempts.get(key) ?? 0) + 1;
+      attempts.set(key, next);
+      return next <= max;
+    },
+  };
+}

package/files/produced-mentions.js

@@ -0,0 +1,19 @@
+import { fileName } from "./filename.js";
+
+/** Strip mention wrappers (`code`, @path) so a chip can match a produced path. */
+export function mentionText(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().replace(/^@/, "").replace(/^`+|`+$/g, "");
+}
+
+/**
+ * True when the visible label is only a produced path (or its leaf). Used to
+ * hide the in-message chip that duplicates the turn-tail preview.
+ */
+export function isDuplicateProducedMention(text, paths) {
+  const bare = mentionText(text);
+  if (!bare || !Array.isArray(paths) || paths.length === 0) return false;
+  return paths.some((path) => {
+    const produced = mentionText(path);
+    return produced !== "" && (bare === produced || bare === fileName(produced));
+  });
+}