@retasc/cli 1.4.0 → 1.6.0

package/dist/api.js

@@ -33,11 +33,49 @@ function client() {
         c.setAuth(cfg.token);
     return c;
 }
+/**
+ * Read a caught backend error into the parts a command wants to show (RTSC-261).
+ *
+ * `code` is machine-readable, so a command branches on `code === "EXPIRED"`
+ * instead of regex-matching prose that any copy edit would break. `hint` is the
+ * next step, kept separate so callers can dim or indent it.
+ *
+ * Both are optional because the sweep is incremental: a backend site still
+ * throwing a plain Error (or an OLD deployment this CLI is pointed at) yields
+ * `{message}` alone via the same first-line/strip-prefix cleanup used before.
+ * Callers must therefore keep any existing string fallback rather than assuming
+ * `code` is present.
+ */
+export function formatError(e) {
+    const data = e?.data;
+    if (data && typeof data === "object" && typeof data.message === "string") {
+        // Type-guard EVERY field, not just `message`: a foreign error carrying
+        // `{message: "x", code: {…}}` would otherwise print `✗ [object Object]: x`.
+        // And strip control characters — these strings go to `console.error`, so a
+        // future converted site that interpolates user data (issue ids, org names)
+        // must not be able to smuggle ANSI escapes into the terminal. Mirrors
+        // `sanitize` in convex/lib/userError.ts; the two are one wire contract.
+        const clean = (v) => 
+        // eslint-disable-next-line no-control-regex
+        typeof v === "string" ? v.replace(/[\x00-\x1f\x7f]/g, " ").trim() : undefined;
+        return { code: clean(data.code), message: clean(data.message), hint: clean(data.hint) };
+    }
+    const message = String(e?.message ?? e)
+        .split("\n")[0]
+        .replace(/^.*?Uncaught Error:\s*/, "")
+        .trim();
+    return { message };
+}
 // Does this error mean "the access token is missing/expired", i.e. a refresh
 // might fix it? The access-token JWT lives ~1h, so any long-lived login trips
 // this. Two shapes surface: our server functions throw `UNAUTHENTICATED …`
 // (requireUser), and the Convex platform rejects a stale JWT with "Could not
 // verify OIDC token"/"Unauthenticated". Match either, case-insensitively.
+// RTSC-261 deliberately does NOT touch this. It gates the refresh-and-retry
+// loop, no site converted here throws an auth code, and `formatError` truncates
+// to the first line — so routing it through there would add real risk (a missed
+// match means a spurious device-flow re-login) for no gain today. It gets a
+// `code === "UNAUTHENTICATED"` fast path in the PR that converts lib/auth.ts.
 export function isAuthError(e) {
     const msg = String(e?.message ?? e);
     return /unauthenticated|could not verify oidc|oidc token/i.test(msg);

package/dist/commands/billing.js

@@ -68,7 +68,7 @@ export async function billingAction(opts) {
     const c = charges;
     console.log(`\nBilling — ${orgLabel}\n`);
     console.log("SUBSCRIPTION");
-    row("Status", s.billingExempt ? "comp — not billed" : `${s.status}${s.gated ? " (gated)" : ""}`);
+    row("Status", `${s.status}${s.gated ? " (gated)" : ""}`);
     row("Subscription", s.subscriptionId ?? "none yet");
     if (s.spendingCapUsd != null) {
         row("Budget", `${usd(s.spendingCapUsd)}${s.capPeriod ? ` / ${s.capPeriod.replace("per_", "")}` : ""}`);

package/dist/commands/bind.js

@@ -4,7 +4,7 @@ import { api } from "../api.js";
 import { loadConfig } from "../config.js";
 import { installMarker } from "./mcp.js";
 import { readLocalBinding, resolveBinding } from "../lib/binding.js";
-import { setBinding, newWorkspaceId } from "../lib/keystore.js";
+import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
 function isInteractive() {
     return Boolean(stdin.isTTY && stdout.isTTY);
 }
@@ -42,8 +42,21 @@ export async function bindAction(opts) {
     const cfg = loadConfig();
     const cwd = process.cwd();
     // --- loud on re-bind -------------------------------------------------------
+    // markerOnly (a cloned repo's committed marker, or an entry the CLI can't
+    // read a key from) never gates: there is no usable binding to "replace", and
+    // minting a key under the existing marker id is exactly what bind is FOR.
     const existing = readLocalBinding(cwd);
-    if (existing) {
+    if (existing && !existing.markerOnly) {
+        // Idempotent converge (RTSC-262): re-running bind with the SAME target is
+        // success, not a refusal — a provisioning script must be able to run
+        // `retasc bind --org-id X --project-id Y` repeatedly without churning keys.
+        if (existing.workspaceId && opts.orgId && opts.projectId) {
+            const cur = getBinding(existing.workspaceId);
+            if (cur && cur.orgId === opts.orgId && cur.projectId === opts.projectId) {
+                console.log(`Already bound to the requested org/project (${cur.prefix ?? cur.projectId}). Nothing to do.`);
+                return;
+            }
+        }
         let where = "an existing Retasc binding";
         try {
             const b = await resolveBinding(existing.url || cfg.mcpUrl, existing.key);
@@ -54,7 +67,16 @@ export async function bindAction(opts) {
         }
         console.log(`This folder is already bound to ${where}.`);
         if (!(await confirm("Replace it?", opts.yes))) {
-            console.log("Left unchanged.");
+            // RTSC-262: with no TTY, confirm() answers "no" on its own — and the
+            // widened binding lookup makes an existing binding the COMMON case. A
+            // provisioning script must not be told success (exit 0) for a no-op.
+            if (!isInteractive()) {
+                console.error("✗ refusing to replace the existing binding (a DIFFERENT org/project) non-interactively — pass --yes.");
+                process.exitCode = 1;
+            }
+            else {
+                console.log("Left unchanged.");
+            }
             return;
         }
     }

package/dist/commands/doctor.js

@@ -1,49 +1,76 @@
-import { readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { loadConfig } from "../config.js";
-import { readLocalBinding, resolveBinding } from "../lib/binding.js";
+import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
 // RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
-// safely bound. Bound? Key valid (resolves to an org/project)? Watchdog wired?
-// And — the safety check — is there an illegal machine-global Retasc server that
-// could shadow per-folder bindings and leak issues across orgs?
+// safely bound. The question a human actually has is "which org/project does
+// this folder talk to?", so the healthy answer is ONE line naming them.
+//
+// RTSC-262: a binding is found in either legal per-folder location —
+// ./.mcp.json or Claude Code's local scope (the DEFAULT `claude mcp add`
+// writes). Reading only the former made doctor cry "not bound" about a working
+// binding, which teaches people to distrust everything else it says. When both
+// exist, we report the claude-local one (what Claude Code actually runs;
+// local > project) and warn if a shadowed folder marker disagrees. The
+// illegal-global check is presence-based and never prints an all-clear it
+// can't prove (unreadable config ≠ no global server).
 const ok = (m) => console.log(`  ✓ ${m}`);
 const warn = (m) => console.log(`  ! ${m}`);
 const bad = (m) => console.log(`  ✗ ${m}`);
-/** A user-scope (global) Retasc MCP server lives at the top level of
- * ~/.claude.json; per-folder ones live under projects[path]. A top-level one is
- * illegal under §13 — it would apply to every workspace. Best-effort detection. */
-function hasGlobalClaudeServer() {
-    const path = join(homedir(), ".claude.json");
-    if (!existsSync(path))
-        return false;
-    try {
-        const doc = JSON.parse(readFileSync(path, "utf8"));
-        return Boolean(doc?.mcpServers?.retasc);
-    }
-    catch {
-        return false;
-    }
-}
+// Server- and config-derived strings end up inside doctor's verdict lines; a
+// hostile endpoint (reachable via a config-supplied legacy url) must not be
+// able to smuggle ANSI escapes into the very output people trust for ✓/✗.
+const clean = (s) => String(s).replace(/[\x00-\x1f\x7f]/g, " ");
 export async function doctorAction() {
     const cfg = loadConfig();
     const cwd = process.cwd();
     console.log(`Retasc workspace check — ${cwd}\n`);
-    // 1) Is this folder bound?
+    // An override redirects BOTH the folder lookup and the global safety check,
+    // so its presence must be visible, not silent (it's a test hook, but nothing
+    // stops an .envrc or CI env from setting it).
+    if (process.env.RETASC_CLAUDE_CONFIG) {
+        warn(`RETASC_CLAUDE_CONFIG is set — inspecting ${claudeConfigPath()} instead of ~/.claude.json.`);
+    }
+    // 1) Which org/project does this folder talk to?
+    let networkDown = false;
     const local = readLocalBinding(cwd);
     if (!local) {
-        bad("not bound — no Retasc MCP server in ./.mcp.json. Run `retasc bind`.");
+        bad("not bound — no Retasc MCP server for this folder. Run `retasc bind`.");
     }
     else if (local.markerOnly) {
-        // RTSC-92: marker present (e.g. a cloned repo) but no key in this machine's
-        // keystore. Safe — the agent gets no tools — but the user must bind.
-        warn(`workspace marker present (${local.workspaceId}) but no key in your keystore.`);
-        bad("not usable yet on this machine — run `retasc bind` to mint your own key.");
+        if (local.workspaceId) {
+            // RTSC-92: marker present (e.g. a cloned repo) but no key in this
+            // machine's keystore. Safe — the agent gets no tools — but must bind.
+            warn(`workspace marker present (${clean(local.workspaceId)}) but no key in your keystore.`);
+            bad("not usable yet on this machine — run `retasc bind` to mint your own key.");
+        }
+        else {
+            // An entry is registered (and the runtime will use it) but carries no
+            // key material the CLI recognizes — likely hand-edited.
+            warn(`a Retasc server is registered for this folder (${local.source} scope) but the CLI can't read a key from it.`);
+            bad("not usable by the CLI — re-run `retasc bind` to rewrite it.");
+        }
     }
     else {
+        // The healthy path is a single line: bound, and to WHAT. Server-resolved so
+        // it's the same answer the agent gets, not a local guess.
+        try {
+            const b = await resolveBinding(local.url || cfg.mcpUrl, local.key);
+            ok(`bound — org "${clean(b.org.name)}" / project ${clean(b.project.prefix)} (${clean(b.project.name)}).`);
+        }
+        catch (e) {
+            const msg = clean(e?.message ?? e);
+            if (isNetworkError(e)) {
+                // 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}.`);
+            }
+            else {
+                bad(`key not accepted by the server: ${msg}. Re-run \`retasc bind\`.`);
+            }
+        }
+        // Caveats below the headline — each is a real risk, none is the common case.
         if (local.workspaceId) {
-            ok(`bound (secret-free marker → home keystore, ${local.workspaceId}).`);
             // The id resolved, but if it was bound at a different folder, this marker
             // may have reused someone else's id — surface it rather than silently use it.
             const entry = getBinding(local.workspaceId);
@@ -54,25 +81,47 @@ export async function doctorAction() {
             }
         }
         else if (local.legacy) {
-            ok("bound (legacy inline-key .mcp.json).");
-            warn("the key is stored IN this folder. Run `retasc bind` to move it to the keystore (secret-free marker).");
-        }
-        // 2) Does the key resolve to an org/project?
-        try {
-            const b = await resolveBinding(local.url || cfg.mcpUrl, local.key);
-            ok(`key valid → org "${b.org.name}" / project ${b.project.prefix} (${b.project.name}).`);
+            warn("the key is stored inline in the config. Run `retasc bind` to move it to the keystore.");
         }
-        catch (e) {
-            bad(`key not accepted by the server: ${String(e?.message ?? e)}. Re-run \`retasc bind\`.`);
+        // Bound in BOTH places with different identities: Claude Code uses the
+        // local-scope entry, so a stale committed ./.mcp.json marker would quietly
+        // mislead anyone reading the repo. Say which one wins. (Re-binding does NOT
+        // clear the folder marker — bind writes local scope — so the advice is to
+        // fix the marker itself.)
+        const shadowed = readShadowedBinding(cwd);
+        if (shadowed && !sameIdentity(local, shadowed)) {
+            warn(`./.mcp.json ALSO carries a Retasc binding, and it differs from the one in use.\n` +
+                `    Claude Code runs the local-scope entry (local > project); the folder marker is shadowed.\n` +
+                `    Remove the stale retasc entry from ./.mcp.json, or align it with the binding in use.`);
         }
     }
-    // 3) The safety check: any illegal global Retasc server?
-    if (hasGlobalClaudeServer()) {
-        bad("a GLOBAL Retasc MCP server is registered (~/.claude.json top level).\n" +
-            "    This applies to every workspace and can leak issues across orgs.\n" +
-            "    Remove it:  claude mcp remove -s user retasc");
+    // 2) The safety check: any illegal machine-global Retasc server?
+    const global = readGlobalBinding();
+    if (global.status === "none") {
+        ok("no illegal global Retasc server.");
+    }
+    else if (global.status === "unreadable") {
+        warn("could not parse Claude Code's config — cannot verify there is no global Retasc server\n" +
+            "    (a local-scope binding for this folder would be invisible too).");
     }
     else {
-        ok("no illegal global Retasc server.");
+        // Name the org it points at when we can: "leaks across orgs" is abstract,
+        // "every unbound folder gets org X" is what makes someone act. Presence
+        // alone is the finding — a keyless entry is still an illegal registration —
+        // and if the network already failed above, don't burn another timeout.
+        let points = "";
+        if (global.binding?.key && !networkDown) {
+            try {
+                const b = await resolveBinding(global.binding.url || cfg.mcpUrl, global.binding.key);
+                points = ` It points at org "${clean(b.org.name)}".`;
+            }
+            catch {
+                /* unresolvable (revoked/offline) — the registration is still illegal. */
+            }
+        }
+        bad(`GLOBAL Retasc server registered (Claude Code config, top level).${points}\n` +
+            `    It captures every folder on this machine that has no binding of its\n` +
+            `    own, so issues can land in the wrong project.\n` +
+            `    Fix:  claude mcp remove -s user retasc`);
     }
 }

package/dist/index.js

@@ -10,11 +10,11 @@ import { claimAction } from "./commands/claim.js";
 import { bindAction } from "./commands/bind.js";
 import { doctorAction } from "./commands/doctor.js";
 import { billingAction } from "./commands/billing.js";
-import { readLocalBinding, resolveBinding } from "./lib/binding.js";
+import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
 import { tidyAction, doneAction } from "./commands/tidy.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
-import { api } from "./api.js";
+import { api, formatError } from "./api.js";
 // Single source of truth for the version: read package.json at runtime from the
 // compiled file's location (dist/index.js -> ../package.json). A JSON import won't
 // work here — tsconfig has rootDir "src", so importing ../package.json is outside
@@ -31,9 +31,15 @@ function requireLogin() {
         process.exit(1);
     }
 }
+// RTSC-261: prefer the structured payload, and print `hint` on its own dimmed
+// line — the whole reason it's a separate field is that the fix shouldn't be
+// buried in the middle of the diagnosis. `formatError` falls back to the old
+// string cleanup, so unconverted backend sites print exactly as they did.
 function fail(e) {
-    const msg = String(e?.message ?? e).split("\n")[0].replace(/^.*?Uncaught Error:\s*/, "");
-    console.error(`✗ ${msg}`);
+    const { code, message, hint } = formatError(e);
+    console.error(`✗ ${code ? `${code}: ` : ""}${message}`);
+    if (hint)
+        console.error(`  → ${hint}`);
     process.exit(1);
 }
 // --- auth ------------------------------------------------------------------
@@ -80,7 +86,14 @@ program
             console.log(`             as ${b.member.name}${b.member.session ? ` · session ${b.member.session}` : ""}\n`);
         }
         catch (e) {
-            console.log(`This folder → bound, but the key did not resolve: ${String(e?.message ?? e)}\n`);
+            // Strip control chars — server-derived text must not smuggle ANSI
+            // escapes into trusted output (same rule as doctor's clean()).
+            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`);
+            else
+                console.log(`This folder → bound, but the key did not resolve: ${msg}\n`);
         }
     }
     else {

package/dist/lib/binding.js

@@ -1,19 +1,28 @@
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { getBinding } from "./keystore.js";
-/** Read the Retasc MCP entry from a folder's ./.mcp.json, if any. */
-export function readLocalBinding(dir) {
-    const path = join(dir, ".mcp.json");
+/** Claude Code's config file. RETASC_CLAUDE_CONFIG overrides it (tests). */
+export function claudeConfigPath() {
+    return process.env.RETASC_CLAUDE_CONFIG || join(homedir(), ".claude.json");
+}
+// "absent" and "unparseable" are different facts: an absent config proves no
+// global server; a corrupt one proves nothing, and a safety check must never
+// print an all-clear off a failed read (~/.claude.json is rewritten constantly,
+// so a truncated write is a realistic state, not a corner case).
+function readJson(path) {
     if (!existsSync(path))
-        return undefined;
-    let doc;
+        return { corrupt: false };
     try {
-        doc = JSON.parse(readFileSync(path, "utf8"));
+        return { doc: JSON.parse(readFileSync(path, "utf8")), corrupt: false };
     }
     catch {
-        return undefined;
+        return { corrupt: true };
     }
-    const s = doc?.mcpServers?.retasc;
+}
+/** Turn a raw MCP server entry into a binding. Shared by all sources — the
+ *  entry shape is identical wherever it is stored (see commands/mcp.ts). */
+function parseServerEntry(s, source) {
     if (!s)
         return undefined;
     // Canonical (RTSC-92): secret-free marker → resolve the key from the keystore.
@@ -21,23 +30,132 @@ export function readLocalBinding(dir) {
     if (workspaceId) {
         const entry = getBinding(workspaceId);
         if (entry)
-            return { key: entry.key, url: entry.url, watchdog: true, workspaceId };
+            return { key: entry.key, url: entry.url, watchdog: true, workspaceId, source };
         // Marker present but no keystore entry (e.g. a cloned repo) → needs binding.
-        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true };
+        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true, source };
     }
     // Legacy inline-key forms (pre-RTSC-92): key in env or the Authorization header.
     if (s.env?.RETASC_MCP_KEY) {
-        return { key: String(s.env.RETASC_MCP_KEY), url: String(s.env.RETASC_MCP_URL ?? ""), watchdog: true, legacy: true };
+        return {
+            key: String(s.env.RETASC_MCP_KEY),
+            url: String(s.env.RETASC_MCP_URL ?? ""),
+            watchdog: true,
+            legacy: true,
+            source,
+        };
     }
     const auth = s.headers?.Authorization ?? s.headers?.authorization;
     if (auth) {
         const m = String(auth).match(/^Bearer\s+(.+)$/i);
-        return { key: m ? m[1].trim() : String(auth).trim(), url: String(s.url ?? ""), watchdog: false, legacy: true };
+        return { key: m ? m[1].trim() : String(auth).trim(), url: String(s.url ?? ""), watchdog: false, legacy: true, source };
+    }
+    // An entry EXISTS but matches no shape we know. It still shadows lower scopes
+    // at runtime (Claude Code runs it regardless), so returning undefined here
+    // would let readLocalBinding fall back to a folder marker the agent is NOT
+    // using — the confident-wrong-org failure this module exists to prevent.
+    // Report presence without a key; doctor words it as "can't read a key".
+    return { key: "", url: "", watchdog: false, markerOnly: true, source };
+}
+/** The raw folder-scope (./.mcp.json) retasc entry, if any. */
+function folderEntry(dir) {
+    return readJson(join(dir, ".mcp.json")).doc?.mcpServers?.retasc;
+}
+/** The raw Claude-Code-local-scope retasc entry for a folder, if any.
+ *  Exported so the shared key resolver (claim.ts resolveMcpConn) sees the same
+ *  binding this module does — keeping doctor/whoami and claim/tidy/done in
+ *  lockstep (RTSC-98's "one place" rule extends to entry SELECTION too). */
+export function claudeLocalRetascEntry(dir) {
+    const projects = readJson(claudeConfigPath()).doc?.projects;
+    if (!projects)
+        return undefined;
+    const direct = projects[dir]?.mcpServers?.retasc;
+    if (direct)
+        return direct;
+    // Claude Code's projects key derivation is undocumented (raw cwd vs realpath,
+    // trailing slash). Cheap insurance: retry with both sides path-normalized —
+    // worst case it misses and we fail safe to "not bound", never to a wrong match.
+    const norm = (p) => {
+        const stripped = p.replace(/\/+$/, "") || "/";
+        try {
+            return realpathSync(stripped);
+        }
+        catch {
+            return stripped;
+        }
+    };
+    const want = norm(dir);
+    for (const k of Object.keys(projects)) {
+        // Only keys that actually CARRY a retasc entry are candidates — this both
+        // avoids an early return on an empty match (a trailing-slash twin with no
+        // entry must not mask a symlink twin that has one) and shrinks the
+        // realpathSync surface to the handful of retasc-bearing keys. First
+        // carrying match wins (deterministic per file order).
+        const e = projects[k]?.mcpServers?.retasc;
+        if (!e || k === dir)
+            continue;
+        if (norm(k) === want)
+            return e;
     }
     return undefined;
 }
+/** 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) {
+    const fromLocal = parseServerEntry(claudeLocalRetascEntry(dir), "claude-local");
+    if (fromLocal)
+        return fromLocal;
+    return parseServerEntry(folderEntry(dir), "folder");
+}
+/** The LOSING per-folder binding when a folder is bound in both places (the
+ *  ./.mcp.json marker shadowed by a claude-local entry). Doctor warns when the
+ *  two identities differ, so a stale committed marker can't mislead a team. */
+export function readShadowedBinding(dir) {
+    if (!claudeLocalRetascEntry(dir))
+        return undefined;
+    return parseServerEntry(folderEntry(dir), "folder");
+}
+/** A user-scope (global) Retasc server: top-level in Claude Code's config,
+ *  NOT under projects[dir]. Illegal under DESIGN §13 override #1 — it applies
+ *  to every folder that has no binding of its own, so issues can land in the
+ *  wrong project. `retasc bind` refuses to create one (normalizeScope); this
+ *  catches one added by hand with `claude mcp add -s user`. */
+export function readGlobalBinding() {
+    const { doc, corrupt } = readJson(claudeConfigPath());
+    if (corrupt)
+        return { status: "unreadable" };
+    const raw = doc?.mcpServers?.retasc;
+    if (!raw)
+        return { status: "none" };
+    return { status: "present", binding: parseServerEntry(raw, "global") };
+}
+/** Two per-folder bindings are the SAME binding if they agree on workspace id
+ *  (canonical form) or on the literal key (legacy forms). Anything else — or
+ *  not enough identity to compare — is a disagreement worth surfacing. */
+export function sameIdentity(a, b) {
+    if (a.workspaceId && b.workspaceId)
+        return a.workspaceId === b.workspaceId;
+    if (a.key && b.key)
+        return a.key === b.key;
+    return false;
+}
+/** True when resolveBinding failed WITHOUT delivering a verdict on the key —
+ *  the server was unreachable, timed out, threw 5xx, or rate-limited us. The
+ *  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) {
+    const name = String(e?.name ?? "");
+    if (name === "TimeoutError" || name === "AbortError")
+        return true;
+    const msg = String(e?.message ?? e);
+    const status = msg.match(/^MCP server returned (\d{3})$/);
+    if (status)
+        return Number(status[1]) >= 500 || Number(status[1]) === 429;
+    return /fetch failed|network|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT/i.test(msg);
+}
 /** Resolve a key's org/project by calling the MCP `whoami` tool (server-enforced
- * scope — the same banner the agent sees). Throws on an invalid/revoked key. */
+ * scope — the same banner the agent sees). Throws on an invalid/revoked key.
+ * Bounded: doctor is the tool people run when things are broken, so it must
+ * never hang on a dead network (RTSC-262 review). */
 export async function resolveBinding(url, key) {
     const res = await fetch(url, {
         method: "POST",
@@ -52,6 +170,7 @@ export async function resolveBinding(url, key) {
             method: "tools/call",
             params: { name: "whoami", arguments: {} },
         }),
+        signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok)
         throw new Error(`MCP server returned ${res.status}`);

package/dist/lib/claim.js

@@ -4,6 +4,7 @@
 // ../commands/claim.ts.
 import { readFileSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { claudeLocalRetascEntry } from "./binding.js";
 import { resolveConn } from "./keystore.js";
 // Tool-payload extraction lives in the shared tolerant parser (RTSC-143);
 // re-exported so existing importers of this module keep working.
@@ -19,9 +20,15 @@ const DEFAULT_MCP_URL = "https://mcp.retasc.com/mcp";
  * if nothing is found, so the caller can error clearly.
  */
 export function resolveMcpConn(opts = {}) {
+    // RTSC-262: the binding may live in Claude Code's local scope instead of
+    // ./.mcp.json (the `claude mcp add` DEFAULT). Select the same entry the
+    // runtime does — claude-local wins over the folder marker (local > project) —
+    // so claim/tidy/done can never disagree with doctor/whoami about whether a
+    // folder is bound. Explicit env (the proxy path) still wins inside resolveConn.
+    const localEntry = claudeLocalRetascEntry(opts.dir ?? process.cwd());
     const { key, url } = resolveConn({
         env: opts.env,
-        mcpEntry: opts.mcpJson?.mcpServers?.retasc,
+        mcpEntry: localEntry ?? opts.mcpJson?.mcpServers?.retasc,
         defaultUrl: opts.defaultUrl || DEFAULT_MCP_URL,
     });
     return { url: url || DEFAULT_MCP_URL, key };

package/dist/lib/keystore.js

@@ -60,26 +60,43 @@ export function newWorkspaceId() {
  * secret-free marker (`RETASC_WORKSPACE` → home keystore). `mcpEntry` is a
  * workspace `.mcp.json`'s `mcpServers.retasc` entry, or undefined when only the
  * environment carries the binding (the spawned proxy).
+ *
+ * URL trust pairs with key source (RTSC-262 review): a keystore-resolved key
+ * travels ONLY to the keystore's url (or explicit env url) — never to a url
+ * from the entry. The marker is secret-free and committed by design, so a
+ * hostile edit adding RETASC_MCP_URL next to RETASC_WORKSPACE must not be able
+ * to redirect a teammate's real key. Legacy inline entries keep their own url:
+ * there the key and url are co-located, same trust domain.
  */
 export function resolveConn(opts) {
     const env = opts.env ?? process.env;
     const entry = opts.mcpEntry;
     let key = env.RETASC_MCP_KEY || "";
     let url = env.RETASC_MCP_URL || "";
+    // Entry-supplied key/url are read together — the url is honored only when
+    // the key it's paired with is the one actually used.
+    let entryKey = "";
+    let entryUrl = "";
     if (entry) {
-        if (!key && typeof entry.env?.RETASC_MCP_KEY === "string")
-            key = entry.env.RETASC_MCP_KEY;
-        if (!url && typeof entry.env?.RETASC_MCP_URL === "string")
-            url = entry.env.RETASC_MCP_URL;
-        if (!url && typeof entry.url === "string")
-            url = entry.url;
-        if (!key && typeof entry.headers?.Authorization === "string") {
+        if (typeof entry.env?.RETASC_MCP_KEY === "string")
+            entryKey = entry.env.RETASC_MCP_KEY;
+        if (typeof entry.env?.RETASC_MCP_URL === "string")
+            entryUrl = entry.env.RETASC_MCP_URL;
+        if (!entryUrl && typeof entry.url === "string")
+            entryUrl = entry.url;
+        if (!entryKey && typeof entry.headers?.Authorization === "string") {
             const m = String(entry.headers.Authorization).match(/^Bearer\s+(.+)$/i);
             if (m)
-                key = m[1].trim();
+                entryKey = m[1].trim();
         }
     }
+    if (!key && entryKey) {
+        key = entryKey;
+        if (!url)
+            url = entryUrl;
+    }
     // Canonical (RTSC-92): secret-free marker → workspace id → home keystore.
+    // The entry's url is deliberately NOT consulted on this branch.
     if (!key) {
         const wsId = env.RETASC_WORKSPACE || entry?.env?.RETASC_WORKSPACE;
         if (wsId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {