@retasc/cli 1.39.1 → 1.39.4

package/CHANGELOG.md

@@ -6,6 +6,74 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.39.4 (2026-09-03)
+
+- **RTSC-810** — `retasc unbind` revokes the key it says it revokes. It had two faults in
+  one lookup, and each on its own was enough to leave the credential live: it destructured
+  `{ keys }` off `listKeys`, which returns a bare array, and it derived the folder's key
+  prefix with a 12-character slice while the server stores 14. An exact compare between a
+  12-character string and a 14-character one is never true, so every run since `unbind`
+  shipped (RTSC-721) printed "not found server-side (already revoked, or the org is
+  gone)" and moved on. The length now mirrors the server's own `displayPrefixOf`, and the
+  test reads that file, so the two cannot drift apart again. A session child key can no
+  longer be the one revoked either: those are minted in memory by the proxy and never
+  reach the keystore, so a match on one would mean revoking a key this folder does not own.
+- **RTSC-810** — `retasc bind --org-id X --project-id Y` learns the project's prefix. The
+  provisioning form skipped every branch that looks a project up, so nothing knew the
+  prefix: the key went out nameless, the keystore entry was written without `prefix` or
+  `orgName`, and the receipt card printed an empty one. It now resolves the project the
+  same way the interactive pickers do.
+- **RTSC-810** — a key is named after the folder it was bound in, not after the project.
+  The Keys list is the folder map (`client-a` → `ENG`), which is what tells you which
+  machine a credential belongs to; `ENG key` on every row told nobody anything. Naming is
+  the server's job now, so no door can store a nameless key: the Dash mint form with the
+  name left blank and `retasc key mint` without `--name` both fall back to the project's
+  own name rather than leaving the Dash to print "Unnamed key".
+
+## 1.39.3 (2026-09-02)
+
+- **RTSC-801** — (security) `save_attachment_file` no longer reads a workspace's own secrets,
+  and no longer follows a file swapped in after it was checked. The proxy reads attachments
+  on the agent's behalf, which is what keeps the API key away from the model, and the cost of
+  that is a read the harness never prompts on: whatever this path allows, an agent can upload
+  to an issue every org member can read. Containment to the attach root was doing all the work
+  and it was never the boundary it looked like, because the files worth stealing are not
+  outside a workspace, they are in it. `.env.local`, a legacy inline-key `.mcp.json` and
+  `.retasc/` all live inside a normal root, so a prompt-injected "attach the config" was
+  confined to exactly the secrets. Anything hidden below the root is now refused, dotfiles and
+  dot-directories alike, along with `secrets.md` and, wherever `RETASC_DIR` puts it, the
+  keystore itself. A root that contains your home directory (`~` or `/`, both previously
+  accepted) is refused outright rather than carved down, since it makes every credential on
+  the machine attachable, including every other workspace's key. Those rules all judge a name,
+  so a file with more than one hard link is refused too: path resolution follows symlinks but
+  not links, and `ln .env.local notes.txt` would otherwise hand the check a name it has no
+  reason to refuse while the bytes stay the same. The one carve-out is `.retasc/attachments/`,
+  which is where the proxy writes files fetched by `get_attachment_file`: refusing that would
+  be the proxy declining to read a file the proxy itself wrote, and downloading from one issue
+  to attach to another is a real thing agents do. Anything hidden deeper inside it is still
+  refused.
+  The second half is a race: the path was resolved and stat'd, a full
+  `prepare_attachment_upload` round trip went to the server, and only then was the file opened
+  by path, so a `ln -sf` in that window was followed on the read. The read now opens the file
+  `O_NOFOLLOW` and non-blocking, and proceeds only if the descriptor's device, inode and size
+  are the ones that passed the check. Opening non-blocking is not a detail: a `mkfifo` in that
+  same window would otherwise have blocked the proxy's event loop outright, stopping every
+  heartbeat it owes and stranding every lease it holds.
+  Legitimate attachments, screenshots, logs and documents, are unaffected: none of them are
+  hidden files.
+
+## 1.39.2 (2026-09-02)
+
+- **RTSC-808** — `retasc setup` no longer writes OpenCode's config into your real home when
+  `RETASC_HOME` says otherwise. That variable exists so anything exercising the harness module
+  cannot reconfigure the machine it runs on, and every other harness honours it; OpenCode read
+  `XDG_CONFIG_HOME` first and so ignored the override wherever that variable is set. The
+  precedence is now override, then environment, then default, and `XDG_CONFIG_HOME` is still
+  honoured when no override is in play, because OpenCode really does read it.
+  This is also why CI had been red on `main` for five consecutive merges. macOS does not set
+  `XDG_CONFIG_HOME` and GitHub's Linux runners do, so the test guarding this passed on every
+  developer machine and failed on every CI run, and no PR in the repo could show a green build.
+
 ## 1.39.1 (2026-09-02)
 
 - **RTSC-800** — (security) a keystore-resolved key now travels only to the keystore's own

package/dist/commands/bind.js

@@ -455,6 +455,20 @@ export async function completeWorkspaceSetup(args) {
             throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
         }
     }
+    // RTSC-810 — a `--project-id` skipped every branch above, so nothing here knew the
+    // project's prefix: the key went out nameless (`keyName` was built from `prefix`), the
+    // keystore entry was written without `prefix`/`orgName`, and the receipt card printed
+    // an empty one. The provisioning form is documented and supported, so it fills the
+    // gap the way the pickers do: one list call. Best-effort on the match — a scoped
+    // member may hold an id the list does not show, and that folder still has to bind.
+    if (projectId && !prefix) {
+        const { projects } = (await api.listProjects({ orgId }));
+        const hit = (projects ?? []).find((p) => p.id === projectId);
+        if (hit) {
+            prefix = hit.prefix;
+            emptyProject = projectIsEmpty(hit);
+        }
+    }
     // --- make `retasc` durable BEFORE anything is committed (RTSC-493) ---------
     // The marker names a command something else spawns on every agent start, so it has to
     // name one proved to run on this machine. Resolved (and announced) here so the install
@@ -501,7 +515,12 @@ export async function completeWorkspaceSetup(args) {
             projectId: projectId,
             agentName: opts.agent,
             runtime: opts.runtime ?? "claude-code",
-            keyName: prefix ? `${prefix} key` : undefined,
+            // RTSC-810 — named after the FOLDER, the leaf only, exactly as the setup-token
+            // door has done since RTSC-532: the Keys list is the folder map (`client-a →
+            // ENG`), and the old prefix-plus-"key" name told nobody which folder held it.
+            // The server cleans the name and falls back to the project's own when the
+            // leaf is empty.
+            keyName: basename(cwd),
         }));
     // The key is named in the receipt card below, not here — one mention, in the place
     // that says where it went (RTSC-673).

package/dist/commands/unbind.js

@@ -27,6 +27,35 @@ import { removeProjectMarker, tryClaudeCliRemove } from "./mcp.js";
  *   • **The session is left alone.** Signing out is `logout`'s job; conflating the two
  *     turns "detach this folder" into "log me out everywhere", which nobody asked.
  */
+/**
+ * The prefix the SERVER stored for a raw key — `displayPrefixOf` in `convex/lib/keys.ts`,
+ * mirrored here because the CLI cannot import backend code.
+ *
+ * RTSC-810: this length is the join `unbind` revokes on, and it was wrong. The local side
+ * sliced 12 while the server stores 14, so the exact compare was never true once, and
+ * `unbind` reported "not found server-side" on every run while leaving the key LIVE —
+ * the same outcome as the `{ keys }` destructure below, from the other half of the same
+ * lookup. A change to the server's slice has to change this one; `unbindRevoke810.test.mjs`
+ * reads `convex/lib/keys.ts` and fails if the two ever disagree again.
+ */
+export const DISPLAY_PREFIX_LEN = 14;
+export function displayPrefixOf(key) {
+    return key.slice(0, DISPLAY_PREFIX_LEN);
+}
+/**
+ * This folder's live key among the org's, by display prefix — the join `unbind` revokes
+ * on. Takes the ARRAY `listKeys` returns; anything else is "nothing to revoke", never a
+ * throw, because the caller's fallback is to name the Dash rather than to fail.
+ *
+ * WORKSPACE keys only: a session child (`parentKeyId` set) is minted in memory by the
+ * proxy and never reaches the keystore, so one matching here would mean revoking a key
+ * this folder does not own.
+ */
+export function liveKeyFor(keys, prefix) {
+    if (!Array.isArray(keys) || !prefix)
+        return undefined;
+    return keys.find((k) => k?.displayPrefix === prefix && !k.revokedAt && !k.parentKeyId && typeof k.id === "string");
+}
 export async function unbindAction(opts) {
     const cwd = process.cwd();
     const existing = readLocalBinding(cwd);
@@ -35,7 +64,7 @@ export async function unbindAction(opts) {
         return;
     }
     const entry = existing.workspaceId ? getBinding(existing.workspaceId) : undefined;
-    const keyPrefix = (entry?.key ?? existing.key ?? "").slice(0, 12);
+    const keyPrefix = displayPrefixOf(entry?.key ?? existing.key ?? "");
     console.log(`This will disconnect ${cwd} from Retasc:`);
     if (entry?.orgName || entry?.prefix) {
         console.log(`  bound to: ${entry.orgName ?? entry.orgId} / ${entry.prefix ?? entry.projectId}`);
@@ -58,14 +87,18 @@ export async function unbindAction(opts) {
         return;
     }
     // Revoke FIRST, while the keystore still holds what identifies the key. displayPrefix
-    // is how the server names keys (the raw value is never stored there), so the first 12
-    // chars of ours is the join.
+    // is how the server names keys (the raw value is never stored there), so the first
+    // DISPLAY_PREFIX_LEN chars of ours is the join — the server's own slice, not a shorter
+    // guess at it (RTSC-810).
     if (entry?.orgId && keyPrefix && isLoggedIn()) {
         try {
-            const { keys } = (await api.listKeys({ orgId: entry.orgId }));
-            const mine = (keys ?? []).find((k) => k.displayPrefix === keyPrefix && !k.revokedAt);
+            // RTSC-810 — `listKeys` returns a bare ARRAY (as `retasc key list` has always
+            // read it). This destructured `{ keys }` off it, got `undefined`, and so every
+            // unbind since RTSC-721 printed "not found server-side" and left the key LIVE —
+            // the exact half of hand-editing the command exists to stop.
+            const mine = liveKeyFor(await api.listKeys({ orgId: entry.orgId }), keyPrefix);
             if (mine) {
-                await api.revokeKey({ keyId: mine.id ?? mine._id });
+                await api.revokeKey({ keyId: mine.id });
                 console.log(`✓ Revoked key ${keyPrefix}… server-side.`);
             }
             else {

package/dist/lib/attachFile.js

@@ -20,8 +20,11 @@
 // would otherwise be a clean exfiltration primitive. The confinement below IS the security
 // boundary, not hygiene — keep it strict, and keep it here where it is unit-tested, rather
 // than inline in the proxy's I/O path.
-import { realpathSync, statSync } from "node:fs";
-import { basename, resolve, sep } from "node:path";
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
+import { keystorePath } from "./keystore.js";
+import { DOWNLOAD_DIR_SEGMENTS } from "./fetchFile.js";
 /** The one tool name for "attach a file", whichever transport can carry the bytes. The
  *  server publishes a base64 variant under this SAME name for clients with no proxy; when a
  *  proxy is present it overrides the entry in `tools/list` with the path form below. One
@@ -34,6 +37,12 @@ export const MAX_ATTACH_BYTES = 50 * 1024 * 1024;
 /** Env var that widens the root a path may live under. Set it deliberately (a worktree
  *  layout, a screenshots dir); unset, the root is the proxy's cwd. */
 export const ATTACH_ROOT_ENV = "RETASC_ATTACH_ROOT";
+/** Files inside the root that carry credentials under a NON-dot name, so the dot rule below
+ *  doesn't catch them. Deliberately short: a name denylist is the weakest of the three rules
+ *  here (rename the file and it stops applying), and it exists only for the two names this
+ *  repo's own conventions put in a workspace. The load-bearing rules are the dot rule, the
+ *  keystore rule and the home-root refusal — those hold regardless of naming. */
+export const DENIED_ATTACH_NAMES = new Set(["secrets.md", "secrets.txt"]);
 /**
  * The directory a file must live under to be attachable. `RETASC_ATTACH_ROOT` if set (a
  * human's deliberate choice — the fleet case is real: agents work in sibling worktrees, so
@@ -52,15 +61,93 @@ export function attachRoot(env, cwd) {
         return resolve(raw); // non-existent root: nothing will resolve inside it anyway
     }
 }
+/** Resolve a path without caring whether it exists yet: `realpathSync` if we can, the plain
+ *  resolution otherwise. Used for the fixed paths we compare AGAINST (home, the keystore), so
+ *  a machine where the keystore hasn't been created yet still gets the rule. */
+function realOrResolved(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/** One message for both places the link count is checked, so the resolution-time refusal and
+ *  the read-time one read identically to whoever sees them. */
+function hardLinkError(path, links) {
+    return (`refusing to read ${path}: it has ${links} hard links, so this name may be an alias for a ` +
+        `file the rules above would refuse (a hard link is invisible to path resolution). Copy it ` +
+        `to a new file and attach the copy.`);
+}
+/** macOS and Windows compare filenames case-insensitively, and `realpathSync` does NOT correct
+ *  the case there — it hands back whatever case was asked for. So a purely case-sensitive
+ *  compare lets `/users/<name>` past a rule written against `/Users/<name>` while the kernel
+ *  happily opens the same directory. Fold on those platforms only; on Linux the case IS the
+ *  identity and folding would wrongly conflate two real directories. */
+const CASE_BLIND = process.platform === "darwin" || process.platform === "win32";
+function samePath(a, b) {
+    return CASE_BLIND ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+/** Is `inner` `outer`, or inside it? Both must already be resolved. */
+function isWithin(inner, outer) {
+    if (samePath(inner, outer))
+        return true;
+    const prefix = outer.endsWith(sep) ? outer : outer + sep;
+    return samePath(inner.slice(0, prefix.length), prefix);
+}
+/**
+ * Does this root swallow the home directory? A root of `~` or `/` does, and both used to be
+ * accepted — which put `~/.retasc/bindings.json` (every org's workspace key, for EVERY
+ * workspace on this machine, not just this one) inside the attachable set. There is no
+ * legitimate attachment that needs a root that wide, and the failure mode if we allowed one
+ * is the worst this module has, so it is refused outright rather than carved down with
+ * exceptions. A root BELOW home (`~/projects/foo`) is the normal case and stays fine.
+ *
+ * An unusable `homedir()` disables the rule rather than widening it. Containers, launchd and
+ * systemd units run with HOME cleared, where `homedir()` can be "" — and "" resolves to the
+ * process's cwd, which is the DEFAULT root, so folding it in would refuse every attachment on
+ * exactly the machines least able to debug it. With no home directory there is also no
+ * `~/.retasc` for the rule to be protecting.
+ */
+export function rootSwallowsHome(root) {
+    const home = homedir();
+    if (!home || !isAbsolute(home))
+        return false;
+    return isWithin(realOrResolved(home), root);
+}
 /**
  * Resolve a caller-supplied path against `root` and decide whether we are willing to read it.
  *
  * Refusals, and what each one is actually for:
+ *  - a root that contains the home directory — see `rootSwallowsHome`. Checked first because
+ *    it condemns every path, and the human needs to see WHY rather than a per-file refusal.
  *  - outside `root` — the containment rule. Compared AFTER `realpathSync` on both sides, so a
  *    symlink inside the root pointing at `~/.ssh/id_rsa` is caught: resolving only the
  *    requested path (or neither) is the classic way this check is defeated.
  *  - anything under a `.git` directory — inside the root by construction, and `.git/config`
  *    routinely holds credentials in remote URLs. No legitimate attachment lives there.
+ *  - any OTHER dotfile or dot-directory below the root (RTSC-801). Containment alone was never
+ *    the whole boundary: the files worth stealing are not outside the workspace, they are in
+ *    it. `.env.local`, a legacy inline-key `.mcp.json` and `.retasc/` all sit inside a normal
+ *    root, so "confined to the project" was confining an attacker to exactly the secrets. A
+ *    dot prefix is the one convention every one of them shares, and attachments are
+ *    screenshots, logs and documents — none of which are dotfiles — so the rule costs nothing
+ *    real and does not have to be kept in step with a list of names. The ONE carve-out is
+ *    `.retasc/attachments/`, which is where this same proxy writes downloads: refusing it would
+ *    mean the proxy declining to read a file the proxy just wrote, and "download from one
+ *    issue, attach to another" is a real thing agents do. The carve-out steps over exactly
+ *    those two segments; anything hidden deeper inside is refused normally.
+ *  - `secrets.md` and friends — the same class under a name the dot rule can't see.
+ *  - the keystore file, and anything sitting beside it — the dot rule already covers the
+ *    default `~/.retasc/`, but `RETASC_DIR` can move it somewhere undotted, and a root INSIDE
+ *    that directory would put it above the dot check entirely. Direct children only, not the
+ *    subtree, so the default layout's `.retasc/attachments/` stays readable.
+ *  - a file with more than one hard link — the rules above judge a NAME, and a hard link gives
+ *    one inode a second name. `realpathSync` resolves symlinks but not links, so `ln .env.local
+ *    notes.txt` inside the root hands the dot rule a name it has no reason to refuse and the
+ *    read follows to the same bytes. Link count is the property that survives renaming, so it
+ *    is what gets checked. Real attachments (a screenshot, a log, a build output) have one
+ *    link; the fix for the rare tool that hard-links its output is to copy the file.
  *  - not a regular file — a directory, fifo or device isn't an attachment, and reading a fifo
  *    would hang the proxy's stdio loop rather than fail.
  *  - empty / oversized — the server rejects both; failing here costs one round trip less and
@@ -68,6 +155,10 @@ export function attachRoot(env, cwd) {
  *
  * A `~` is deliberately NOT expanded: the home directory is precisely what the root confines
  * away from, so silently reaching it would undo the boundary.
+ *
+ * What this function decides is only half the guarantee — see `readAttachFile`, which is what
+ * actually opens the bytes, because a decision made about a path is not a decision about the
+ * file that path names a network round trip later.
  */
 export function resolveAttachPath(input, root) {
     const requested = typeof input === "string" ? input.trim() : "";
@@ -80,6 +171,14 @@ export function resolveAttachPath(input, root) {
                 `under ${root}; give a path inside it (relative paths resolve against it).`,
         };
     }
+    if (rootSwallowsHome(root)) {
+        return {
+            ok: false,
+            error: `refusing to attach anything: the attach root ${root} contains your home directory, ` +
+                `which would make every credential on this machine attachable. Set ${ATTACH_ROOT_ENV} ` +
+                `to the project directory you actually work in.`,
+        };
+    }
     const candidate = resolve(root, requested);
     let real;
     try {
@@ -92,22 +191,64 @@ export function resolveAttachPath(input, root) {
     // "/" would refuse everything instead of allowing everything. Fail-closed is the right
     // direction, but silently, and only for that one root; normalize instead.
     const prefix = root.endsWith(sep) ? root : root + sep;
-    if (real !== root && !real.startsWith(prefix)) {
+    if (!isWithin(real, root)) {
         return {
             ok: false,
             error: `refusing to read ${real}: it resolves outside ${root}. Only files under that root can ` +
                 `be attached (set ${ATTACH_ROOT_ENV} to widen it deliberately).`,
         };
     }
-    if (real.split(sep).includes(".git")) {
+    // Only the segments BELOW the root: the root itself is the human's deliberate choice and may
+    // legitimately be a dotted path, so judging it here would refuse everything under it.
+    let below = real.slice(prefix.length).split(sep).filter(Boolean);
+    // `.retasc/attachments/` is the directory THIS proxy writes downloads into, so a blanket dot
+    // rule would make "download the design from RTSC-1, attach it to RTSC-2" impossible — the
+    // proxy refusing to read a file the proxy just wrote. Step over those two segments and judge
+    // the rest normally, so a hand-placed `.env` deeper inside is still refused.
+    if (below.length > DOWNLOAD_DIR_SEGMENTS.length && DOWNLOAD_DIR_SEGMENTS.every((seg, i) => below[i] === seg)) {
+        below = below.slice(DOWNLOAD_DIR_SEGMENTS.length);
+    }
+    if (below.includes(".git")) {
         return { ok: false, error: `refusing to read ${real}: paths inside a .git directory are not attachable.` };
     }
+    const dotted = below.find((seg) => seg.startsWith("."));
+    if (dotted) {
+        return {
+            ok: false,
+            error: `refusing to read ${real}: "${dotted}" is hidden, and hidden files and directories are ` +
+                `not attachable. Attach a file that isn't hidden.`,
+        };
+    }
+    // Trailing dots and spaces are stripped by Win32 before the filesystem sees a name, so
+    // `secrets.md.` and `secrets.md ` open the same file while a literal compare misses both.
+    const leaf = (below[below.length - 1] ?? "").replace(/[. ]+$/, "");
+    if (DENIED_ATTACH_NAMES.has(leaf.toLowerCase())) {
+        return { ok: false, error: `refusing to read ${real}: that file is not attachable.` };
+    }
+    // The keystore file itself, and anything sitting beside it in the directory it lives in —
+    // `RETASC_DIR` names a credential directory, not just one file. Direct children only: a
+    // subtree ban would swallow `.retasc/attachments/` on the default layout, which the carve-out
+    // above exists to keep readable.
+    const keystore = realOrResolved(keystorePath());
+    if (samePath(real, keystore) || samePath(dirname(real), realOrResolved(dirname(keystorePath())))) {
+        return {
+            ok: false,
+            error: `refusing to read ${real}: it is in the directory retasc keeps credentials in ` +
+                `(RETASC_DIR). Nothing there is attachable.`,
+        };
+    }
     let size;
+    let dev;
+    let ino;
     try {
         const st = statSync(real);
         if (!st.isFile())
             return { ok: false, error: `not a regular file: ${real}` };
+        if (st.nlink > 1)
+            return { ok: false, error: hardLinkError(real, st.nlink) };
         size = st.size;
+        dev = st.dev;
+        ino = st.ino;
     }
     catch {
         return { ok: false, error: `cannot stat ${real}` };
@@ -122,7 +263,90 @@ export function resolveAttachPath(input, root) {
     }
     // The display name comes from what the caller ASKED for, not from the resolved target: a
     // symlink's own name is the one the human recognizes, and it only ever becomes a label.
-    return { ok: true, path: real, filename: basename(candidate), size };
+    return { ok: true, path: real, filename: basename(candidate), size, dev, ino };
+}
+/**
+ * Read the bytes we agreed to read — and prove they are the SAME bytes (RTSC-801).
+ *
+ * `resolveAttachPath` runs, then the proxy spends a full network round trip on
+ * `prepare_attachment_upload`, and only then does the file get opened. Reading by path at that
+ * point re-does the lookup against whatever the filesystem holds NOW, which is a window an
+ * agent's own shell can drive: a background `ln -sf` loop swaps the approved file for a link
+ * to `~/.ssh/id_rsa` and the read follows it, having passed every check above.
+ *
+ * Three things close it. `O_NOFOLLOW` refuses a symlink as the final component outright.
+ * `O_NONBLOCK` keeps a fifo swapped into the window from blocking the whole event loop rather
+ * than being refused. And the dev/ino/size comparison covers the rest — an intermediate
+ * directory swapped for another one, or the file replaced by a different regular file —
+ * because it asks the question that actually matters: is the fd I am holding open on the file
+ * I checked? A path can be re-pointed; an open descriptor cannot. Everything after the open
+ * reads from the fd, never from the path.
+ *
+ * What that does NOT cover, stated plainly rather than implied away: a rewrite in place, through
+ * the same inode, that lands on exactly the same byte count. Nothing short of hashing the
+ * content twice would catch it, and hashing is itself racy and costs a second full read of up
+ * to 50MB. It is also the weakest of these attacks by some distance — it needs write access to
+ * the file the human already approved AND the secret bytes already in hand, which is an
+ * attacker who could simply have named the secret in the first place.
+ */
+export function readAttachFile(resolved) {
+    // O_NOFOLLOW is POSIX; on a platform without it we lean on the dev/ino check below.
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    // O_NONBLOCK matters more than it looks. `openSync` on a FIFO with no writer BLOCKS, and it
+    // blocks the whole process — not a request, the event loop, so heartbeats stop and every
+    // lease this proxy holds goes stale. `resolveAttachPath` rejects a fifo, but a `mkfifo` in
+    // the same window this function exists for is never seen by that check, which would turn a
+    // refusal into a frozen proxy. Opening non-blocking returns immediately and lets the
+    // `isFile` check below refuse it like any other non-file. Harmless on a regular file.
+    const nonBlock = typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0;
+    let fd;
+    try {
+        fd = openSync(resolved.path, constants.O_RDONLY | noFollow | nonBlock);
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code === "ELOOP" || code === "EMLINK") {
+            return { ok: false, error: `refusing to read ${resolved.path}: it became a symlink after it was checked.` };
+        }
+        return { ok: false, error: `cannot open ${resolved.path}: ${String(e?.message ?? e)}` };
+    }
+    try {
+        const st = fstatSync(fd);
+        // Identity AND size: dev/ino prove the same inode, the size proves it was not rewritten in
+        // place through the same inode (`open(path, "r+")` changes neither dev nor ino nor link
+        // count). Together they are what "the file that was checked" can honestly mean here.
+        if (!st.isFile() || st.dev !== resolved.dev || st.ino !== resolved.ino || st.size !== resolved.size) {
+            return { ok: false, error: `refusing to read ${resolved.path}: the file changed after it was checked.` };
+        }
+        // With no O_NOFOLLOW and no usable inode number there is nothing left proving this
+        // descriptor is the file that passed the checks, so refuse rather than pretend. Real on
+        // SMB, FAT/exFAT and some FUSE mounts, where `ino` is 0 or not stable.
+        if (noFollow === 0 && st.ino === 0) {
+            return {
+                ok: false,
+                error: `refusing to read ${resolved.path}: this filesystem reports no stable file id and the ` +
+                    `platform cannot refuse symlinks on open, so the file cannot be proven unchanged.`,
+            };
+        }
+        // Re-checked on the fd, not just at resolution: a link can be added inside the same window
+        // the dev/ino check exists for, and adding one does not change the inode.
+        if (st.nlink > 1)
+            return { ok: false, error: hardLinkError(resolved.path, st.nlink) };
+        // No separate empty/oversize re-check: resolveAttachPath already refused both, and any size
+        // that could newly violate either is a size that differs from the one just compared.
+        return { ok: true, bytes: readFileSync(fd) };
+    }
+    catch (e) {
+        return { ok: false, error: `cannot read ${resolved.path}: ${String(e?.message ?? e)}` };
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* already gone */
+        }
+    }
 }
 /** The tool the proxy advertises in place of (or in addition to) the server's base64 variant.
  *  It names the root in the description because the model has no other way to learn where it
@@ -134,8 +358,9 @@ export function localAttachToolDef(root) {
             "proxy reads the bytes and uploads them with the credential it already holds. You do NOT " +
             "need an API key for this and must not go looking for one — the whole point is that the " +
             `key stays in the proxy. Readable paths are confined to ${root} (relative paths resolve ` +
-            "against it, symlinks out of it are refused, as is anything under .git). For a plain URL " +
-            "rather than a file, use save_attachment instead.",
+            "against it, symlinks out of it are refused, and so is any hidden file or directory, any " +
+            "hard-linked file, and anything retasc keeps credentials in). For a plain URL rather than " +
+            "a file, use save_attachment instead.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/lib/harness.js

@@ -460,9 +460,18 @@ function addCommandHarness(opts) {
     };
 }
 /** `~/.config/opencode/`, XDG-aware — OpenCode honours XDG_CONFIG_HOME, so resolving it
- *  to `~/.config` unconditionally would name the wrong file in the receipt. */
+ *  to `~/.config` unconditionally would name the wrong file in the receipt.
+ *
+ *  `RETASC_HOME` outranks XDG_CONFIG_HOME, which is the whole point of the override and the
+ *  one thing this function used to get wrong: reading the environment first meant the escape
+ *  hatch was ignored on every machine that sets XDG_CONFIG_HOME, so a test run wrote into the
+ *  developer's REAL `~/.config/opencode/` — the exact accident `home()` exists to prevent, and
+ *  invisible on macOS, which does not set the variable. Take the override first, then the
+ *  environment, then the default. */
 function opencodeConfig() {
-    const xdg = process.env.XDG_CONFIG_HOME || join(home(), ".config");
+    const xdg = process.env.RETASC_HOME
+        ? join(home(), ".config")
+        : process.env.XDG_CONFIG_HOME || join(home(), ".config");
     return join(xdg, "opencode", "opencode.jsonc");
 }
 /**

package/dist/proxy.js

@@ -6,7 +6,6 @@
 // reclaims the lease (the correct default) — a broken watchdog is never worse than
 // no watchdog. Self-enforcing: no proxy → no Retasc tools → can't orphan a lease.
 import { createInterface } from "node:readline";
-import { readFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
@@ -15,7 +14,7 @@ import { applyObservation, heartbeatRequest, isClaimLost, isUnauthorized, should
 import { AUTO_WORKSPACE, 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 { attachRoot, isLocalAttachCall, mergeAttachTool, readAttachFile, 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
@@ -255,7 +254,16 @@ async function handleLocalAttach(msg) {
         return replyToolResult(msg.id, `could not prepare an upload for ${issue}: ${detail}`, true);
     }
     const title = typeof args.title === "string" ? args.title : undefined;
-    log(`attaching ${resolved.path} (${resolved.size} bytes) to ${issue}`);
+    // Open AFTER the round trip, and re-prove the inode: the path was resolved before we went to
+    // the network, and reading it by path again here would follow whatever it points at now
+    // (RTSC-801). `readAttachFile` opens O_NOFOLLOW and reads from the descriptor.
+    const read = readAttachFile(resolved);
+    if (!read.ok) {
+        log(`refused attachment for ${issue}: ${read.error}`);
+        return replyToolResult(msg.id, read.error, true);
+    }
+    const bytes = read.bytes;
+    log(`attaching ${resolved.path} (${bytes.length} bytes) to ${issue}`);
     try {
         const res = await fetch(uploadUrlWith(uploadUrl, resolved.filename, title), {
             method: "POST",
@@ -263,7 +271,7 @@ async function handleLocalAttach(msg) {
             // is better than anything guessed here — declaring octet-stream would REPLACE it and
             // cost the attachment its inline preview.
             headers: { Authorization: `Bearer ${activeKey}` },
-            body: await readFile(resolved.path),
+            body: bytes,
         });
         const body = await res.text();
         if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.39.1",
+  "version": "1.39.4",
   "description": "Retasc CLI — 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": {