@retasc/cli 1.48.0 → 1.49.0

package/CHANGELOG.md

@@ -6,6 +6,65 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.49.0 (2026-09-09)
+
+- **RTSC-879** — a committed `.mcp.json` now names `npx -y @retasc/cli@<version> mcp-proxy`
+  instead of a bare `retasc`, so it starts on a machine that is not the one that wrote it.
+  `portableLauncher` used to pass an on-PATH resolution straight through on the belief that
+  a bare binary "was at least portable"; it is portable only across machines that happen to
+  have a global install. A container has none. Measured in a Claude Code cloud session on a
+  fresh clone: the MCP server died at `ENOENT: Executable not found in $PATH: retasc` before
+  it could do anything else. Startup on the shared marker now pays npx resolution (about 6s
+  cold, ~1s off the cache); user-level configs, which never travel, keep the direct binary.
+- **RTSC-879** — `retasc bind --json` can now sign in from a container. An agent-driven
+  bind takes the DEVICE grant instead of the browser one, in two steps: the first call
+  prints an approve URL and an eight-character code and **exits**, the human approves on
+  any device, and running the same command again resumes the same grant and finishes.
+  Previously an agent got the browser door, which redirects to `127.0.0.1` on the machine
+  running the CLI — unreachable when the human is somewhere else, which in a cloud
+  container they always are. New continuable outcome state `SIGN_IN_PENDING` so an agent
+  can tell "waiting on a click" from "nothing has started" and does not issue a second
+  code that invalidates the one its human is reading. CI and `RETASC_NO_BROWSER` still
+  refuse immediately: neither has anyone to approve anything.
+- **RTSC-879** — `retasc doctor` no longer installs a package to check a marker. For an
+  npx marker it probes `npx --version` rather than executing the pinned package spec,
+  which was a registry fetch on every run and reported "your agent CANNOT start Retasc"
+  for a healthy marker whenever npm was unreachable. Its remedy line is corrected too: a
+  global install can no longer change what `bind` writes into a shared marker.
+- **RTSC-879** — the repo's own committed `.mcp.json`, and the marker blocks published in
+  `web/auth.md` and the agent-skill, now show the npx form. They were the bare binary,
+  which is the exact thing this release stops emitting. Those hand-written blocks say
+  `@latest` rather than a pinned version on purpose: `release:cli` publishes from `main`
+  AFTER a merge, so a committed marker pinning the version being released would 404 for
+  every fresh clone in the window between the two — trading this release's ENOENT for an
+  E404. `bind` still writes the pinned form, which is correct because it only ever names
+  a version that already exists.
+- **[no-issue]** — test fix: the setup-hook test pinned `RETASC_HOME` to a temp dir. It
+  fell through to the real home directory, so it passed on a clean CI runner and failed
+  on any machine that had actually run `retasc setup`.
+
+## 1.48.1 (2026-09-08)
+
+- **RTSC-878** — `retasc doctor` no longer condemns the entry `retasc setup` writes. Its
+  machine-global check dated from RTSC-91, when every top-level `mcpServers.retasc` carried
+  a key or a workspace id and so routed every unbound folder to one org; presence alone was
+  a correct test for that. RTSC-780 then made one global entry mandatory, the keyless `auto`
+  marker, which carries no identity at all, and the check was never taught the difference.
+  Doctor therefore printed `✗ GLOBAL Retasc server registered` at the marker and offered
+  `claude mcp remove -s user retasc` as the fix, which strips Retasc from every folder
+  without a binding of its own. It cost a customer a day.
+- The check now reads the entry's identity: `RETASC_WORKSPACE=auto` with no key resolved is
+  reported as correct and named, so someone who just ran `setup` can see that what it wrote
+  is what belongs there. Every other shape stays illegal, including a keyless entry that
+  names a real `ws_` workspace, which still routes every unbound folder to one binding.
+- The exemption is not granted on the sentinel alone. `parseServerEntry` reads
+  `RETASC_WORKSPACE` before it looks for a key in an `Authorization` header or in
+  `RETASC_MCP_KEY`, so an entry carrying both the `auto` sentinel and a real credential
+  parses as an innocent keyless marker; judging the parse alone would have exempted a live
+  machine-global registration pointing every unbound folder at that key's org. The raw
+  entry is examined too, and anything carrying credential material or a `url` of its own
+  stays illegal whatever its `env` claims.
+
 ## 1.48.0 (2026-09-08)
 
 - **RTSC-859** — `retasc key mint --hosted`: a key now says at mint what it is for.

package/dist/auth.js

@@ -287,6 +287,123 @@ async function browserLogin(deploymentUrl, dashUrl, onUrl) {
     // what actually worked.
     patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
 }
+/** Ask the provider for a code. Returns immediately; nobody waits here. */
+export async function deviceStart(provider, deploymentUrl) {
+    if (provider === "google") {
+        const convex = new ConvexHttpClient(deploymentUrl);
+        const start = (await convex.action(googleDeviceStart, {}));
+        return {
+            provider,
+            deploymentUrl,
+            deviceCode: start.deviceCode,
+            userCode: start.userCode,
+            verificationUri: start.verificationUrl,
+            ...(start.verificationUrlComplete
+                ? { verificationUriComplete: start.verificationUrlComplete }
+                : {}),
+            intervalMs: (start.intervalSeconds || 5) * 1000,
+            expiresAt: Date.now() + start.expiresInSeconds * 1000,
+        };
+    }
+    if (!GITHUB_CLIENT_ID) {
+        throw new Error("GitHub client id not configured. Set RETASC_GITHUB_CLIENT_ID (the OAuth App's public Client ID).");
+    }
+    const start = await postForm(DEVICE_CODE_URL, {
+        client_id: GITHUB_CLIENT_ID,
+        scope: "read:user user:email",
+    });
+    if (!start.device_code) {
+        // Same rule as `githubDeviceToken`: quote what GitHub WROTE for a person, never the
+        // raw payload.
+        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 try again.`);
+    }
+    return {
+        provider,
+        deploymentUrl,
+        deviceCode: start.device_code,
+        userCode: start.user_code,
+        verificationUri: start.verification_uri,
+        ...(start.verification_uri_complete
+            ? { verificationUriComplete: start.verification_uri_complete }
+            : {}),
+        intervalMs: (start.interval || 5) * 1000,
+        expiresAt: Date.now() + start.expires_in * 1000,
+    };
+}
+/**
+ * Poll an already-started grant for at most `budgetMs`, and sign in if it completed.
+ *
+ * BOUNDED ON PURPOSE. The caller is an agent, and an agent that blocks for the grant's
+ * full fifteen minutes is the very failure this split exists to avoid. `false` means
+ * "not yet, ask again" — the human has not clicked — and is not an error. Anything
+ * genuinely terminal (denied, expired, a misconfigured client) throws, because those
+ * cannot be fixed by asking again and an agent must be told to stop rather than loop.
+ */
+export async function deviceFinish(pending, deploymentUrl, budgetMs) {
+    const convex = new ConvexHttpClient(deploymentUrl);
+    let intervalMs = pending.intervalMs || 5000;
+    const stopAt = Math.min(Date.now() + budgetMs, pending.expiresAt);
+    let upstream;
+    while (Date.now() < stopAt) {
+        // Never poll SOONER than the provider asked. Clamping the sleep to the remaining
+        // budget would do exactly that on the last iteration — and after a `slow_down` that
+        // interval is the provider telling us to back off. Stop instead; the caller
+        // re-enters on its next invocation anyway.
+        const wait = Math.min(intervalMs, Math.max(0, stopAt - Date.now()));
+        if (wait < intervalMs)
+            break;
+        await sleep(wait);
+        if (Date.now() > pending.expiresAt)
+            break;
+        if (pending.provider === "google") {
+            const r = (await convex.action(googleDevicePoll, { deviceCode: pending.deviceCode }));
+            if (r.status === "ok") {
+                upstream = r.googleToken;
+                break;
+            }
+            if (r.status === "slowDown")
+                intervalMs += 5000;
+            continue;
+        }
+        const r = await postForm(TOKEN_URL, {
+            client_id: GITHUB_CLIENT_ID,
+            device_code: pending.deviceCode,
+            grant_type: GRANT,
+        });
+        if (r.access_token) {
+            upstream = r.access_token;
+            break;
+        }
+        if (r.error === "authorization_pending")
+            continue;
+        if (r.error === "slow_down") {
+            intervalMs += 5000;
+            continue;
+        }
+        throw new Error(`Authorization failed: ${clean(String(r.error_description ?? r.error))}`);
+    }
+    if (!upstream) {
+        if (Date.now() >= pending.expiresAt) {
+            throw new Error("The sign-in code expired before it was approved. Start again.");
+        }
+        return false;
+    }
+    const res = await convex.action(signIn, {
+        provider: pending.provider === "google" ? "google-device" : "github-device",
+        params: pending.provider === "google" ? { googleToken: upstream } : { githubToken: upstream },
+    });
+    const tokens = res?.tokens;
+    if (!tokens?.token)
+        throw new Error("Sign-in did not return a session token.");
+    patchConfig({
+        token: tokens.token,
+        refreshToken: tokens.refreshToken,
+        loginProvider: pending.provider,
+    });
+    return true;
+}
 /**
  * Run a device-flow login and persist the resulting Convex Auth session to
  * ~/.retasc/config.json. Prints the user code + verification URL.

package/dist/commands/bind.js

@@ -1,6 +1,6 @@
 import { basename } from "node:path";
 import { api, cliError } from "../api.js";
-import { deviceLogin } from "../auth.js";
+import { deviceLogin, deviceStart, deviceFinish } from "../auth.js";
 import { loadConfig, patchConfig } from "../config.js";
 import { installMarker, printMarkerBlock } from "./mcp.js";
 import { runSetup } from "./setup.js";
@@ -730,6 +730,30 @@ export const NEXT_STEP = "Start your agent in this folder, or restart it if it's
  * because "run this, but run the other one first" is not a single instruction. So the
  * sign-in is explicit, announced, and only when a human is present to authorize it.
  */
+/**
+ * RTSC-879 — thrown when a device grant has been started and the human has not approved
+ * it yet. NOT a failure: `bindAction` turns it into a CONTINUABLE outcome, because the
+ * only thing missing is a click that has not happened yet.
+ */
+/**
+ * How long a resuming `bind --json` waits for the click before handing control back.
+ *
+ * Ninety seconds is chosen against the agent's loop, not the human's: long enough that
+ * a human who clicks while the agent is still talking is picked up on the same call,
+ * short enough that a run never looks hung. Being wrong is cheap in one direction only
+ * — too short just means one more `bind --json`, too long means an agent that looks
+ * dead — so it errs short.
+ */
+const RESUME_POLL_MS = 90_000;
+export class SignInPending extends Error {
+    url;
+    code;
+    constructor(url, code) {
+        super("sign-in pending: waiting for approval");
+        this.url = url;
+        this.code = code;
+    }
+}
 export async function ensureSignedIn(agent) {
     if (loadConfig().token)
         return;
@@ -750,11 +774,81 @@ export async function ensureSignedIn(agent) {
         // would itself fail silently.
         cliError("UNAUTHENTICATED", `Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`, versionStamp(VERSION).trim());
     }
+    // RTSC-879 — an AGENT always takes the device door, and takes it in two steps.
+    //
+    // Not the browser door, which is what an agent-driven run used to get. That door sends
+    // the human to a URL redirecting to `127.0.0.1` on THIS machine, so it only works when
+    // the browser and the CLI share a host. An agent's human may be anywhere, and in a
+    // cloud container they always are, so the click lands on a port nobody can reach and
+    // the CLI waits out its timeout. `canOpenBrowser` does not catch that: it looks for
+    // SSH, CI and an explicit opt-out, and a cloud container sets none of them, so it
+    // reports a browser that is not there. A device grant does not care where the human
+    // is, which is why it is the door for every agent rather than a fallback for some.
+    //
+    // Two steps because one does not work: an agent running a blocking command sees no
+    // stdout until the process exits, so a code printed above a fifteen-minute wait
+    // reaches nobody. START prints and exits; the next `bind --json` FINISHes.
+    if (agent) {
+        // Two doors stay shut, and only two. A device grant works wherever the human is, so
+        // SSH and a container are no longer dead ends — but neither of these is about WHERE
+        // the human is:
+        //   • CI has nobody watching at all. A code emitted there is read by no one and the
+        //     run would ask for it again forever.
+        //   • RETASC_NO_BROWSER is a person saying "do not put me through browser auth". A
+        //     device grant is still browser auth, just on a different device, so honouring
+        //     the switch means honouring it here too.
+        if (process.env.CI || process.env.RETASC_NO_BROWSER) {
+            throw new Error("no browser door here: " +
+                (process.env.CI
+                    ? "this is CI, and a sign-in code needs a human to approve it. Mint a key on a machine with a browser and set RETASC_MCP_KEY instead."
+                    : "RETASC_NO_BROWSER is set. Unset it, or sign in on another machine and bind there."));
+        }
+        const cfg = loadConfig();
+        // A grant started against a DIFFERENT backend is not resumable here: Google's half
+        // lives in Convex, so polling another deployment asks a server about a code it never
+        // issued. Treat it as absent and start a fresh one.
+        const stored = cfg.pendingDevice && (cfg.pendingDevice.deploymentUrl ?? cfg.deploymentUrl) === cfg.deploymentUrl
+            ? cfg.pendingDevice
+            : undefined;
+        // Resume an approval already in flight. Bounded: `deviceFinish` returns false rather
+        // than holding the process open, so every invocation ends promptly whatever the
+        // human is doing.
+        if (stored && Date.now() < stored.expiresAt) {
+            let done;
+            try {
+                done = await deviceFinish(stored, cfg.deploymentUrl, RESUME_POLL_MS);
+            }
+            catch (e) {
+                // TERMINAL, so the grant must go. `deviceFinish` throws only on things retrying
+                // cannot fix — the human declined, the code expired, the client is misconfigured
+                // — and a dead grant left in the config is re-loaded by the branch above on every
+                // later run, which would rethrow the same refusal forever and leave no way to
+                // start a new one short of editing the file by hand.
+                patchConfig({ pendingDevice: undefined });
+                throw e;
+            }
+            if (done) {
+                patchConfig({ pendingDevice: undefined });
+                return;
+            }
+            throw new SignInPending(stored.verificationUriComplete || stored.verificationUri, stored.userCode);
+        }
+        // No grant, or the last one died of old age, or it belongs to another deployment.
+        // Clear before starting rather than relying on the write below to overwrite it: if
+        // `deviceStart` throws, a dead grant left behind would be re-read on the next run.
+        if (cfg.pendingDevice)
+            patchConfig({ pendingDevice: undefined });
+        const started = await deviceStart(cfg.loginProvider ?? "github", cfg.deploymentUrl);
+        patchConfig({ pendingDevice: started });
+        const url = started.verificationUriComplete || started.verificationUri;
+        agent.onDeviceCode?.({ url, code: started.userCode });
+        throw new SignInPending(url, started.userCode);
+    }
     // RTSC-508: don't name a provider here. `deviceLogin` asks which door, and
     // announcing "GitHub" before the question would be wrong for the invited
     // teammate who signed up through Google — the exact person `join` is for.
     console.error("Not signed in yet — let's do that first.");
-    await deviceLogin(undefined, agent ? { agentDriven: true, onUrl: agent.onUrl } : undefined);
+    await deviceLogin(undefined);
 }
 export async function bindAction(opts) {
     // RTSC-713 — `--json` is the signal that a machine is driving, and it turns three
@@ -763,7 +857,14 @@ export async function bindAction(opts) {
     // independently useful: structured output nobody can act on, or a door that leads to a
     // thrown Error, is each worse than neither.
     const agent = opts.json
-        ? { onUrl: (url) => emit({ event: "approve_url", url }) }
+        ? {
+            onUrl: (url) => emit({ event: "approve_url", url }),
+            // RTSC-879 — the device grant emits the SAME event, plus the code. Without this
+            // the URL reached an agent only inside the outcome's free-text `next`, so a
+            // client parsing NDJSON (which is what `--json` is for) lost the one field it
+            // was watching for.
+            onDeviceCode: (d) => emit({ event: "approve_url", url: d.url, code: d.code }),
+        }
         : undefined;
     const folder = process.cwd();
     // RTSC-722 — the escape option's value is a sentinel, and this is where it stops being
@@ -808,6 +909,21 @@ export async function bindAction(opts) {
     catch (e) {
         if (!agent)
             throw e;
+        // RTSC-879 — started, not failed. The only missing thing is a click, so this is
+        // CONTINUABLE: exit 0, tell the agent what to show its human, and let the next
+        // `bind --json` resume the same grant. Reported as a failure it would read as
+        // "this cannot work here", which is exactly backwards.
+        if (e instanceof SignInPending) {
+            pause({
+                state: "SIGN_IN_PENDING",
+                next: `Sign-in has started and is waiting for your human. Show them BOTH of these, ` +
+                    `then run this same command again once they say they have approved it:\n` +
+                    `  Open: ${e.url}\n  Enter code: ${e.code}\n` +
+                    `They can open it on any device — a phone, another laptop — it does not have ` +
+                    `to be this machine.`,
+            });
+            return;
+        }
         // Sign-in was ATTEMPTED and did not complete. Distinct from arriving with no session,
         // which is continuable — collapsing the two is what made the old refusal stop agents
         // that had actually succeeded.

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "../config.js";
 import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
-import { getBinding } from "../lib/keystore.js";
+import { AUTO_WORKSPACE, getBinding } from "../lib/keystore.js";
 import { gitCommonDir } from "../lib/gitRepo.js";
 import { detectHarnesses } from "../lib/harness.js";
 import { runsOk } from "../lib/launcher.js";
@@ -16,8 +16,9 @@ import { clean } from "../lib/text.js";
 // 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).
+// illegal-global check reads the entry's IDENTITY, not merely its presence
+// (RTSC-878), 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}`);
@@ -43,11 +44,89 @@ export function launcherVerdict(local, probe = runsOk) {
     // The stored args end in `mcp-proxy` (the subcommand). Probe the LAUNCHER, so drop it.
     const args = local.args ?? [];
     const probeArgs = args[args.length - 1] === "mcp-proxy" ? args.slice(0, -1) : args;
+    // RTSC-879 — an npx marker is probed by asking whether NPX runs, never by running the
+    // package spec. `runsOk` executes what it is handed, so probing `npx -y @retasc/cli@X`
+    // means a registry fetch and an install on every `doctor` — slow when it works, and a
+    // false "your agent CANNOT start Retasc" the moment the machine is offline or npm is
+    // unreachable. What this check is actually asking is whether the LAUNCHER exists, and
+    // for the npx form that question is answered by `npx --version`.
+    //
+    // WHAT THIS STOPS CHECKING, said out loud: it proves the launcher exists and nothing
+    // about the pinned spec. A version that is not on npm, a registry behind a proxy, or a
+    // corrupt npx cache all read as healthy here while the server dies at startup. That is
+    // the deliberate trade — a false "CANNOT start" every time someone is offline is worse
+    // than a rare false "can" — but since 1.49.0 every shared marker is this form, so it
+    // is a blind spot on the common path, not an edge one.
+    if (local.command === "npx") {
+        return {
+            startable: Boolean(probe("npx", ["--version"])),
+            shown: clean([local.command, ...probeArgs].join(" ")),
+        };
+    }
     return {
         startable: Boolean(probe(local.command, probeArgs)),
         shown: clean([local.command, ...probeArgs].join(" ")),
     };
 }
+/**
+ * RTSC-878: is the machine-global entry a real registration, or the marker `setup` writes?
+ *
+ * The old rule was presence alone, and it was correct when it was written (RTSC-91): every
+ * top-level `mcpServers.retasc` then carried a key or a workspace id, so any of them routed
+ * every unbound folder on the disk to one org. RTSC-780 changed that world by making ONE
+ * global entry mandatory, the keyless `auto` marker, which carries no identity at all: the
+ * proxy resolves the folder it was spawned in and the org still comes from the folder.
+ *
+ * Doctor kept the old rule and so told people to delete what `retasc setup` had just
+ * installed. Following that advice strips Retasc from every folder without a binding of its
+ * own, and it happened to a real customer before this was fixed.
+ *
+ * The test is the marker's OWN sentinel rather than a shape heuristic: `RETASC_WORKSPACE`
+ * is `auto` and no key resolved from it. Workspace ids are `ws_`-prefixed uuids
+ * (`keystore.ts`), so `auto` can never be one, and an entry naming a real workspace stays
+ * illegal exactly as before.
+ *
+ * The sentinel alone is NOT enough, and this is the trap the exemption has to survive.
+ * `parseServerEntry` reads `RETASC_WORKSPACE` BEFORE it looks for a key in an
+ * `Authorization` header or in `RETASC_MCP_KEY`, so an entry that carries BOTH the `auto`
+ * sentinel and a real credential parses as an innocent keyless marker. That shape is a
+ * live machine-global registration pointing every unbound folder at whatever org its key
+ * names, which is the exact fault this check exists to catch, and it is not theoretical:
+ * `lib/harness.ts` records an agent hand-writing a machine-global entry with an inline key.
+ * So the raw entry is examined too, and anything carrying credential material or its own
+ * endpoint is illegal no matter what its `env` claims.
+ */
+export function globalVerdict(global) {
+    if (global.status === "none")
+        return "clear";
+    if (global.status === "unreadable")
+        return "unreadable";
+    const b = global.binding;
+    if (b && b.workspaceId === AUTO_WORKSPACE && !b.key && isBareMarker(global.raw))
+        return "auto";
+    return "illegal";
+}
+/**
+ * Does the entry as written carry nothing but the `auto` sentinel?
+ *
+ * Deliberately a DENYLIST of credential-bearing and endpoint-bearing fields rather than an
+ * exact-shape match: `setup` may add a field to the marker later (it already grew `env`
+ * once), and an exemption that broke on every such addition would be reverted rather than
+ * updated. What must never be exempt is an entry that can reach a server on its own terms:
+ * a key in `env`, a key in a header, or a `url` of its own.
+ */
+function isBareMarker(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const e = raw;
+    if (e.url !== undefined)
+        return false;
+    if (e.headers !== undefined)
+        return false;
+    if (e.env && typeof e.env === "object" && e.env.RETASC_MCP_KEY !== undefined)
+        return false;
+    return true;
+}
 /**
  * RTSC-498: macOS is the only platform this CLI is tested on. That was true and written
  * down nowhere, which left someone on Linux or Windows unable to tell their own mistake
@@ -89,10 +168,19 @@ function checkLauncher(local) {
         ok(`your agent can start Retasc (${v.shown}).`);
         return;
     }
-    bad(`your agent CANNOT start Retasc — this folder is registered to run "${v.shown}",\n` +
-        `    which doesn't run on this machine. The binding itself is fine; the command is missing.\n` +
-        `    This is what a bind through npx used to leave behind.\n` +
-        `    Fix:  npm install -g @retasc/cli   then re-run \`retasc bind\` here.`);
+    // RTSC-879 — the remedy differs by form, because a global install no longer changes
+    // what `bind` writes into a SHARED marker: `portableLauncher` emits the npx form for
+    // every resolution now, so "install it globally and re-bind" would rewrite the
+    // identical entry and fix nothing.
+    bad(local?.command === "npx"
+        ? `your agent CANNOT start Retasc — this folder is registered to run "${v.shown}",\n` +
+            `    and npx itself did not run here. That is a Node/npm problem, not a Retasc one.\n` +
+            `    Fix:  make sure \`npx --version\` works, then try again. If this machine is\n` +
+            `          offline or npm is unreachable, that is the cause and nothing is broken.`
+        : `your agent CANNOT start Retasc — this folder is registered to run "${v.shown}",\n` +
+            `    which doesn't run on this machine. The binding itself is fine; the command is missing.\n` +
+            `    Fix:  re-run \`retasc bind\` here — it now writes a portable npx entry that\n` +
+            `          starts on any machine with Node, including one with no global install.`);
 }
 export async function doctorAction() {
     const cfg = loadConfig();
@@ -192,22 +280,34 @@ export async function doctorAction() {
     }
     // 2) The safety check: any illegal machine-global Retasc server?
     const global = readGlobalBinding();
-    if (global.status === "none") {
+    // Pulled out once: the verdict below is computed from the same entry, and reading it
+    // through the union again inside a branch loses the `present` narrowing.
+    const entry = global.status === "present" ? global.binding : undefined;
+    const verdict = globalVerdict(global);
+    if (verdict === "clear") {
         ok("no illegal global Retasc server.");
     }
-    else if (global.status === "unreadable") {
+    else if (verdict === "auto") {
+        // RTSC-878: the entry `retasc setup` writes, and the one state doctor used to
+        // condemn. Named rather than passed over in silence: someone who just ran `setup`
+        // should see that the thing it wrote is the thing that is supposed to be there.
+        ok("machine-wide Retasc entry is the keyless `auto` marker `retasc setup` writes;\n" +
+            "    it names no org, so every folder still resolves its own binding.");
+    }
+    else if (verdict === "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 {
         // 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.
+        // "every unbound folder gets org X" is what makes someone act. A keyless entry
+        // that names a WORKSPACE is still illegal (it routes every unbound folder to that
+        // one binding); only the identity-free `auto` marker above is not. If the network
+        // already failed above, don't burn another timeout.
         let points = "";
-        if (global.binding?.key && !networkDown) {
+        if (entry?.key && !networkDown) {
             try {
-                const b = await resolveBinding(global.binding.url || cfg.mcpUrl, global.binding.key);
+                const b = await resolveBinding(entry.url || cfg.mcpUrl, entry.key);
                 points = ` It points at org "${clean(b.org.name)}".`;
             }
             catch {

package/dist/config.js

@@ -74,6 +74,48 @@ export function loadConfig() {
         updateNoticeAt: typeof stored.updateNoticeAt === "number" && Number.isFinite(stored.updateNoticeAt)
             ? stored.updateNoticeAt
             : undefined,
+        // RTSC-879 — and it MUST be here. `loadConfig` rebuilds the object field by field, so
+        // a field absent from this literal is invisible to every reader no matter what is on
+        // disk. Left out, `bind --json` never saw the grant it had just written: it minted a
+        // fresh code on every call, invalidating the one the human was reading, and exited 0
+        // forever. The whole suite stayed green because nothing round-tripped the grant
+        // through the config, which is why the test below does exactly that.
+        //
+        // Validated, same rule as the fields above: the file is hand-editable, and this one
+        // is fed straight to a polling loop. An unrecognised provider must not fall through
+        // to GitHub's branch by default, and a non-finite `expiresAt` would make the grant
+        // either immortal or already dead.
+        pendingDevice: readPendingDevice(stored.pendingDevice),
+    };
+}
+/** A stored device grant, or `undefined` if it is anything other than a complete one. */
+function readPendingDevice(v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const str = (x) => (typeof x === "string" && x.length > 0 ? x : undefined);
+    const provider = v.provider === "github" || v.provider === "google" ? v.provider : undefined;
+    const deviceCode = str(v.deviceCode);
+    const userCode = str(v.userCode);
+    const verificationUri = str(v.verificationUri);
+    const expiresAt = typeof v.expiresAt === "number" && Number.isFinite(v.expiresAt) ? v.expiresAt : undefined;
+    if (!provider || !deviceCode || !userCode || !verificationUri || expiresAt === undefined) {
+        return undefined;
+    }
+    // A negative or absent interval would busy-poll a provider that asked us not to.
+    const intervalMs = typeof v.intervalMs === "number" && Number.isFinite(v.intervalMs) && v.intervalMs > 0
+        ? v.intervalMs
+        : 5000;
+    return {
+        provider,
+        deviceCode,
+        userCode,
+        verificationUri,
+        ...(str(v.verificationUriComplete)
+            ? { verificationUriComplete: v.verificationUriComplete }
+            : {}),
+        intervalMs,
+        expiresAt,
+        ...(str(v.deploymentUrl) ? { deploymentUrl: v.deploymentUrl } : {}),
     };
 }
 /** Move a corrupt config aside to a unique sibling so a human can recover any

package/dist/lib/binding.js

@@ -213,7 +213,7 @@ export function readGlobalBinding() {
     const raw = doc?.mcpServers?.retasc;
     if (!raw)
         return { status: "none" };
-    return { status: "present", binding: parseServerEntry(raw, "global") };
+    return { status: "present", binding: parseServerEntry(raw, "global"), raw };
 }
 /** 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

package/dist/lib/launcher.js

@@ -117,18 +117,35 @@ export function globalBinCandidates(prefix, win = WIN) {
         : [join(prefix, "bin", "retasc")];
 }
 /**
- * A launcher safe to write into a SHARED file.
+ * A launcher safe to write into a SHARED file. ALWAYS the pinned npx form.
  *
  * The absolute-path form is correct for the machine that resolved it and wrong everywhere
  * else: `./.mcp.json` is the secret-free marker the product describes as safe to commit,
  * so a path under someone's home directory both leaks their username into a committed
- * file and hands every teammate a command that does not exist on their machine. The bare
- * `retasc` it replaces was at least portable. So project-scoped writes get the pinned npx
- * form, which is slower but true on any machine.
+ * file and hands every teammate a command that does not exist on their machine.
+ *
+ * RTSC-879 — the bare `retasc` is NOT the safe fallback this function used to treat it as.
+ * The old comment here said it "was at least portable", and that is only true across
+ * machines that happen to have a global install. A container has none. Measured
+ * 2026-09-09 in a Claude Code cloud session on a fresh clone of this repo: the committed
+ * marker said `command: "retasc"`, and the MCP server died at
+ * `ENOENT: Executable not found in $PATH: retasc` before it could do anything else. That
+ * marker was written by a laptop where `resolveLauncher` found the binary on a durable
+ * PATH and returned `how: "on-path"`, which this function then passed straight through as
+ * though on-PATH-here meant on-PATH-anywhere.
+ *
+ * So there is no `how` worth preserving. `absolute` names a path nobody else has,
+ * `on-path` and `installed` name a binary nobody else is guaranteed to have, and this
+ * file is committed ON PURPOSE (see `.gitignore`, and the pre-commit guard that keeps it
+ * secret-free). The only form true on every machine is the pinned npx one.
+ *
+ * COST, stated plainly: sessions using the committed marker now pay npx resolution at
+ * startup — about 6s cold, and roughly a second warm off the npx cache. That is the price
+ * of a marker that starts at all on a machine that is not the one that wrote it, and it
+ * is paid ONLY here. `resolveLauncher`'s fast direct form is still what goes into
+ * user-level configs, which never travel.
  */
-export function portableLauncher(r, version) {
-    if (r.how !== "absolute")
-        return r.launcher;
+export function portableLauncher(_r, version) {
     return { command: "npx", args: ["-y", `${PKG}@${version}`] };
 }
 /**

package/dist/lib/outcome.js

@@ -66,6 +66,15 @@ import { homedir } from "node:os";
 export const CONTINUABLE_STATES = [
     /** No session, and no attempt has been made yet. The browser door is available. */
     "NEEDS_SIGN_IN",
+    /**
+     * RTSC-879 — a device grant HAS been started and is waiting on the human's click.
+     *
+     * Continuable, and the distinction from `NEEDS_SIGN_IN` is the whole point: there,
+     * nothing has happened and the agent should begin. Here a code is live, the human has
+     * been handed it, and re-starting would issue a second code that invalidates the one
+     * they are looking at. The agent's move is to run the same command again, unchanged.
+     */
+    "SIGN_IN_PENDING",
     /** Signed in. Zero orgs, or more than one, so which org this folder is for is unknown. */
     "NEEDS_ORG",
     /** Org settled. Zero projects, or more than one, so which project is unknown. */

package/package.json

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