@retasc/cli 1.21.1 → 1.23.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.23.0 (2026-08-17)
+
+- **RTSC-660** — the proxy attaches files for you. Attaching a file was the one Retasc write
+  an agent could not finish on its own: the server handed back an upload URL and told the
+  caller to POST the bytes with "your API key", which under MCP lives in the proxy, not in
+  the model. Agents were resorting to reading the key out of `~/.retasc/bindings.json`, and
+  harnesses were blocking that as credential harvesting. The proxy now serves
+  `save_attachment_file(issue, path, title?)` itself: it reads the file and uploads it with
+  the key it already holds, so nothing about the credential reaches the model and the bytes
+  never pass through its context. Readable paths are confined to a root — `RETASC_ATTACH_ROOT`
+  if set, otherwise the proxy's working directory — compared after resolving symlinks on both
+  sides, with `.git` and non-regular files refused, because reading a file on the agent's
+  behalf skips the harness's own file-access prompt. Every accepted read is logged to stderr
+  with its resolved path. Calls that pass `contentBase64` instead are forwarded to the server
+  untouched.
+
+## 1.22.0 (2026-08-12)
+
+- **RTSC-646** — the watchdog now says when it is **not** renewing a lease. Its lease set is
+  in-memory and built only from claim traffic this proxy saw, so a claim made in another
+  terminal, over direct HTTP MCP, or by a previous proxy before a harness restart was renewed
+  by nobody — silently, until the reclaimer took the issue away mid-build. Touching such a
+  lease now prints a warning naming the issue and what to do about it (`release_issue` is
+  exempt: it ends a lease rather than needing one). A heartbeat rejected as `UNAUTHORIZED` is
+  also called out loudly, once: that means the session's **credential** died, not the lease,
+  so every claim stops renewing at the same moment and each lapses at its own expiry. The
+  proxy keeps tracking and keeps trying, because re-minting the key inside the TTL recovers
+  all of them. The `mcp install --watchdog` text no longer stops at "no per-claim
+  heartbeats" — it names both bounds: the proxy must be running, and it only renews claims
+  it saw this session make.
+
 ## 1.21.1 (2026-08-10)
 
 - **RTSC-643** — `retasc gate install` keys the gate to **this folder's** project, not the

package/dist/commands/mcp.js

@@ -186,7 +186,12 @@ export function installMcp(opts) {
         }
         console.log("\nWatchdog MCP config (Codex / OpenCode / any stdio MCP client):\n");
         console.log(mcpProxyConfigBlock(opts.url, opts.key, resolved.launcher));
-        console.log("\nThe watchdog keeps your claims alive automatically — no per-claim heartbeats. If it ever isn't running you just fall back to the normal lease timeout (safe).");
+        // RTSC-646: the old text stopped at "no per-claim heartbeats", which reads as
+        // "a claim never lapses while I'm working". It renews the claims THIS proxy saw
+        // you make, for as long as it is running — so name both bounds here, or the
+        // first surprise is the reclaimer taking an issue mid-build.
+        console.log("\nThe watchdog keeps claims alive automatically — it renews every claim it saw this session make, about every 10 minutes, so your agent needs no per-claim heartbeats. Long builds and test runs do NOT free a claim by themselves.");
+        console.log("Two things it does not cover, both safe (they fall back to the normal 30-minute lease timeout): if the proxy stops, renewal stops; and a claim made elsewhere — another terminal, direct HTTP MCP, or a previous proxy before a restart — is renewed by nobody. Heartbeat or checkpoint those yourself.");
         return;
     }
     const res = tryClaudeCli(opts.url, opts.key, scope);

package/dist/lib/attachFile.js

@@ -0,0 +1,207 @@
+// Local file attachment for the MCP proxy (RTSC-660) — path resolution + the tool it advertises.
+//
+// Why this exists: every other Retasc write is ONE MCP tool call, because the credential
+// lives in the server and the model only names a tool. File upload was the exception.
+// `prepare_attachment_upload` handed back a URL and told the caller to Bearer it with "your
+// API key", which under MCP the model structurally does not have. What that produced in the
+// field (the customer report behind RTSC-660): the agent shelled out to read
+// `~/.retasc/bindings.json`, and its harness blocked that twice as credential harvesting.
+// Our happy path required the agent to do something indistinguishable from an attack.
+//
+// The proxy is the one component that can close this without moving the credential: it
+// already holds the key and already sees every JSON-RPC message. So the agent names a PATH,
+// the proxy reads the bytes and POSTs them. The key never approaches the model and the file
+// never passes through its context (a 300KB screenshot as base64 in a tool argument is ~100k
+// output tokens, which is why the bytes-over-HTTP design exists in the first place).
+//
+// The cost of that convenience is the reason this module is mostly rules: a proxy-side read
+// bypasses the harness's OWN file-access prompt. Whatever this module agrees to open, a model
+// can attach with nobody approving it, so a prompt-injected agent told to "attach the config"
+// 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";
+/** 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
+ *  name, the best shape the environment can actually support — the model never has to know
+ *  which it got, it just reads the schema it was handed. */
+export const ATTACH_TOOL_NAME = "save_attachment_file";
+/** Matches the server's `MAX_ENCRYPTED_BLOB_BYTES`. Checked locally too so an oversized file
+ *  fails before we spend the upload, and with a message that names the size. */
+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";
+/**
+ * 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
+ * the proxy's cwd is often the main checkout while the file is next door), else the proxy's
+ * cwd. Resolved through `realpathSync` so the containment check below compares like with
+ * like on macOS, where `/tmp` is a symlink to `/private/tmp` and a naive prefix test on the
+ * unresolved root rejects every legitimate path under it.
+ */
+export function attachRoot(env, cwd) {
+    const configured = (env[ATTACH_ROOT_ENV] ?? "").trim();
+    const raw = configured || cwd;
+    try {
+        return realpathSync(raw);
+    }
+    catch {
+        return resolve(raw); // non-existent root: nothing will resolve inside it anyway
+    }
+}
+/**
+ * Resolve a caller-supplied path against `root` and decide whether we are willing to read it.
+ *
+ * Refusals, and what each one is actually for:
+ *  - 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.
+ *  - 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
+ *    can say how big the file actually was.
+ *
+ * A `~` is deliberately NOT expanded: the home directory is precisely what the root confines
+ * away from, so silently reaching it would undo the boundary.
+ */
+export function resolveAttachPath(input, root) {
+    const requested = typeof input === "string" ? input.trim() : "";
+    if (!requested)
+        return { ok: false, error: "path is required" };
+    if (requested.startsWith("~")) {
+        return {
+            ok: false,
+            error: `path "${requested}" starts with ~, which is not expanded. Attachable files must live ` +
+                `under ${root}; give a path inside it (relative paths resolve against it).`,
+        };
+    }
+    const candidate = resolve(root, requested);
+    let real;
+    try {
+        real = realpathSync(candidate);
+    }
+    catch {
+        return { ok: false, error: `no such file: ${candidate}` };
+    }
+    // `root + sep` would be "//" for a root of "/", which nothing starts with — so a root of
+    // "/" 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)) {
+        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")) {
+        return { ok: false, error: `refusing to read ${real}: paths inside a .git directory are not attachable.` };
+    }
+    let size;
+    try {
+        const st = statSync(real);
+        if (!st.isFile())
+            return { ok: false, error: `not a regular file: ${real}` };
+        size = st.size;
+    }
+    catch {
+        return { ok: false, error: `cannot stat ${real}` };
+    }
+    if (size === 0)
+        return { ok: false, error: `refusing to attach an empty file: ${real}` };
+    if (size > MAX_ATTACH_BYTES) {
+        return {
+            ok: false,
+            error: `file is ${size} bytes, over the ${MAX_ATTACH_BYTES}-byte attachment limit: ${real}`,
+        };
+    }
+    // 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 };
+}
+/** 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
+ *  may read from, and a refusal it could have avoided costs a whole turn. */
+export function localAttachToolDef(root) {
+    return {
+        name: ATTACH_TOOL_NAME,
+        description: "Attach a FILE on this machine to an issue, in ONE call. Give the path; your local retasc " +
+            "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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                issue: { type: "string", description: "Issue ID, e.g. RTSC-12" },
+                path: { type: "string", description: `File path, absolute or relative to ${root}.` },
+                title: { type: "string", description: "Optional label; also the download name." },
+            },
+            required: ["issue", "path"],
+        },
+    };
+}
+/**
+ * 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 base64 fallback)
+ * or append it when the server has none. Appending matters — the proxy only needs
+ * `prepare_attachment_upload` to do its job, so it can offer one-call attachment against a
+ * server deployed before the base64 variant existed.
+ */
+export function mergeAttachTool(tools, root) {
+    if (!Array.isArray(tools))
+        return tools;
+    const local = localAttachToolDef(root);
+    const idx = tools.findIndex((t) => t && typeof t === "object" && t.name === ATTACH_TOOL_NAME);
+    if (idx === -1)
+        return [...tools, local];
+    const merged = [...tools];
+    merged[idx] = local;
+    return merged;
+}
+/** Does this JSON-RPC message want a LOCAL file upload? Only a `path` argument does: an agent
+ *  that sends `contentBase64` is using the server's variant and must be forwarded untouched,
+ *  so an older or hand-written client keeps working through a newer proxy. */
+export function isLocalAttachCall(msg) {
+    const m = msg;
+    if (!m || m.method !== "tools/call" || m.params?.name !== ATTACH_TOOL_NAME)
+        return false;
+    const args = m.params?.arguments;
+    return typeof args?.path === "string" && args.path.trim() !== "";
+}
+/** Build the upload URL: the server hands back a per-issue endpoint, we add the download-name
+ *  hints. `filename` drives the stored name and the server's content-type inference; `title`
+ *  is the human label. Both are query params because the endpoint takes the raw bytes as its
+ *  entire body. */
+export function uploadUrlWith(uploadUrl, filename, title) {
+    const sepChar = uploadUrl.includes("?") ? "&" : "?";
+    const parts = [`filename=${encodeURIComponent(filename)}`];
+    if (title && title.trim())
+        parts.push(`title=${encodeURIComponent(title.trim())}`);
+    return `${uploadUrl}${sepChar}${parts.join("&")}`;
+}
+/** Turn an upload HTTP failure into something the agent can act on. The endpoint answers in
+ *  plain text, so the status is what carries the meaning; a bare "HTTP 402" tells an agent
+ *  nothing it can relay to the human who alone can fix it. */
+export function uploadFailureMessage(status, body) {
+    const detail = body.trim() ? ` — ${body.trim()}` : "";
+    switch (status) {
+        case 401:
+            return `upload rejected: this proxy's key no longer authenticates${detail}`;
+        case 402:
+            return (`upload refused for billing${detail}. PASS THIS TO YOUR HUMAN — you cannot fix it ` +
+                `yourself, only an owner can, and until they do every write will keep failing.`);
+        case 404:
+            return `upload rejected: no such issue in this project${detail}`;
+        case 413:
+            return `upload rejected: file too large${detail}`;
+        default:
+            return `upload failed with HTTP ${status}${detail}`;
+    }
+}

package/dist/lib/watchdog.js

@@ -111,32 +111,93 @@ export function heartbeatRequest(rpcId, issueId, claimToken) {
     };
 }
 /**
- * A heartbeat CLAIM_LOST means the lease is gone — stop tracking it.
+ * Does a tool result carry SERVER ERROR signal `code`? The shared matcher behind
+ * isClaimLost / isUnauthorized.
  *
- * The server throws `Error("CLAIM_LOST: …")` (convex/lib/claims.ts), and http.ts
- * surfaces that as an MCP tool ERROR: `{ isError: true, content:[{text:"CLAIM_LOST: …"}] }`.
- * Match ONLY that signal (or a top-level `error`/`code` field, for a future
- * structured shape) — NEVER `JSON.stringify` the whole result and regex it, or a
- * benign payload field that merely CONTAINS "CLAIM_LOST" (an issue title, a
- * checkpoint note quoting an error, a comment body) would silently drop a live
- * lease and let the reclaimer hand our work to someone else (RTSC-150).
+ * The server throws `Error("CLAIM_LOST: …")` / `Error("UNAUTHORIZED: …")`
+ * (convex/lib/claims.ts, convex/lib/auth.ts), and http.ts surfaces that as an MCP
+ * tool ERROR: `{ isError: true, content:[{text:"CLAIM_LOST: …"}] }`. Match ONLY that
+ * signal (or a top-level `error`/`code` field, for a future structured shape) —
+ * NEVER `JSON.stringify` the whole result and regex it, or a benign payload field
+ * that merely CONTAINS the code (an issue title, a checkpoint note quoting an error,
+ * a comment body) would silently drop a live lease and let the reclaimer hand our
+ * work to someone else (RTSC-150).
  */
-export function isClaimLost(result) {
+function hasErrorCode(result, code) {
     if (!result || typeof result !== "object")
         return false;
     const r = result;
+    // Substring match, NOT `new RegExp(code)`: the codes are fixed literals, so a
+    // regex buys nothing and turns any future caller-supplied code into a regex
+    // injection / ReDoS shape. `.includes` is the same match with none of that.
+    const carries = (s) => s.includes(code);
     // A structured error signal on a top-level field (belt-and-suspenders; also the
     // shape the older unit test asserts). Bounded to top-level scalars, not nested.
-    if (r.code === "CLAIM_LOST")
+    if (r.code === code)
         return true;
-    if (typeof r.error === "string" && /CLAIM_LOST/.test(r.error))
+    if (typeof r.error === "string" && carries(r.error))
         return true;
     // The live shape: only an MCP error envelope, and only its text blocks — success
-    // payloads (isError absent/false) are never treated as a lost claim.
+    // payloads (isError absent/false) are never treated as an error.
     if (r.isError !== true || !Array.isArray(r.content))
         return false;
     return r.content.some((c) => c !== null &&
         typeof c === "object" &&
         typeof c.text === "string" &&
-        /CLAIM_LOST/.test(c.text));
+        carries(c.text));
+}
+/** A heartbeat CLAIM_LOST means the lease is gone — stop tracking it. */
+export function isClaimLost(result) {
+    return hasErrorCode(result, "CLAIM_LOST");
+}
+/**
+ * A heartbeat UNAUTHORIZED means the CREDENTIAL died, not the lease (RTSC-646).
+ * `resolveAuth` throws it when the key was revoked or rotated, its parent key was
+ * revoked, or the member was suspended/retired — so EVERY lease in this session
+ * stops renewing at once and each one lapses at its own expiry.
+ *
+ * Deliberately NOT treated like CLAIM_LOST: the claims are still ours and still
+ * live server-side, so dropping them from the map would hide exactly the leases
+ * the human needs to hear about. We keep tracking, keep trying (a re-mint can fix
+ * it inside the TTL), and say so loudly.
+ */
+export function isUnauthorized(result) {
+    return hasErrorCode(result, "UNAUTHORIZED");
+}
+/**
+ * The renewal-visibility warning (RTSC-646): this session is touching a lease the
+ * watchdog is NOT renewing, so it runs on the bare 30-minute TTL.
+ *
+ * The lease map is in-memory and built ONLY from claim traffic this process saw, so
+ * a claim made in another terminal, over direct HTTP MCP, or by a previous proxy
+ * before a harness restart is renewed by nobody — and today that is silent until
+ * the reclaimer takes the issue away mid-work. Two observable tells, both meaning
+ * "we hold it, we aren't renewing it":
+ *   1. a request carrying a `claimToken` for an issue we don't track (the agent is
+ *      hand-heartbeating/checkpointing a lease we never saw claimed), and
+ *   2. a `check_claim` answering `youHold: true` for an issue we don't track.
+ * Returns the warning text, or undefined when there's nothing to say. Pure so the
+ * decision is testable without a proxy; the caller does the printing.
+ */
+export function untrackedLeaseWarning(o, leases) {
+    const id = typeof o.args?.identifier === "string" ? o.args.identifier : undefined;
+    if (!id || leases.has(id))
+        return undefined;
+    // `release_issue` also carries a claimToken, but it ENDS the lease. Warning
+    // "nothing is renewing it, heartbeat it yourself" about a claim the agent is
+    // deliberately handing back is advice for the opposite of what it just did.
+    if (o.toolName === "release_issue")
+        return undefined;
+    const holds = typeof o.args?.claimToken === "string" ||
+        (!!o.result &&
+            typeof o.result === "object" &&
+            o.result.youHold === true);
+    if (!holds)
+        return undefined;
+    return (`lease for ${id} is NOT tracked by this proxy — nothing is renewing it, so it ` +
+        `runs on the bare 30-minute TTL and the reclaimer will take it mid-work. ` +
+        `This happens when the claim was made in another terminal, over direct HTTP MCP, ` +
+        `or by a previous proxy before a restart. Heartbeat or checkpoint it yourself ` +
+        `(checkpoint is better — it renews AND leaves the handoff note), or release it ` +
+        `and re-claim through this session.`);
 }

package/dist/proxy.js

@@ -6,14 +6,16 @@
 // 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";
 import { fileURLToPath } from "node:url";
-import { applyObservation, heartbeatRequest, isClaimLost, shouldReapOnClose, } from "./lib/watchdog.js";
+import { applyObservation, heartbeatRequest, isClaimLost, isUnauthorized, shouldReapOnClose, untrackedLeaseWarning, } from "./lib/watchdog.js";
 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";
 // 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).
@@ -23,12 +25,19 @@ const KEY = resolved.key;
 const HEARTBEAT_MS = Number(process.env.RETASC_HEARTBEAT_MS) || 10 * 60 * 1000;
 const leases = new Map();
 let hbSeq = -1; // out-of-band heartbeat ids are negative — never collide with the harness's
+// RTSC-646: the credential-death warning fires ONCE with its full explanation. A
+// revoked/rotated key fails every heartbeat of every lease, so repeating the whole
+// paragraph on each tick (every 10 min, per lease) would bury the first one.
+let authWarned = false;
 // Per-session key (RTSC-50): starts as the workspace key; on startup we mint a
 // session key and switch to it so this session is distinguishable from others.
 let activeKey = KEY;
 // Set when session-key minting failed and we fell back to the workspace key —
 // whoami responses get a warning block appended so the agent sees the degraded state.
 let sessionKeyFallback = false;
+// RTSC-660: the directory a `save_attachment_file` path must live under. Resolved ONCE at
+// startup, not per call, so the boundary can't be moved mid-session by anything the model says.
+const ATTACH_ROOT = attachRoot(process.env, process.cwd());
 // stderr only: stdout is the MCP channel and must carry ONLY protocol messages.
 function log(msg) {
     process.stderr.write(`[retasc-watchdog] ${msg}\n`);
@@ -175,6 +184,82 @@ async function announceBinding() {
 function toolResult(resp, tool) {
     return parseTool(resp, (msg) => log(tool ? `${tool}: ${msg}` : msg));
 }
+/** Write one JSON-RPC tool result back to the harness (the local half of a tools/call). */
+function replyToolResult(id, text, isError) {
+    process.stdout.write(JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        result: { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) },
+    }) + "\n");
+}
+/**
+ * Serve `save_attachment_file` LOCALLY (RTSC-660): the agent names a path, we read the bytes
+ * and POST them with the key we already hold. This is the whole fix — it turns the one write
+ * an agent could not complete on its own into a single tool call, and removes the step where
+ * a well-behaved agent had to go reading a credential file off disk.
+ *
+ * The upload URL is fetched from the server rather than composed here, so the issue check,
+ * the project boundary and the endpoint's shape all stay server-authoritative and this side
+ * holds no policy it could get wrong. The path is validated first, before we spend a round
+ * trip on a file we would refuse to read anyway.
+ *
+ * Every accepted read is logged to stderr with its resolved path: a proxy-side read bypasses
+ * the harness's own file-access prompt, so the MCP log is where a human can see what was
+ * actually opened on their behalf.
+ */
+async function handleLocalAttach(msg) {
+    const args = (msg.params?.arguments ?? {});
+    const issue = typeof args.issue === "string" ? args.issue.trim() : "";
+    if (!issue)
+        return replyToolResult(msg.id, "issue is required (e.g. RTSC-12)", true);
+    const resolved = resolveAttachPath(String(args.path ?? ""), ATTACH_ROOT);
+    if (!resolved.ok) {
+        log(`refused attachment for ${issue}: ${resolved.error}`);
+        return replyToolResult(msg.id, resolved.error, true);
+    }
+    // Ask the server where this issue's bytes go. Doubles as the auth + issue-exists check, so
+    // a bad id or a foreign project fails before we open anything.
+    let prepared;
+    try {
+        prepared = toolResult(await postRemote({
+            jsonrpc: "2.0",
+            id: hbSeq--,
+            method: "tools/call",
+            params: { name: "prepare_attachment_upload", arguments: { issue } },
+        }), "prepare_attachment_upload");
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `could not reach Retasc: ${String(e?.message ?? e)}`, true);
+    }
+    const uploadUrl = typeof prepared?.uploadUrl === "string" ? prepared.uploadUrl : "";
+    if (!uploadUrl) {
+        // Relay what the server said rather than a generic failure: it is usually NOT_FOUND for
+        // this issue, and that is the sentence the agent needs to see.
+        const detail = typeof prepared === "string" ? prepared : JSON.stringify(prepared ?? null);
+        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}`);
+    try {
+        const res = await fetch(uploadUrlWith(uploadUrl, resolved.filename, title), {
+            method: "POST",
+            // No Content-Type on purpose: the server infers it from `filename`, and that inference
+            // 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),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            log(`upload of ${resolved.filename} to ${issue} failed: HTTP ${res.status}`);
+            return replyToolResult(msg.id, uploadFailureMessage(res.status, body), true);
+        }
+        return replyToolResult(msg.id, body, false);
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `upload failed: ${String(e?.message ?? e)}`, true);
+    }
+}
 async function handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -186,6 +271,11 @@ async function handleLine(line) {
     catch {
         return; // not a JSON-RPC message — ignore
     }
+    // RTSC-660: a file attachment by PATH is served here, not forwarded — the bytes are on
+    // THIS machine and the credential is in this process. Anything else (including the same
+    // tool called with `contentBase64`, the server's own variant) goes remote untouched.
+    if (isLocalAttachCall(msg))
+        return await handleLocalAttach(msg);
     let resp;
     try {
         resp = await postRemote(msg);
@@ -201,6 +291,14 @@ async function handleLine(line) {
         }
         return;
     }
+    // RTSC-660: advertise the PATH form of save_attachment_file in place of the server's
+    // base64 one. A tool list is fetched once at startup, so this is the only moment we get to
+    // 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))
+            result.tools = mergeAttachTool(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
     // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.
@@ -212,6 +310,12 @@ async function handleLine(line) {
         // ownership). Pure decision — see shouldReapOnClose. We act on it AFTER relaying
         // the response, below (RTSC-181).
         reapId = shouldReapOnClose(obs, leases);
+        // RTSC-646: warn BEFORE applyObservation, while the map still reflects what we
+        // were renewing when the call was made — after it, a fresh claim would look
+        // tracked and a deliberate release would look untracked.
+        const warning = untrackedLeaseWarning(obs, leases);
+        if (warning)
+            log(`warning: ${warning}`);
         applyObservation(leases, obs);
         appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
     }
@@ -227,11 +331,35 @@ async function handleLine(line) {
 async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {
         try {
-            const resp = await postRemote(heartbeatRequest(hbSeq--, issueId, token));
-            if (isClaimLost(toolResult(resp, "heartbeat"))) {
+            const result = toolResult(await postRemote(heartbeatRequest(hbSeq--, issueId, token)), "heartbeat");
+            if (isClaimLost(result)) {
                 leases.delete(issueId);
                 log(`lease for ${issueId} is gone — stopped tracking`);
             }
+            else if (isUnauthorized(result)) {
+                // RTSC-646: the credential died, not the lease. Every claim in this session
+                // stops renewing at once and lapses at its own expiry, which reads exactly
+                // like "the watchdog is working" until the reclaimer takes the work away.
+                // Keep tracking and keep trying — re-minting the key inside the TTL recovers
+                // every lease — but say the cause out loud, once.
+                if (!authWarned) {
+                    authWarned = true;
+                    log(`warning: heartbeat for ${issueId} was rejected as UNAUTHORIZED — this session's key ` +
+                        `no longer authenticates (revoked or rotated key, revoked parent key, or a suspended/` +
+                        `retired member). NO lease in this session is being renewed now; each one lapses at ` +
+                        `its own expiry and the reclaimer hands the work to another agent. Restore the ` +
+                        `credential and restart this session, or finish and release your claims by hand.`);
+                }
+                else {
+                    log(`heartbeat for ${issueId} still UNAUTHORIZED — lease not renewed`);
+                }
+            }
+            else {
+                // A renewal that worked proves the credential works, so arm the full
+                // warning again: a key re-minted mid-session and then revoked a second
+                // time deserves the same loud explanation as the first time.
+                authWarned = false;
+            }
         }
         catch (e) {
             log(`heartbeat for ${issueId} failed: ${String(e?.message ?? e)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.21.1",
+  "version": "1.23.0",
   "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": {