@retasc/cli 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.30.0 (2026-08-20)
+
+- **RTSC-681** — your agent can read a file you attached to an issue. Uploading has
+  been one call since 1.24.0; reading one back needed an API key the model does not
+  have and is told not to go looking for, so a certificate attached for an agent to
+  verify was something it could see the name of and nothing else. `get_attachment_file`
+  closes it: name the attachment id, the proxy downloads it with the credential it
+  already holds and hands back a path to read. Any size, and the bytes never pass
+  through the model's context.
+- **RTSC-681** — downloads land under `.retasc/attachments/` in your workspace, one
+  folder per attachment, never overwriting anything and never following a symlink, in
+  a directory that ignores itself so a customer's certificate cannot be committed by
+  accident. There is no destination argument on purpose: a write the proxy performs
+  skips the prompt your harness would otherwise show you, so it only ever writes to
+  the one place it owns. Copy the file where you want it and your normal tools ask you
+  first, which is the point.
+
+## 1.29.0 (2026-08-19)
+
+- **RTSC-672** — every command we hand out now says `npx @retasc/cli@latest`. npx caches
+  by spec, so a bare `npx @retasc/cli` can keep serving whatever version you first ran —
+  which meant the people most likely to re-run a command, the ones who hit a bug and were
+  told it was fixed, were exactly the ones liable to be served the broken build again.
+  `@latest` is a tag, not a pin: it re-resolves every time and can never go stale, where a
+  version number written into docs absolutely can.
+- **RTSC-672** — a first-run failure names the build that produced it, so "it still
+  doesn't work" and "you're running last week's CLI" stop looking identical.
+
 ## 1.28.0 (2026-08-19)
 
 - **RTSC-676** — signing in opens your browser. It used to print a URL and an

package/dist/commands/bind.js

@@ -5,7 +5,7 @@ import { loadConfig, patchConfig } from "../config.js";
 import { installMarker, printMarkerBlock } from "./mcp.js";
 import { readLocalBinding, resolveBinding } from "../lib/binding.js";
 import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
-import { resolveLauncher, launcherNote, runsOk, selfCommand } from "../lib/launcher.js";
+import { resolveLauncher, launcherNote, runsOk, selfCommand, versionStamp } from "../lib/launcher.js";
 import { ask, confirm, isInteractive } from "../lib/prompt.js";
 import { clean } from "../lib/text.js";
 import { card, DOT } from "../lib/card.js";
@@ -563,7 +563,11 @@ export async function ensureSignedIn() {
     if (loadConfig().token)
         return;
     if (!isInteractive()) {
-        throw new Error(`Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`);
+        // RTSC-672 — the stamp rides in the HINT, not the message. `formatError` keeps only
+        // the first line of a message (deliberately, to strip stack noise), so a second line
+        // here would be silently dropped — which is how a diagnostic aimed at silent failures
+        // would itself fail silently.
+        cliError("UNAUTHENTICATED", `Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`, versionStamp(VERSION).trim());
     }
     // RTSC-508: don't name a provider here. `deviceLogin` asks which door, and
     // announcing "GitHub" before the question would be wrong for the invited

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { VERSION } from "./version.js";
-import { selfCommand } from "./lib/launcher.js";
+import { selfCommand, versionStamp } from "./lib/launcher.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
@@ -27,9 +27,13 @@ program
 function requireLogin() {
     if (!isLoggedIn()) {
         // RTSC-671 — `selfCommand` renders the form they actually used. The docs send a
-        // new owner through `npx @retasc/cli`, which never puts `retasc` on PATH, so naming
+        // new owner through `npx @retasc/cli@latest`, which never puts `retasc` on PATH, so naming
         // it here answers a failure with a second `command not found`.
         console.error(`Not signed in. Run \`${selfCommand(VERSION)} login\` first.`);
+        // RTSC-672 — say which build spoke. A stale CLI and a broken one produce the same
+        // sentence otherwise, and the people most likely to re-run this are the ones who
+        // were just told a fix shipped.
+        console.error(versionStamp(VERSION));
         process.exit(1);
     }
 }
@@ -403,7 +407,7 @@ members
         // them in, binds the folder and wires their agent, so this must not tell them to run
         // `retasc login` first — nor name a `retasc` binary they don't have yet.
         console.log(`  Share it. In the folder their agent works in, they run:`);
-        console.log(`      npx @retasc/cli join ${res.code}`);
+        console.log(`      npx @retasc/cli@latest join ${res.code}`);
     }
     catch (e) {
         fail(e);

package/dist/lib/fetchFile.js

@@ -0,0 +1,222 @@
+// Local file DOWNLOAD for the MCP proxy (RTSC-681) — the read counterpart to attachFile.ts.
+//
+// Why this exists: attachments were one-way. Uploading has been a single tool call since
+// RTSC-660 (the agent names a path, the proxy uploads with the key it holds), but reading one
+// back required `Authorization: Bearer <agent key>` on /attachments/download — a credential the
+// model structurally does not have and is explicitly told not to hunt for. So a human could
+// attach a certificate for an agent to verify and the agent could see its name and nothing
+// else. The proxy already brokers bytes in one direction with a credential the model never
+// touches; this is the same trade in reverse.
+//
+// The cost of the reverse trade is different, and worse, which is why this module is stricter
+// than its sibling rather than a mirror image of it. attachFile.ts confines what may be READ,
+// because a proxy-side read bypasses the harness's file-access prompt. A proxy-side WRITE
+// bypasses the harness's write prompt, and a write is the more dangerous primitive: bytes we
+// place in `.claude/settings.json`, `.githooks/`, or a workflow file become someone's next
+// command execution. The filename is not ours either — it comes off an attachment row any org
+// member (or an importer pulling from Jira, ClickUp or Asana) can influence.
+//
+// So this side takes no destination from anybody. Downloads land in ONE directory the proxy
+// owns, under a sanitized name, never overwriting, never through a symlink. An agent that
+// wants the file somewhere else copies it with its own file tools — which the harness DOES
+// prompt on. That asymmetry is the whole argument: bypassing the read prompt was unavoidable
+// to make upload work at all, bypassing the write prompt is not.
+import { lstatSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+/** The one tool name for "read an attached file", whichever transport can carry the bytes.
+ *  The server publishes an INLINE variant under this SAME name (bytes in the tool result,
+ *  capped, an image as an image); when a proxy is present it overrides that entry in
+ *  `tools/list` with the to-disk form below. One name, the best shape the environment can
+ *  actually support — exactly as save_attachment_file works. */
+export const FETCH_TOOL_NAME = "get_attachment_file";
+/** Matches the server's blob ceiling (MAX_ENCRYPTED_BLOB_BYTES), so nothing storable is
+ *  un-readable. Checked against what the server SAYS the size is, and again against what it
+ *  actually sent — a length header is a claim, not a guarantee. */
+export const MAX_FETCH_BYTES = 50 * 1024 * 1024;
+/** Where downloads land, relative to the attach root. Inside the workspace on purpose: a
+ *  harness that sandboxes file reads to the project would not be able to open anything we
+ *  wrote to the OS temp dir, and a file the agent cannot read is the bug we are fixing. */
+export const DOWNLOAD_DIR_SEGMENTS = [".retasc", "attachments"];
+/** The directory the proxy owns for downloaded attachments. */
+export function downloadDir(root) {
+    return join(root, ...DOWNLOAD_DIR_SEGMENTS);
+}
+/**
+ * Reduce a server-supplied name to something safe to create INSIDE a directory we own.
+ *
+ * Every rule here is about a name we did not choose: the row's filename came from whoever
+ * uploaded it, or from an importer copying a third-party tracker's field verbatim.
+ *  - `basename` first, then a second sweep for separators — `../../.git/hooks/pre-commit` and
+ *    an absolute path both collapse to a leaf, and a Windows `..\\` does too.
+ *  - control characters and NUL, which truncate paths in some syscalls and lie in terminals.
+ *  - a leading dot, so nothing we write can become a dotfile (`.gitignore`, `.npmrc`, `.env`)
+ *    even inside our own directory.
+ *  - Windows device names (CON, NUL, COM1…), which are not openable as files there.
+ *  - length, so a long title can't push us past a filesystem limit and get truncated into a
+ *    name that collides with something else.
+ * Empty after all that (a name made entirely of stripped characters) falls back to the id,
+ * which is unique by construction.
+ */
+export function sanitizeDownloadName(name, attachmentId) {
+    const leaf = basename(String(name ?? "").replace(/[\\/]+/g, "/"));
+    let cleaned = leaf
+        .replace(/[\\/]/g, "_")
+        .replace(/[\u0000-\u001f\u007f]/g, "") // control characters and NUL, which lie in a terminal and truncate paths
+        .replace(/^\.+/, "") // no dotfiles, not even inside a directory we own
+        .trim()
+        .slice(0, 120);
+    if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(cleaned))
+        cleaned = `file-${cleaned}`;
+    return cleaned || `attachment-${attachmentId}`;
+}
+/**
+ * Where `attachmentId`'s bytes go. One directory per attachment (ids are unique and immutable,
+ * so two files never contend for a name and a cached file is never the wrong file), under the
+ * proxy-owned root. The id is validated rather than sanitized: it comes from the server, it is
+ * an opaque token, and anything that isn't one is a bug or an attack, not a name to clean up.
+ * The containment check at the end is belt-and-braces — after the id check and the name
+ * sanitizer there is no known way to escape, which is exactly when a cheap assertion earns its
+ * place.
+ */
+export function resolveDownloadTarget(root, attachmentId, filename) {
+    const id = String(attachmentId ?? "").trim();
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(id)) {
+        return { ok: false, error: `refusing to write: "${id}" is not a valid attachment id` };
+    }
+    const dir = join(downloadDir(root), id);
+    const name = sanitizeDownloadName(filename, id);
+    const path = join(dir, name);
+    if (path !== join(dir, basename(path)) || !path.startsWith(dir + sep)) {
+        return { ok: false, error: `refusing to write ${path}: it resolves outside ${dir}` };
+    }
+    return { ok: true, dir, path, filename: name };
+}
+/**
+ * The size of an already-downloaded file, or null if there isn't one. `lstat`, never `stat`:
+ * a symlink at this path would make `stat` report the target's size and the agent read
+ * whatever it points at, so a symlink counts as "not our file" and is reported as such.
+ *
+ * A file being present IS a complete download — writes go through a temp file and a rename
+ * below, so a crash mid-write can never leave a short file at the final path.
+ */
+export function existingDownload(path) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+    if (st.isSymbolicLink())
+        return { symlink: true };
+    if (!st.isFile())
+        return null;
+    return { size: st.size };
+}
+/**
+ * Write the downloaded bytes, atomically and without ever following a symlink.
+ *
+ * `wx` on the temp file so we only ever create, never clobber; `rename` to publish, which
+ * REPLACES a symlink sitting at the destination rather than writing through it (the one
+ * escape a plain write would allow). A leftover temp file from a killed proxy is removed
+ * first — it is inside a directory only this code writes to, and its name is ours.
+ */
+export function writeDownloadedFile(target, bytes, root) {
+    mkdirSync(target.dir, { recursive: true, mode: 0o700 });
+    ensureCacheIgnored(root);
+    const tmp = `${target.path}.part-${process.pid}`;
+    try {
+        unlinkSync(tmp);
+    }
+    catch {
+        /* nothing to clean up */
+    }
+    writeFileSync(tmp, bytes, { flag: "wx", mode: 0o600 });
+    renameSync(tmp, target.path);
+}
+/**
+ * Make the download directory ignore itself, once.
+ *
+ * A customer's certificate, production log or crash dump lands in their working tree, and the
+ * agent working there is about to commit something. A `.gitignore` holding `*` inside the
+ * directory covers everything in it (itself included) without touching the repo's own
+ * `.gitignore`, which is a file we have no business editing.
+ */
+export function ensureCacheIgnored(root) {
+    const dir = downloadDir(root);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(dir, ".gitignore"), "*\n", { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        /* already there (the common case), or unwritable — never fail a download over this */
+    }
+}
+/** The tool the proxy advertises in place of the server's inline variant. It names the
+ *  directory because the model has no other way to learn where the file will appear, and
+ *  says the bytes never enter the context so nobody "helpfully" asks for base64 instead. */
+export function localFetchToolDef(root) {
+    return {
+        name: FETCH_TOOL_NAME,
+        description: "Read a FILE attached to an issue, in ONE call. Give the attachment id (from " +
+            "list_attachments); your local retasc proxy downloads it with the credential it already " +
+            "holds and writes it to disk, then hands you the path — read it with your normal file " +
+            "tools. You do NOT need an API key for this and must not go looking for one, and you " +
+            "must not curl the download URL yourself: the whole point is that the key stays in the " +
+            `proxy. Files land under ${downloadDir(root)} (one folder per attachment, never ` +
+            "overwritten, git-ignored); copy it elsewhere yourself if you want it kept. Works at any " +
+            "size up to the 50MB attachment limit, and the bytes never pass through your context. " +
+            "For a link attachment (one saved with save_attachment) there is nothing to download — " +
+            "fetch its URL yourself.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                attachment: { type: "string", description: "Attachment id, e.g. from list_attachments." },
+            },
+            required: ["attachment"],
+        },
+    };
+}
+/**
+ * Put the local tool into a `tools/list` result: replace the server's entry of the same name
+ * (so the agent sees the shape this environment can actually serve, not the inline fallback)
+ * or append it when the server has none. Appending matters — the proxy needs only
+ * `get_attachment` to do its job, so it can offer to-disk downloads against a server deployed
+ * before the inline variant existed.
+ */
+export function mergeFetchTool(tools, root) {
+    if (!Array.isArray(tools))
+        return tools;
+    const local = localFetchToolDef(root);
+    const idx = tools.findIndex((t) => t && typeof t === "object" && t.name === FETCH_TOOL_NAME);
+    if (idx === -1)
+        return [...tools, local];
+    const merged = [...tools];
+    merged[idx] = local;
+    return merged;
+}
+/** Does this JSON-RPC message want a LOCAL download? Any call to the tool does: unlike the
+ *  upload pair there is no second argument shape to tell them apart, and when a proxy is
+ *  present writing to disk is always the better answer — it costs the agent no context and
+ *  has no size ceiling. */
+export function isLocalFetchCall(msg) {
+    const m = msg;
+    return !!m && m.method === "tools/call" && m.params?.name === FETCH_TOOL_NAME;
+}
+/** Turn a download HTTP failure into something the agent can act on — same contract as the
+ *  upload side: the status carries the meaning, and a bare "HTTP 402" tells an agent nothing
+ *  it can relay to the human who alone can fix it. */
+export function downloadFailureMessage(status, body) {
+    const detail = body.trim() ? ` — ${body.trim()}` : "";
+    switch (status) {
+        case 401:
+            return `download rejected: this proxy's key no longer authenticates${detail}`;
+        case 402:
+            return (`download refused for billing${detail}. PASS THIS TO YOUR HUMAN — you cannot fix it ` +
+                `yourself, only an owner can, and until they do every call will keep failing.`);
+        case 404:
+            return `download rejected: no such attachment in this project, or it has no stored file${detail}`;
+        default:
+            return `download failed with HTTP ${status}${detail}`;
+    }
+}

package/dist/lib/launcher.js

@@ -96,6 +96,25 @@ export function portableLauncher(r, version) {
 export function selfCommand(version, argv1 = process.argv[1] ?? "") {
     return /[\\/]_npx[\\/]/.test(argv1) ? `npx -y ${PKG}@${version}` : "retasc";
 }
+/**
+ * A one-line stamp of which build just spoke (RTSC-672).
+ *
+ * A failure report is only diagnosable if it says what produced it. After 1.26.0 fixed
+ * sign-in, a container kept printing the 1.25.0 message and the only way to learn why was
+ * a round trip asking someone to run `--version` — because nothing in the output said.
+ * Worse, the population most likely to re-run a command is the population that hit a bug
+ * and was told it is fixed, which is exactly the population liable to be holding a stale
+ * build. "It still doesn't work" and "you are running last week's CLI" look identical
+ * without this.
+ *
+ * The EXACT version, not `@latest`: this names the code that emitted the message, which
+ * is a different question from how to fetch the current one. `npx` in the prefix when
+ * that is how they started, so the line doubles as a runnable command.
+ */
+export function versionStamp(version, argv1 = process.argv[1] ?? "") {
+    const how = /[\\/]_npx[\\/]/.test(argv1) ? `npx ${PKG}@${version}` : `${PKG} ${version}`;
+    return `  (${how})`;
+}
 /** Install (or upgrade to) an exact version globally. Returns null on success. */
 function installGlobal(version) {
     // A cold global install takes seconds with no output of its own. Silence here reads as

package/dist/proxy.js

@@ -16,6 +16,7 @@ import { resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
 import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
 import { attachRoot, isLocalAttachCall, mergeAttachTool, resolveAttachPath, uploadFailureMessage, uploadUrlWith, } from "./lib/attachFile.js";
+import { MAX_FETCH_BYTES, downloadFailureMessage, existingDownload, isLocalFetchCall, mergeFetchTool, resolveDownloadTarget, writeDownloadedFile, } from "./lib/fetchFile.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
 // the direct commands (claim/tidy/done) can never diverge. The proxy carries its
 // binding in its own env (RETASC_MCP_KEY legacy, or RETASC_WORKSPACE → keystore).
@@ -260,6 +261,132 @@ async function handleLocalAttach(msg) {
         return replyToolResult(msg.id, `upload failed: ${String(e?.message ?? e)}`, true);
     }
 }
+/**
+ * Serve `get_attachment_file` LOCALLY (RTSC-681): the agent names an attachment id, we fetch
+ * the bytes with the key we already hold and write them to a file the agent can open. The
+ * mirror of handleLocalAttach above, and the other half of the same fix — attachments were a
+ * one-way street, and the way back required a credential the model is told it must not go
+ * looking for.
+ *
+ * The metadata comes from the server rather than being assumed here, for the same reason the
+ * upload asks for its URL: the auth check, the project boundary and "is there even a file"
+ * stay server-authoritative, so this side holds no policy it could get wrong. Only then do we
+ * spend a download.
+ *
+ * Every write is logged to stderr with its resolved path. A proxy-side write bypasses the
+ * harness's own file-write prompt, so the MCP log is where a human can see what appeared on
+ * their disk on their behalf.
+ */
+async function handleLocalFetch(msg) {
+    const args = (msg.params?.arguments ?? {});
+    const attachment = typeof args.attachment === "string" ? args.attachment.trim() : "";
+    if (!attachment) {
+        return replyToolResult(msg.id, "attachment is required (an attachment id from list_attachments)", true);
+    }
+    // Ask the server what this is. Doubles as the auth + existence + project-boundary check, so
+    // a bad id or a foreign project fails before we write anything.
+    let meta;
+    try {
+        meta = toolResult(await postRemote({
+            jsonrpc: "2.0",
+            id: hbSeq--,
+            method: "tools/call",
+            params: { name: "get_attachment", arguments: { attachment } },
+        }), "get_attachment");
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `could not reach Retasc: ${String(e?.message ?? e)}`, true);
+    }
+    const url = typeof meta?.url === "string" ? meta.url : "";
+    if (!url) {
+        // Relay what the server said rather than a generic failure: it is usually NOT_FOUND for
+        // this id, and that is the sentence the agent needs to see.
+        const detail = typeof meta === "string" ? meta : JSON.stringify(meta ?? null);
+        return replyToolResult(msg.id, `could not read attachment ${attachment}: ${detail}`, true);
+    }
+    // Whether there are bytes is the SERVER's answer, never inferred from the URL. An earlier
+    // draft fell back to matching the download path in the URL when `hasFile` was absent, which
+    // is a credential leak: a LINK attachment's URL is arbitrary text any org member can write,
+    // so `https://evil.example/attachments/download?x=1` would have matched and this fetch would
+    // have carried our Bearer token to their host. A server too old to answer gets an error that
+    // names the fix, which is the safe direction to fail.
+    if (meta.hasFile !== true) {
+        const why = meta.hasFile === false
+            ? `attachment ${attachment} is a link, not an uploaded file — there are no bytes to download. ` +
+                `Fetch it yourself if you can reach it: ${url}`
+            : `this Retasc deployment is too old to serve get_attachment_file (its get_attachment does ` +
+                `not report whether an attachment has a file). Ask your human to update the backend.`;
+        return replyToolResult(msg.id, why, true);
+    }
+    // Belt and braces on the URL the server handed back: only ever send the credential to the
+    // endpoint this feature is about, over http(s), never to a `file:`/`data:` scheme or some
+    // other path that a future server-side bug might emit here.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return replyToolResult(msg.id, `could not read attachment ${attachment}: the server returned an unusable URL`, true);
+    }
+    // `endsWith`, not `===`: a deployment whose site URL carries a path prefix serves the same
+    // endpoint under it, and rejecting that would break a legitimate install to catch nothing.
+    if (!/^https?:$/.test(parsed.protocol) || !parsed.pathname.endsWith("/attachments/download")) {
+        log(`refused download of ${attachment}: unexpected download URL ${parsed.origin}${parsed.pathname}`);
+        return replyToolResult(msg.id, `refusing to download ${attachment}: the server returned an unexpected download URL.`, true);
+    }
+    const declared = typeof meta.bytes === "number" ? meta.bytes : undefined;
+    if (declared !== undefined && declared > MAX_FETCH_BYTES) {
+        return replyToolResult(msg.id, `attachment ${attachment} is ${declared} bytes, over the ${MAX_FETCH_BYTES}-byte limit`, true);
+    }
+    const target = resolveDownloadTarget(ATTACH_ROOT, attachment, meta.filename ?? meta.title);
+    if (!target.ok) {
+        log(`refused download of ${attachment}: ${target.error}`);
+        return replyToolResult(msg.id, target.error, true);
+    }
+    const describe = (bytes, cached) => JSON.stringify({
+        attachment,
+        issue: meta.issue,
+        path: target.path,
+        filename: target.filename,
+        bytes,
+        contentType: meta.contentType,
+        obsolete: meta.obsolete ?? false,
+        cached,
+        note: "The file is on disk — read it with your normal file tools. Copy it elsewhere yourself if you want to keep it; this directory is git-ignored and is not cleaned up for you.",
+    }, null, 2);
+    // An attachment id maps to immutable bytes, so a file already sitting at this exact path IS
+    // this attachment — hand it back rather than paying for the same egress twice.
+    const existing = existingDownload(target.path);
+    if (existing && "symlink" in existing) {
+        const error = `refusing to use ${target.path}: it is a symlink, not a downloaded file. Remove it and try again.`;
+        log(error);
+        return replyToolResult(msg.id, error, true);
+    }
+    if (existing) {
+        log(`${attachment} already downloaded → ${target.path}`);
+        return replyToolResult(msg.id, describe(existing.size, true), false);
+    }
+    try {
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${activeKey}` } });
+        if (!res.ok) {
+            const body = await res.text();
+            log(`download of ${attachment} failed: HTTP ${res.status}`);
+            return replyToolResult(msg.id, downloadFailureMessage(res.status, body), true);
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        // The declared size was a claim; this is what actually arrived. Check it before it lands
+        // on disk — a response is not bounded by what the metadata said it would be.
+        if (bytes.byteLength > MAX_FETCH_BYTES) {
+            return replyToolResult(msg.id, `download aborted: ${bytes.byteLength} bytes exceeds the ${MAX_FETCH_BYTES}-byte limit`, true);
+        }
+        writeDownloadedFile(target, bytes, ATTACH_ROOT);
+        log(`downloaded ${attachment} (${bytes.byteLength} bytes) → ${target.path}`);
+        return replyToolResult(msg.id, describe(bytes.byteLength, false), false);
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `download failed: ${String(e?.message ?? e)}`, true);
+    }
+}
 async function handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -276,6 +403,11 @@ async function handleLine(line) {
     // tool called with `contentBase64`, the server's own variant) goes remote untouched.
     if (isLocalAttachCall(msg))
         return await handleLocalAttach(msg);
+    // RTSC-681: the read counterpart. Whenever a proxy is present, downloading to disk beats
+    // the server's inline variant on every axis (no size ceiling, no bytes in the model's
+    // context), so every call to the tool is served here rather than forwarded.
+    if (isLocalFetchCall(msg))
+        return await handleLocalFetch(msg);
     let resp;
     try {
         resp = await postRemote(msg);
@@ -296,8 +428,13 @@ async function handleLine(line) {
     // tell the agent which shape this environment can actually serve.
     if (msg.method === "tools/list" && resp && typeof resp === "object") {
         const result = resp.result;
-        if (result && Array.isArray(result.tools))
+        if (result && Array.isArray(result.tools)) {
             result.tools = mergeAttachTool(result.tools, ATTACH_ROOT);
+            // RTSC-681: same override for the read half — one name, the shape this environment can
+            // actually serve, decided at the only moment we get to tell the agent (tools/list is
+            // fetched once, at startup).
+            result.tools = mergeFetchTool(result.tools, ATTACH_ROOT);
+        }
     }
     // Watch tools/call traffic for claims/releases (request args + result), and
     // flag the workspace-key fallback on whoami so the AGENT sees the degraded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Retasc CLI \u2014 the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {