@retasc/cli 1.35.0 → 1.36.0

package/CHANGELOG.md

@@ -6,6 +6,67 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.36.0 (2026-08-25)
+
+- **RTSC-520** — the CLI now says when it is out of date. There was no version check
+  anywhere in `cli/`, so a global install went stale silently and stayed that way for as
+  long as the machine lived — and a stale CLI does not merely lack features, it *lies*:
+  its copy describes SERVER behaviour, so 1.11.0 kept telling people a decline "covers the
+  whole org, including later migrations" long after RTSC-507 made that false, and 1.10.0
+  had no Google door, so it sent Google-only humans through GitHub and minted them a
+  second identity. After any login-gated command an outdated build now prints one line
+  naming both versions and asks whether to update:
+
+  ```
+  A newer retasc is available (1.36.0, you have 1.35.2).
+  Update now? [y/N]
+  ```
+
+  Notify then ask, never a silent `npm i -g`: interactive terminals only (no TTY prints
+  the notice and nothing else, so scripted runs are unchanged), at most once a day with a
+  decline remembered, and a failed install — EACCES on a root-owned prefix is the common
+  one — reports itself and names `npm i -g @retasc/cli@latest` without ever failing the
+  command you actually ran. A successful update says it applies from your next command and
+  that agents need restarting to pick up the new MCP server. The MCP proxy never prints it.
+
+  The published version is resolved server-side from the npm registry, cached hourly, and
+  handed down on `manage:me` — a call every login-gated command already makes, so checking
+  costs no round trip and no shared rate limit, and no release step can forget to update
+  it. An optional `RETASC_CLI_MIN_HONEST` marks the oldest version whose copy still matches
+  the server; below it the notice says so plainly, because "a newer version exists" and
+  "what this build just told you may be false" are different problems.
+
+## 1.35.2 (2026-08-25)
+
+- **RTSC-743** — the last CLI replies that answered a person with a machine shape now
+  answer in sentences. A failed MCP request used to paste 200 characters of the raw
+  response body after the status, which on that endpoint is either a JSON-RPC envelope or,
+  when the failure lands at Cloudflare rather than in Convex, a page of HTML; it now says
+  what the status means and what to do about it, and reads the body for a message rather
+  than printing it. A reply that is not JSON at all (a proxy error page, a captive portal)
+  named a JSON parser's position; it now names what actually answered. `retasc login`
+  stringified GitHub's whole OAuth payload into its error, burying `error_description`,
+  the one field in it written for a person. `whoami` and `doctor` could surface a bare
+  parser complaint from `resolveBinding`, which is a poor answer to "what is broken?" from
+  the two commands you run when something already is. And `retasc import` printed the
+  summary with the wire payload's own field names as labels — `issuesCreated`,
+  `commentsInserted`, `attachmentsRehosted` — where it now prints Issues created,
+  Comments and Attachments copied. Along the way, `doctor` and `whoami` stop telling you
+  to re-run `retasc bind` when the thing that answered was a proxy rather than Retasc:
+  that failure carries no verdict on your key, and re-binding to fix it mints a new one
+  for nothing.
+
+## 1.35.1 (2026-08-25)
+
+- **RTSC-478** — a network failure now names its own cause. Node reports every failed
+  `fetch` as the literal `fetch failed` and puts the diagnosis on `err.cause.code`, which
+  the CLI read past, so `retasc login` on a machine whose TLS trust store Node cannot read
+  died on `✗ fetch failed` and nothing else. It now prints
+  `✗ fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` — a searchable string naming the
+  real problem. `cli/README.md` gains a troubleshooting entry keyed on that code, covering
+  both causes: a corporate TLS-inspecting proxy, and a Homebrew `openssl@3` keg that lost
+  its CA symlink (the confusing one, since `curl` and `npm` keep working).
+
 ## 1.35.0 (2026-08-25)
 
 - **RTSC-709** — `retasc issue show` and `retasc issue list` read the queue from a

package/README.md

@@ -122,6 +122,34 @@ Two more are reachable but not as their own command, which is also deliberate:
 If you want any of the above from a terminal anyway, say so in an issue: the point of this
 list is that their absence is a choice we wrote down, not one nobody has noticed.
 
+## Troubleshooting
+
+### `fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` or `(SELF_SIGNED_CERT_IN_CHAIN)`
+
+Node cannot verify the TLS certificate, so every request the CLI makes dies before it is
+sent. It usually shows up on `retasc login`, because that is the first command that talks
+to the network. Two causes, and the code tells you which:
+
+- **A corporate TLS-inspecting proxy** (Zscaler and similar) re-signs traffic with a root
+  Node does not trust — normally `SELF_SIGNED_CERT_IN_CHAIN`. Point Node at your
+  organisation's CA bundle:
+
+  ```bash
+  export NODE_EXTRA_CA_CERTS=/path/to/your-company-ca.pem
+  ```
+
+- **A Homebrew Node whose OpenSSL keg lost its CA symlink** — normally
+  `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, and the confusing one, because `curl` and `npm`
+  keep working: they do not read the file Node reads. Relink it:
+
+  ```bash
+  brew postinstall openssl@3
+  ```
+
+Never set `NODE_TLS_REJECT_UNAUTHORIZED=0`. It turns off certificate verification for
+every connection the process makes, including the one carrying your session token.
+`NODE_EXTRA_CA_CERTS` fixes the same failures with verification left on.
+
 ## Links
 
 - Website — [retasc.com](https://retasc.com)

package/dist/api.js

@@ -3,7 +3,9 @@ import { makeFunctionReference } from "convex/server";
 import { loadConfig } from "./config.js";
 import { refreshSession, deviceLogin } from "./auth.js";
 import { selfCommand } from "./lib/launcher.js";
+import { clean as sanitize } from "./lib/text.js";
 import { VERSION } from "./version.js";
+import { recordRelease } from "./lib/updateNotice.js";
 // Typed-ish references to the public management functions in convex/manage.ts.
 // The CLI is a standalone package, so we reference functions by name rather than
 // importing the parent's generated api.
@@ -100,6 +102,19 @@ export function formatError(e) {
         .split("\n")[0]
         .replace(/^.*?Uncaught Error:\s*/, "")
         .trim();
+    // RTSC-478: a failed `fetch` throws the literal `TypeError: fetch failed` and puts the
+    // actual diagnosis on `cause.code` — `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` when Node cannot
+    // read the machine's CA roots, `SELF_SIGNED_CERT_IN_CHAIN` behind a corporate
+    // TLS-inspecting proxy, `ECONNREFUSED`, `ENOTFOUND`. Reading `message` alone throws away
+    // the diagnosis Node already handed us, and leaves `retasc login` — the FIRST command a
+    // new user runs — dead-ended on a string that names nothing and searches for nothing:
+    //     ✗ fetch failed          →     ✗ fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)
+    // Fallback branch only: a structured backend error (above) already carries its own `code`.
+    // Sanitized like every other string we print, because `cause` is not always ours.
+    const raw = e?.cause?.code;
+    const code = typeof raw === "string" ? sanitize(raw).trim() : "";
+    if (code && !message.includes(code))
+        return { message: `${message} (${code})` };
     return { message };
 }
 /**
@@ -173,7 +188,15 @@ async function withAuth(call) {
     }
 }
 export const api = {
-    me: () => withAuth(() => client().query(fns.me, {})),
+    // RTSC-520 — every login-gated command already makes this call, so the published-version
+    // signal rides down on it and costs nothing. Recording it HERE, rather than at each of the
+    // nine call sites, is also what keeps the notice out of the machine channel: the MCP proxy
+    // never imports this module, so it can never have a signal to print.
+    me: async () => {
+        const res = await withAuth(() => client().query(fns.me, {}));
+        recordRelease(res?.cli);
+        return res;
+    },
     listProjects: (args) => withAuth(() => client().query(fns.listProjects, args)),
     createOrg: (args) => withAuth(() => client().mutation(fns.createOrg, args)),
     createProject: (args) => withAuth(() => client().mutation(fns.createProject, args)),

package/dist/auth.js

@@ -4,6 +4,9 @@ import { makeFunctionReference } from "convex/server";
 import { loadConfig, patchConfig } from "./config.js";
 import { ask, isInteractive } from "./lib/prompt.js";
 import { startBrowserLogin } from "./lib/browserLogin.js";
+import { clean } from "./lib/text.js";
+import { selfCommand } from "./lib/launcher.js";
+import { VERSION } from "./version.js";
 // The GitHub OAuth App's PUBLIC client id (safe to ship — device flow needs no
 // secret). Baked in so `retasc login` works out-of-the-box; override via env.
 const GITHUB_CLIENT_ID = process.env.RETASC_GITHUB_CLIENT_ID ?? "Ov23linqRy875IU8OYTW";
@@ -140,7 +143,13 @@ async function githubDeviceToken() {
         scope: "read:user user:email",
     });
     if (!start.device_code) {
-        throw new Error(`GitHub device-flow start failed: ${JSON.stringify(start)}`);
+        // Say what GitHub said, not what GitHub SENT. The whole response used to be
+        // JSON.stringify'd into this message, which put a raw OAuth payload in front of
+        // someone whose only question is whether to try again — and buried
+        // `error_description`, the one field in it written for a person to read.
+        const said = start.error_description ?? start.error;
+        throw new Error(`GitHub didn't hand back a sign-in code${said ? `: ${clean(said)}` : "."} ` +
+            `Check your connection and run \`${selfCommand(VERSION)} login\` again.`);
     }
     announceCode("GitHub", start.verification_uri, start.user_code, start.verification_uri_complete);
     // Poll GitHub for the access token.

package/dist/commands/claim.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { basename, dirname, resolve, sep } from "node:path";
 import { resolveMcpConn, readMcpJson, mcpCall, parseClaimResult, planWorktree, isValidIssueId, normalizeIssueId, resolveIssueRef, } from "../lib/claim.js";
 import { loadConfig } from "../config.js";
+import { clean } from "../lib/text.js";
 function git(args, cwd) {
     return spawnSync("git", args, { encoding: "utf8", cwd });
 }
@@ -124,7 +125,12 @@ export async function claimAction(opts) {
     }
     // The id flows into a git ref and a filesystem path — reject a malformed one.
     if (!isValidIssueId(claim.issueId)) {
-        note(`✗ Server returned an unexpected issue id: ${JSON.stringify(claim.issueId)}`);
+        // Named in words, not JSON.stringify'd. The value is either a string, in which case
+        // quoting it is enough, or it is a shape — and dumping that shape tells the reader
+        // nothing they can act on while looking exactly like a crash.
+        const shown = typeof claim.issueId === "string" ? `"${clean(claim.issueId)}"` : "nothing usable";
+        note(`✗ Retasc sent ${shown} where an issue id (like RTSC-42) should be.`);
+        note(`  Nothing was branched or checked out. Try again, or run \`retasc doctor\`.`);
         process.exit(1);
     }
     // claim_issue returns just the id — fetch the title so the slug is meaningful.

package/dist/commands/doctor.js

@@ -134,7 +134,7 @@ export async function doctorAction() {
                 // The binding EXISTS; we just can't verify it. Don't send the user off
                 // to re-bind over a dead wifi link or a server having a bad minute.
                 networkDown = true;
-                warn(`binding present (${local.source} scope) but the server didn't answer: ${msg}.`);
+                warn(`binding present (${local.source} scope) but no usable answer came back: ${msg}.`);
             }
             else {
                 bad(`key not accepted by the server: ${msg}. Re-run \`retasc bind\`.`);

package/dist/commands/import.js

@@ -50,6 +50,42 @@ export function reimportWarning(history, source, label) {
         `  Re-importing re-syncs those issues, so any edits you made in Retasc to them\n` +
         `  (status, labels, and so on) will be replaced by ${clean(label)}'s version.`);
 }
+/**
+ * What each field of the server's `ImportSummary` is CALLED, for a person.
+ *
+ * The summary is a wire payload, and it used to be printed with its own keys as labels —
+ * `issuesCreated`, `commentsInserted`, `attachmentsRehosted`, one per line. That is a JSON
+ * object with the braces taken off: it reads as the inside of the program rather than as
+ * the answer to "what just came across". The names live here, in one list, next to the
+ * shape they describe (`ImportSummary` in convex/import.ts).
+ */
+const SUMMARY_LABELS = {
+    totalIssues: "Issues seen",
+    issuesCreated: "Issues created",
+    issuesUpdated: "Issues updated",
+    relationsAdded: "Links between issues",
+    commentsInserted: "Comments",
+    attachmentsRehosted: "Attachments copied",
+    attachmentsFailed: "Attachments that failed",
+};
+/**
+ * A label for a field the list above doesn't name.
+ *
+ * A field this CLI is too old to know about must still read as English rather than as a
+ * key, because the pairing is permanent: the backend deploys separately, so there is
+ * always a version of this CLI that predates the newest summary field. `fooBarBaz`
+ * becomes "Foo bar baz" — not the real name someone would have chosen, but a phrase.
+ */
+export function summaryLabel(key) {
+    // `hasOwnProperty`, not a bare lookup. The keys come off the wire, and a bare
+    // `SUMMARY_LABELS[key]` walks Object.prototype: a field named `constructor` or
+    // `toString` returns a FUNCTION, which `padEnd` then throws on. That would crash
+    // `retasc import` on the line after a multi-minute run finished successfully.
+    if (Object.prototype.hasOwnProperty.call(SUMMARY_LABELS, key))
+        return SUMMARY_LABELS[key];
+    const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
 /**
  * The summary after a run, with the one field that needs words rather than a number.
  *
@@ -66,8 +102,11 @@ export function summaryLines(summary, label) {
                 unmapped.push(...v.map(String));
             continue;
         }
-        if (typeof v === "number" || typeof v === "string")
-            out.push(`  ${k.padEnd(20)}${clean(v)}`);
+        // Only numbers and strings are printed, which is also what keeps a structured field
+        // (`sample`, `relationCyclesSkipped`) from arriving as `[object Object]`.
+        if (typeof v === "number" || typeof v === "string") {
+            out.push(`  ${summaryLabel(k).padEnd(24)}${clean(v)}`);
+        }
     }
     if (unmapped.length) {
         out.push("", `! These ${clean(label)} statuses weren't mapped, so their issues landed in todo:`, `    ${unmapped.map((u) => clean(u)).join(", ")}`, "  They appeared after you set the mapping. Re-import to place them.");

package/dist/config.js

@@ -68,6 +68,12 @@ export function loadConfig() {
         // "never asked", so a mangled file leads to a question rather than to an
         // install nobody agreed to.
         globalInstall: typeof stored.globalInstall === "boolean" ? stored.globalInstall : undefined,
+        // Same rule again (RTSC-520): a hand-edited or mangled value reads as "never shown".
+        // Finite, because `NaN`/`Infinity` survive JSON round-trips through some editors and
+        // would make the once-a-day gate either permanently open or permanently shut.
+        updateNoticeAt: typeof stored.updateNoticeAt === "number" && Number.isFinite(stored.updateNoticeAt)
+            ? stored.updateNoticeAt
+            : undefined,
     };
 }
 /** Move a corrupt config aside to a unique sibling so a human can recover any

package/dist/index.js

@@ -21,6 +21,7 @@ import { issueShowAction, issueListAction, checkpointAction, checkClaimAction, }
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
 import { api, formatError } from "./api.js";
+import { maybeOfferUpdate } from "./lib/updateNotice.js";
 const program = new Command();
 program
     .name("retasc")
@@ -111,7 +112,7 @@ program
             const msg = String(e?.message ?? e).replace(/[\x00-\x1f\x7f]/g, " ");
             // Unreachable ≠ rejected: don't imply a bad key over a dead network.
             if (isNetworkError(e))
-                console.log(`This folder → binding present, but the server didn't answer: ${msg}\n`);
+                console.log(`This folder → binding present, but no usable answer came back: ${msg}\n`);
             else
                 console.log(`This folder → bound, but the key did not resolve: ${msg}\n`);
         }
@@ -677,4 +678,13 @@ program
     console.log(`mcp url:        ${cfg.mcpUrl}`);
     console.log(`signed in:      ${isLoggedIn(cfg) ? `yes${cfg.user?.name ? ` (${cfg.user.name})` : ""}` : "no"}`);
 });
+// RTSC-520 — after the command, never during it. A postAction hook is the only place the
+// notice can go without interleaving with a command's own output or with a prompt it is in
+// the middle of asking, and it fires for whatever ran, so nothing has to remember to call it.
+// `maybeOfferUpdate` stays silent unless the command actually talked to the backend and the
+// build is genuinely behind; it never throws, because a notice must not fail a command that
+// already succeeded.
+program.hook("postAction", async () => {
+    await maybeOfferUpdate();
+});
 program.parseAsync(process.argv);

package/dist/lib/binding.js

@@ -2,6 +2,7 @@ import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { getBinding } from "./keystore.js";
+import { parseToolResult } from "./toolresult.js";
 /** Claude Code's config file. RETASC_CLAUDE_CONFIG overrides it (tests). */
 export function claudeConfigPath() {
     return process.env.RETASC_CLAUDE_CONFIG || join(homedir(), ".claude.json");
@@ -123,6 +124,18 @@ export function claudeLocalRetascEntry(dir) {
 export function bindingRefused(e) {
     return /\bUNAUTHORIZED\b/i.test(String(e?.message ?? e));
 }
+/**
+ * A failure that says nothing about the key: see `isNetworkError`.
+ *
+ * Every caller of `resolveBinding` splits its failures two ways, and the split decides
+ * what the human is told to do. These three are neither a refusal nor a dead network,
+ * so they are tagged explicitly instead of being classified by accident.
+ */
+function noVerdict(message) {
+    const e = new Error(message);
+    e.retascNoVerdict = true;
+    return e;
+}
 /** Read the Retasc binding a folder's agent actually uses, from either legal
  *  location — claude-local first, matching Claude Code's runtime precedence. */
 export function readLocalBinding(dir) {
@@ -217,6 +230,16 @@ export function sameIdentity(a, b) {
  *  advice differs: "check your network / try again" vs "re-run retasc bind".
  *  A 4xx (other than 429) IS a verdict: the server saw the key and said no. */
 export function isNetworkError(e) {
+    // Tagged rather than matched on its prose. `noVerdict` marks the failures where
+    // something answered but not Retasc, or Retasc answered in a shape we could not
+    // read: the server passed no judgement on the key either way. Without this they
+    // fall through to the 4xx branch and `doctor` says "key not accepted, re-run
+    // `retasc bind`" at somebody whose real problem is a proxy, which is both wrong
+    // and the most expensive wrong answer available (a re-bind mints a new key).
+    // A FLAG, not a regex, because this file's own comment is right that matching
+    // prose is fragile, and these strings are copy that will be reworded.
+    if (e?.retascNoVerdict === true)
+        return true;
     const name = String(e?.name ?? "");
     if (name === "TimeoutError" || name === "AbortError")
         return true;
@@ -248,7 +271,17 @@ export async function resolveBinding(url, key) {
     });
     if (!res.ok)
         throw new Error(`MCP server returned ${res.status}`);
-    const body = await res.json();
+    // `res.json()` used to be called straight, so a 200 carrying a proxy's error page
+    // (or a captive portal's sign-in form) failed with a JSON parser's complaint about
+    // a `<`. Read the text and say what actually happened instead.
+    const raw = await res.text();
+    let body;
+    try {
+        body = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        throw noVerdict("a proxy or a VPN sign-in page answered instead of Retasc");
+    }
     if (body?.error)
         throw new Error(body.error.message ?? "MCP error");
     const result = body?.result;
@@ -256,6 +289,16 @@ export async function resolveBinding(url, key) {
         throw new Error(result?.content?.[0]?.text ?? "key not accepted");
     const text = result?.content?.[0]?.text;
     if (!text)
-        throw new Error("empty whoami response");
-    return JSON.parse(text);
+        throw noVerdict("the server said nothing at all about this key");
+    // Tolerant, and never a bare JSON.parse. This message is printed by `whoami` and
+    // `doctor` — the two commands someone runs when things are already wrong — so a
+    // "SyntaxError: Unexpected token … in JSON at position 42" here would answer a
+    // person's "what is broken?" with a parser's internal state. The shared parser also
+    // recovers a payload that arrived with prose after it (RTSC-142/143), which is the
+    // regression that made this line worth hardening in the first place.
+    const parsed = parseToolResult(body);
+    if (parsed.kind === "raw") {
+        throw noVerdict("the server's answer wasn't in a shape this CLI could read");
+    }
+    return parsed.value;
 }

package/dist/lib/claim.js

@@ -6,6 +6,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { claudeLocalRetascEntry } from "./binding.js";
 import { resolveConn } from "./keystore.js";
+import { clean } from "./text.js";
 // Tool-payload extraction lives in the shared tolerant parser (RTSC-143);
 // re-exported so existing importers of this module keep working.
 import { toolResult } from "./toolresult.js";
@@ -125,6 +126,63 @@ export function parseClaimResult(result) {
     const title = typeof r.issue === "object" ? r.issue?.title : undefined;
     return { issueId, title, claimToken: r.claimToken };
 }
+/**
+ * A sentence a PERSON can act on for a non-2xx from the MCP endpoint.
+ *
+ * This path used to paste 200 characters of the raw body after the status, and the raw
+ * body is the one shape a reader cannot use: from Convex it is a JSON-RPC envelope, and
+ * when the failure happens at Cloudflare instead of in Convex it is a page of HTML. Both
+ * land in the terminal of somebody who typed `retasc claim`, and neither says what to do.
+ *
+ * So the body is never printed. It is READ — for a message, if it carries one — and what
+ * gets shown is what the status means, in words, plus the fix where there is one. The
+ * status is kept, in parentheses, because it is the thing worth quoting in a bug report.
+ *
+ * Pure, and exported, so the wording is pinned by a test rather than by a live 401.
+ */
+export function mcpFailureMessage(status, body = "", url) {
+    const said = bodyMessage(body);
+    const why = status === 401 || status === 403
+        ? "Retasc refused this folder's key. Re-run `retasc bind` here to mint a fresh one."
+        : status === 404
+            ? `Nothing is serving Retasc at ${url ? clean(url) : "that address"}. Check this folder's MCP url, or re-run \`retasc bind\`.`
+            : status === 429
+                ? "Retasc is rate-limiting this key. Wait a moment, then try again."
+                : status >= 500
+                    ? "Retasc's server had a problem. Nothing was claimed or changed — try again in a minute."
+                    : "Retasc refused the request.";
+    return `${why} (HTTP ${status}${said ? `: ${said}` : ""})`;
+}
+/**
+ * The one sentence inside an error body, or nothing.
+ *
+ * Only ever returns text the server MEANT as a message — a JSON-RPC `error.message`, a
+ * tool result's text, a bare `message` field. Anything else (HTML, a payload with no
+ * message in it, a body that is not JSON at all) returns undefined, so the caller says
+ * its own sentence rather than quoting a structure at the reader. Control characters are
+ * stripped and it is capped at one line: this reaches a terminal that acts on escapes.
+ */
+function bodyMessage(body) {
+    if (!/^\s*[{[]/.test(body))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const said = [parsed?.error?.message, parsed?.result?.content?.[0]?.text, parsed?.message].find((c) => typeof c === "string" && c.trim());
+    if (!said)
+        return undefined;
+    const line = clean(said).split("\n")[0].trim();
+    // A "message" that is itself a payload is the very thing this function exists to keep
+    // off the screen — a server can put its JSON result in `content[0].text`, and quoting
+    // that back would reintroduce the blob one layer down.
+    if (!line || /^[{[]/.test(line))
+        return undefined;
+    return line.slice(0, 200);
+}
 /**
  * Call one MCP tool over JSON-RPC with the agent key. Throws on transport errors
  * and on tool errors (isError) — surfacing the server's message (CLAIM_LOST,
@@ -147,12 +205,23 @@ export async function mcpCall(conn, name, args = {}, fetchImpl = fetch) {
     });
     const text = await res.text();
     // A non-2xx (expired/invalid key → 401, server error → 5xx) must not look like
-    // an empty queue. Surface the status + a body snippet so a bad key is obvious.
-    if (!res.ok) {
-        const snippet = text ? `: ${text.slice(0, 200).replace(/\s+/g, " ").trim()}` : "";
-        throw new Error(`MCP request failed (HTTP ${res.status})${snippet}`);
+    // an empty queue — say what happened, in words. See mcpFailureMessage.
+    if (!res.ok)
+        throw new Error(mcpFailureMessage(res.status, text, conn.url));
+    // A 200 whose body is not JSON is a captive portal, a proxy error page, or a
+    // deployment answering on the wrong route. Letting JSON.parse throw puts
+    // "Unexpected token < in JSON at position 0" in front of a person, which names
+    // neither the problem nor the fix.
+    let resp = null;
+    if (text) {
+        try {
+            resp = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${clean(conn.url)} answered, but not with Retasc's reply — something in between (a proxy, ` +
+                `a captive portal, a VPN sign-in page) is intercepting it.`);
+        }
     }
-    const resp = text ? JSON.parse(text) : null;
     if (resp?.error) {
         throw new Error(resp.error?.message || "MCP transport error");
     }

package/dist/lib/launcher.js

@@ -168,11 +168,17 @@ 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
-    // a hang in the middle of a bind, so say what is happening before it starts.
-    console.log("  Installing the retasc CLI so your agent can start it…");
+/**
+ * Install (or upgrade to) an exact version globally. Returns null on success, and the
+ * first useful line of npm's failure otherwise.
+ *
+ * Exported since RTSC-520, which upgrades an existing install rather than creating one —
+ * same npm invocation, different reason. The "what is happening" line moved OUT to the
+ * callers with it: a cold install takes seconds with no output of its own and silence
+ * reads as a hang, but the sentence that makes sense mid-`bind` ("so your agent can start
+ * it") is the wrong sentence for someone who just answered y to an update prompt.
+ */
+export function installGlobal(version) {
     let r;
     try {
         r = spawnSync("npm", ["install", "-g", `${PKG}@${version}`], {
@@ -228,7 +234,9 @@ export function resolveLauncher(opts) {
     });
     if (opts.install === false)
         return npxFallback("install not attempted");
-    // 2. Try to make `retasc` real.
+    // 2. Try to make `retasc` real. Say so first — a cold install takes seconds in silence
+    //    and this one lands in the middle of a bind, where silence reads as a hang.
+    console.log("  Installing the retasc CLI so your agent can start it…");
     const failure = installGlobal(opts.version);
     // 3. Prove it, by running it. An exit code of 0 is not evidence the command resolves:
     //    npm can install happily into a prefix whose bin directory PATH never searches.

package/dist/lib/updateNotice.js

@@ -0,0 +1,172 @@
+// "You are running an old build" — the one thing the CLI never said (RTSC-520).
+//
+// A stale install is not merely missing features. CLI copy describes SERVER behaviour,
+// so an old build makes false statements about the account in front of it: 1.11.0 told
+// people a decline "covers the whole org, including later migrations" long after
+// RTSC-507 made that untrue, and 1.10.0 had no Google door at all, so it sent a
+// Google-only human through GitHub and minted them a second identity. Both are worse
+// than a missing feature, because nothing on screen hints the sentence is out of date.
+//
+// The stance, and it is deliberate: NOTIFY, THEN ASK. Never a silent `npm i -g`. That
+// mutates someone's machine unasked, fails on a root-owned prefix, and can swap the
+// binary under a running agent. `resolveLauncher` already refuses to surprise-install
+// for someone who manages their own install; this must not undercut it.
+//
+// Four rules fall out of that, and every one of them is a test below:
+//   - Interactive only. No TTY ⇒ the notice, never the prompt and never the install.
+//   - Never in the MCP proxy. An upgrade nag inside an agent's tool results is noise in
+//     a machine channel. Structurally impossible here: the signal is only ever recorded
+//     by `api.me()`, and the proxy does not import api.js.
+//   - At most once a day, stamped in ~/.retasc/config.json. Declining must not re-ask on
+//     the next command.
+//   - A failed install is NOT a failed command. EACCES is the common one. Report it, name
+//     the manual command, and carry on with whatever the human actually ran.
+//
+// Everything goes to STDERR. `retasc issue list --json | jq` must keep working byte for
+// byte, and a notice on stdout would break exactly the scripted callers the issue
+// promises not to disturb.
+import { VERSION } from "../version.js";
+import { loadConfig, patchConfig } from "../config.js";
+import { confirm, isInteractive } from "./prompt.js";
+import { installGlobal } from "./launcher.js";
+const PKG = "@retasc/cli";
+export const MANUAL_INSTALL = `npm i -g ${PKG}@latest`;
+/** Once a day. The notice is worth reading; a notice on every command is wallpaper. */
+export const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * The signal from the most recent `me()` this process made.
+ *
+ * A module slot rather than a parameter because the notice fires from a postAction hook
+ * that has no idea which commands talked to the backend. This is also what scopes the
+ * feature correctly for free: only a login-gated command calls `me()`, so only a
+ * login-gated command can ever have something to say.
+ */
+let recorded;
+/**
+ * A published version and nothing else: three numbers, optionally a prerelease tag.
+ *
+ * Validated HERE as well as on the server, and not out of politeness. These strings do two
+ * dangerous things: they are printed to a terminal, and `latest` is handed to `spawnSync`
+ * as the version half of `@retasc/cli@<v>` — which on Windows runs through a shell. Trusting
+ * the server for the CLI's own subprocess and terminal safety is the wrong shape of trust;
+ * `formatError` already refuses it for backend error strings, for the same reason.
+ */
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const clean = (v) => typeof v === "string" && VERSION_RE.test(v.trim()) ? v.trim() : null;
+export function recordRelease(signal) {
+    if (!signal || typeof signal !== "object")
+        return;
+    const { latest, minHonest } = signal;
+    recorded = { latest: clean(latest), minHonest: clean(minHonest) };
+}
+export function releaseSignal() {
+    return recorded;
+}
+/** Test seam only — the slot is process-global by design. */
+export function resetRelease() {
+    recorded = undefined;
+}
+/**
+ * Compare two versions: negative if a < b, 0 if equal, positive if a > b.
+ *
+ * Deliberately small. npm's `latest` dist-tag is a release, and this only ever compares
+ * against it, so full semver precedence would be dead code — but a PRERELEASE has to
+ * sort below its own release (`1.36.0-rc.1` < `1.36.0`) or someone testing an rc would
+ * be told they are ahead of the world and never hear about the real 1.36.0.
+ * Unparseable input answers 0, which reads as "no opinion" and keeps us silent.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(v.trim());
+        return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] } : null;
+    };
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return 0;
+    for (let i = 0; i < 3; i++)
+        if (x.nums[i] !== y.nums[i])
+            return x.nums[i] - y.nums[i];
+    if (x.pre === y.pre)
+        return 0;
+    if (x.pre === undefined)
+        return 1; // a release outranks any prerelease of itself
+    if (y.pre === undefined)
+        return -1;
+    return x.pre < y.pre ? -1 : 1;
+}
+/**
+ * The whole decision, with every edge injected so the interesting paths — no TTY, a
+ * root-owned prefix, a deployment too old to send the field — can be tested without
+ * owning a terminal, an npm prefix, or a backend.
+ */
+export async function offerUpdate(deps) {
+    const signal = deps.signal();
+    const latest = signal?.latest;
+    // No signal at all is the normal case for an old deployment or a cold cache, and it
+    // means exactly one thing: we do not know, so we do not speak.
+    if (!latest)
+        return "silent";
+    if (compareVersions(deps.version, latest) >= 0)
+        return "silent";
+    const now = deps.now();
+    const last = deps.lastNoticeAt();
+    if (last !== undefined && now - last < NOTICE_INTERVAL_MS)
+        return "silent";
+    // Stamp on PRINT, not on answer: someone who declines and someone who ignores the line
+    // have both been told today, and re-asking either tomorrow-minus-one-command is the
+    // nagging this gate exists to prevent. Stamped before the prompt so a Ctrl-C mid-question
+    // doesn't reset the clock either.
+    deps.stampNotice(now);
+    // Two different problems, said differently. "Newer exists" is an invitation; "your copy
+    // no longer matches the server" is a warning that what they just read may be false.
+    const dishonest = signal?.minHonest ? compareVersions(deps.version, signal.minHonest) < 0 : false;
+    if (dishonest) {
+        deps.out(`This retasc is ${deps.version}; ${latest} is published.`);
+        deps.out("  Its wording no longer matches how the server behaves, so what it tells you about your account may be out of date.");
+    }
+    else {
+        deps.out(`A newer retasc is available (${latest}, you have ${deps.version}).`);
+    }
+    // No TTY: the notice is the whole of it. A scripted run keeps behaving as it does today.
+    if (!deps.interactive()) {
+        deps.out(`  To update: ${MANUAL_INSTALL}`);
+        return "noticed";
+    }
+    if (!(await deps.ask("Update now?"))) {
+        deps.out(`  Left alone. To update later: ${MANUAL_INSTALL}`);
+        return "declined";
+    }
+    deps.out(`  Updating to ${latest}…`);
+    const failure = deps.install(latest);
+    if (failure) {
+        // NOT a failed command. Whatever they actually ran already succeeded above this line.
+        deps.out(`  Couldn't update (${failure}).`);
+        deps.out(`  To do it by hand: ${MANUAL_INSTALL}`);
+        return "install-failed";
+    }
+    // Say where it took effect, or the next thing they see will look like it didn't work:
+    // this process is still the OLD build, and every already-running agent is still pointed
+    // at the old MCP proxy. Same beat RTSC-519 added to `bind`.
+    deps.out(`  ✓ Updated to ${latest}. It applies from your next command — restart your agents to pick up the new MCP server.`);
+    return "installed";
+}
+/** The real-deps entry point. Never throws: a notice must not be able to fail a command. */
+export async function maybeOfferUpdate() {
+    try {
+        return await offerUpdate({
+            version: VERSION,
+            signal: releaseSignal,
+            interactive: isInteractive,
+            lastNoticeAt: () => loadConfig().updateNoticeAt,
+            stampNotice: (at) => patchConfig({ updateNoticeAt: at }),
+            ask: (q) => confirm(q),
+            install: installGlobal,
+            out: (line) => console.error(line),
+            now: () => Date.now(),
+        });
+    }
+    catch {
+        return "silent";
+    }
+}

package/package.json

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