@retasc/cli 1.7.2 → 1.9.0

package/dist/api.js

@@ -25,6 +25,12 @@ const fns = {
     billingStatus: makeFunctionReference("manage:billingStatus"),
     chargeHistory: makeFunctionReference("manage:chargeHistory"),
     orgPayments: makeFunctionReference("manage:orgPayments"),
+    // Imported-identity claim (RTSC-433/473), wired for `join` by RTSC-492 and shared with
+    // RTSC-477's standalone `retasc identity`. Member-gated already — nothing was widened
+    // server-side for the CLI, and nothing should be.
+    claimableGhosts: makeFunctionReference("ghosts:claimableGhosts"),
+    claimGhost: makeFunctionReference("ghosts:claimGhost"),
+    dismissGhostPrompt: makeFunctionReference("ghosts:dismissGhostPrompt"),
 };
 function client() {
     const cfg = loadConfig();
@@ -66,6 +72,20 @@ export function formatError(e) {
         .trim();
     return { message };
 }
+/**
+ * Fail the same way the backend does (RTSC-492).
+ *
+ * `formatError` truncates a bare Error to its FIRST line, so a multi-line message loses
+ * everything after the diagnosis — including the command that fixes it. Some of the stops
+ * the CLI has to make are its own (an org with no projects the caller may not create),
+ * with no server call to produce a `userError`, and they deserve the same code + message +
+ * hint rendering as one that came off the wire.
+ */
+export function cliError(code, message, hint) {
+    const e = new Error(`${code}: ${message}`);
+    e.data = { code, message, hint };
+    throw e;
+}
 // 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 …`
@@ -139,4 +159,7 @@ export const api = {
     billingStatus: (args) => withAuth(() => client().query(fns.billingStatus, args)),
     chargeHistory: (args) => withAuth(() => client().query(fns.chargeHistory, args)),
     orgPayments: (args) => withAuth(() => client().action(fns.orgPayments, args)),
+    claimableGhosts: (args) => withAuth(() => client().query(fns.claimableGhosts, args)),
+    claimGhost: (args) => withAuth(() => client().mutation(fns.claimGhost, args)),
+    dismissGhostPrompt: (args) => withAuth(() => client().mutation(fns.dismissGhostPrompt, args)),
 };

package/dist/commands/bind.js

@@ -1,14 +1,18 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
-import { api } from "../api.js";
+import { api, cliError } from "../api.js";
+import { deviceLogin } from "../auth.js";
 import { loadConfig } from "../config.js";
 import { installMarker } from "./mcp.js";
 import { readLocalBinding, resolveBinding } from "../lib/binding.js";
 import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
-function isInteractive() {
+import { resolveLauncher, launcherNote, selfCommand } from "../lib/launcher.js";
+import { clean } from "../lib/text.js";
+import { VERSION } from "../version.js";
+export function isInteractive() {
     return Boolean(stdin.isTTY && stdout.isTTY);
 }
-async function ask(question) {
+export async function ask(question) {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
         // readline's question() NEVER settles when stdin hits EOF (Ctrl-D, or a
@@ -23,7 +27,7 @@ async function ask(question) {
         rl.close();
     }
 }
-async function confirm(question, assumeYes) {
+export async function confirm(question, assumeYes) {
     if (assumeYes)
         return true;
     if (!isInteractive())
@@ -32,8 +36,10 @@ async function confirm(question, assumeYes) {
     return a === "y" || a === "yes";
 }
 /**
- * Pick from a list interactively. Returns the chosen item, or undefined when the
- * user explicitly picks the trailing "create new" option.
+ * Render a numbered menu and read one answer, optionally with a trailing extra option.
+ *
+ * Returns the chosen item, or `undefined` when the trailing option was taken. When there
+ * is no trailing option, `undefined` is impossible — every valid answer names an item.
  *
  * Invalid input re-prompts rather than falling through: undefined used to mean
  * BOTH "chose create-new" and "typed garbage", so a typo like `1)` silently
@@ -43,26 +49,55 @@ async function confirm(question, assumeYes) {
  * "4.0", which would route those straight to create-new — the same
  * non-canonical-input-hits-the-destructive-branch bug in a new coat.
  */
-export async function pick(label, items, render, askFn = ask) {
-    if (!items.length)
-        return undefined;
-    console.log(`\n${label}:`);
+async function choose(label, items, render, askFn, extra) {
+    // An empty label means the caller already printed its own heading, and a menu is being
+    // appended to it — used by the identity prompt, whose lede is two lines of its own.
+    if (label)
+        console.log(`\n${label}:`);
     items.forEach((it, i) => console.log(`  ${i + 1}) ${render(it)}`));
-    const createNew = items.length + 1;
-    console.log(`  ${createNew}) + create new`);
+    const extraSlot = items.length + 1;
+    if (extra)
+        console.log(`  ${extraSlot}) ${extra}`);
+    const highest = extra ? extraSlot : items.length;
     for (let attempt = 0; attempt < 3; attempt++) {
         const a = await askFn("Choose a number: ");
         if (/^\d+$/.test(a)) {
             const n = Number(a);
             if (n >= 1 && n <= items.length)
                 return items[n - 1];
-            if (n === createNew)
+            if (extra && n === extraSlot)
                 return undefined;
         }
-        console.log(`Please enter a number between 1 and ${createNew}.`);
+        console.log(`Please enter a number between 1 and ${highest}.`);
     }
     throw new Error("no valid choice — aborting");
 }
+/**
+ * Pick from a list interactively. Returns the chosen item, or undefined when the
+ * user explicitly picks the trailing "create new" option.
+ */
+export async function pick(label, items, render, askFn = ask) {
+    if (!items.length)
+        return undefined;
+    return choose(label, items, render, askFn, "+ create new");
+}
+/**
+ * Pick from a list with NO create option (RTSC-492).
+ *
+ * `pick` appends "+ create new" unconditionally, which is right for `bind` — the person
+ * running it is setting up their own org and is its owner. It is wrong for someone who
+ * just accepted an invite: `createProject` is `requireOwner`, so offering the slot to a
+ * member is offering them a refusal. An option that can only fail is worse than no option,
+ * because it reads as permission.
+ *
+ * Never returns undefined, so the caller has no "or else" branch to get wrong. An empty
+ * list is the caller's problem to explain, not something to render as a menu of nothing.
+ */
+export async function pickExisting(label, items, render, askFn = ask) {
+    if (!items.length)
+        throw new Error("nothing to choose from");
+    return (await choose(label, items, render, askFn, null));
+}
 /**
  * The message to show when `bind` aborts mid-run, or null when there's nothing
  * to say. `bind` commits a new org server-side before the project step; if a
@@ -82,48 +117,225 @@ export function strandRecoveryHint(args) {
         `but has no project or key yet — re-run to finish:\n` +
         `    retasc bind --org-id ${orgId}`);
 }
-export async function bindAction(opts) {
-    const cfg = loadConfig();
-    const cwd = process.cwd();
-    // --- loud on re-bind -------------------------------------------------------
+/**
+ * "This folder is already bound — replace it?" (RTSC-262/RTSC-91)
+ *
+ * Extracted from `bindAction` so `join` inherits it verbatim rather than growing a second,
+ * quieter re-bind path (RTSC-492). Silently rebinding someone's working folder is the one
+ * outcome neither command may produce, and two implementations of that rule is one too
+ * many.
+ *
+ * `proceed: false` means STOP — either the caller declined, or the requested binding is
+ * already in place and there is nothing to do. The exit code for the non-interactive
+ * refusal is set here, at the point that knows why.
+ *
+ * Both callers run this before doing any work that commits state: `bind` before it can
+ * create an org, `join` before it mints a key. Neither runs it before the invite is
+ * redeemed, because joining an org is not a property of this folder.
+ */
+export async function rebindGuard(args) {
     // 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 && !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;
-            }
+    const existing = readLocalBinding(args.cwd);
+    if (!existing || existing.markerOnly)
+        return { proceed: true, existing: existing ?? null };
+    // Idempotent converge (RTSC-262): re-running 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 && args.orgId && args.projectId) {
+        const cur = getBinding(existing.workspaceId);
+        if (cur && cur.orgId === args.orgId && cur.projectId === args.projectId) {
+            console.log(`Already bound to the requested org/project (${cur.prefix ?? cur.projectId}). Nothing to do.`);
+            return { proceed: false, existing };
         }
-        let where = "an existing Retasc binding";
-        try {
-            const b = await resolveBinding(existing.url || cfg.mcpUrl, existing.key);
-            where = `org "${b.org.name}" / project ${b.project.prefix}`;
+    }
+    let where = "an existing Retasc binding";
+    try {
+        const b = await resolveBinding(existing.url || args.mcpUrl, existing.key);
+        where = `org "${clean(b.org.name)}" / project ${clean(b.project.prefix)}`;
+    }
+    catch {
+        /* key may be stale/revoked — still warn before replacing */
+    }
+    console.log(`This folder is already bound to ${where}.`);
+    if (await confirm("Replace it?", args.yes))
+        return { proceed: true, existing };
+    // 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 { proceed: false, existing };
+}
+/**
+ * Everything from "which project" to a working folder: pick the project, make `retasc`
+ * durable, mint a key for that (org, project), write the binding, and wire the marker.
+ *
+ * Shared by `bind` and `join` (RTSC-492) rather than copied. The two commands differ only
+ * in how they arrive at an org and in whether the caller may create a project; the tail is
+ * the same act, and two copies of it would drift — the marker-writing half in particular
+ * has already had to be fixed once (RTSC-493) and must never need fixing twice.
+ *
+ * ORDER. The durable-`retasc` step runs BEFORE the mint, not as a side effect of writing
+ * the marker afterwards. A cold `npm i -g` takes tens of seconds and can fail outright; a
+ * key minted before it is a live credential stranded behind a step that may never finish.
+ * Resolving first also means the launcher is known to every message printed after it.
+ */
+export async function completeWorkspaceSetup(args) {
+    const { orgId, opts, existing } = args;
+    const cfg = loadConfig();
+    const cwd = process.cwd();
+    const org = args.orgLabel ? `"${clean(args.orgLabel)}"` : "this org";
+    // --- resolve project (pick / flag / create) --------------------------------
+    let projectId = opts.projectId;
+    let prefix;
+    if (!projectId && opts.project && opts.prefix) {
+        if (!args.canCreateProject) {
+            cliError("FORBIDDEN", "Only an owner can create a project.", `Ask an owner to add one, then pass --project-id <id>.`);
         }
-        catch {
-            /* key may be stale/revoked — still warn before replacing */
+        const p = (await api.createProject({ orgId, name: opts.project, prefix: opts.prefix }));
+        projectId = p.projectId;
+        prefix = p.prefix;
+        console.log(`✓ Created project ${p.prefix}.`);
+    }
+    if (!projectId) {
+        const { projects } = (await api.listProjects({ orgId }));
+        const list = projects ?? [];
+        if (!args.canCreateProject) {
+            // A member cannot create one, so an empty org is a dead end here — and it has to say
+            // what to ask for, by name. A bare FORBIDDEN from `createProject` would be both
+            // wrong (they never asked to create anything) and unactionable.
+            if (!list.length) {
+                cliError("NO_PROJECTS", `Org ${org} has no projects yet, and only an owner can create one.`, `Ask an owner to add a project, then finish this folder with:  ${selfCommand(VERSION)} bind --org-id ${orgId}`);
+            }
+            // One project is not a choice. Asking anyway would be the only question in the
+            // common invite path, for an answer that was never in doubt.
+            if (list.length === 1) {
+                projectId = list[0].id;
+                prefix = list[0].prefix;
+            }
+            else if (isInteractive()) {
+                const chosen = await pickExisting("Select a project", list, (p) => `${clean(p.prefix)} — ${clean(p.name)}`);
+                projectId = chosen.id;
+                prefix = chosen.prefix;
+            }
+            else {
+                cliError("AMBIGUOUS", `Org ${org} has ${list.length} projects, so one has to be named.`, `Pass --project-id <id> (or run interactively): ${list.map((p) => `${p.prefix}=${p.id}`).join(", ")}`);
+            }
         }
-        console.log(`This folder is already bound to ${where}.`);
-        if (!(await confirm("Replace it?", opts.yes))) {
-            // 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 if (isInteractive()) {
+            const chosen = await pick("Select a project", list, (p) => `${clean(p.prefix)} — ${clean(p.name)}`);
+            if (chosen) {
+                projectId = chosen.id;
+                prefix = chosen.prefix;
             }
             else {
-                console.log("Left unchanged.");
+                const name = await ask("New project name: ");
+                const pfx = (await ask("Project prefix (e.g. ACME): ")).toUpperCase();
+                if (!name || !pfx)
+                    throw new Error("project name and prefix required");
+                const p = (await api.createProject({ orgId, name, prefix: pfx }));
+                projectId = p.projectId;
+                prefix = p.prefix;
+                console.log(`✓ Created project ${p.prefix}.`);
             }
-            return;
         }
+        else if (list.length === 1) {
+            projectId = list[0].id;
+            prefix = list[0].prefix;
+        }
+        else {
+            throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
+        }
+    }
+    // --- make `retasc` durable BEFORE anything is committed (RTSC-493) ---------
+    // The marker names a command something else spawns on every agent start, so it has to
+    // name one proved to run on this machine. Resolved (and announced) here so the install
+    // can't land after a key exists, and so every later message knows what to tell the user
+    // to type.
+    const launcher = resolveLauncher({ version: VERSION });
+    const note = launcherNote(launcher);
+    if (note)
+        console.log(note);
+    // --- mint a key for THIS (org, project) and wire the watchdog into THIS folder
+    const minted = (await api.mintKey({
+        orgId,
+        projectId: projectId,
+        agentName: opts.agent,
+        runtime: opts.runtime ?? "claude-code",
+        keyName: prefix ? `${prefix} key` : undefined,
+    }));
+    console.log(`✓ Minted key for this workspace (${minted.key.slice(0, 14)}…).\n`);
+    // RTSC-92: the secret stays OUT of the repo. Store it in the home keystore
+    // keyed by a workspace id; reuse this folder's existing id (so a re-bind, or a
+    // teammate's committed marker, keeps the same id) or mint a fresh one.
+    const workspaceId = existing?.workspaceId ?? newWorkspaceId();
+    setBinding(workspaceId, {
+        orgId,
+        projectId: projectId,
+        key: minted.key,
+        url: cfg.mcpUrl,
+        prefix,
+        orgName: args.orgLabel,
+        boundPath: cwd,
+        createdAt: Date.now(),
+    });
+    args.onBound?.();
+    // Per-folder only (local scope), always watchdog. The marker carries only the
+    // workspace id — no secret — so ./.mcp.json is safe to commit.
+    installMarker({ workspaceId, scope: "local", launcher });
+    // Confirm the binding the same way the agent will see it.
+    try {
+        const b = await resolveBinding(cfg.mcpUrl, minted.key);
+        console.log(`\n✓ This folder is bound to org "${clean(b.org.name)}" / project ${clean(b.project.prefix)}.\n` +
+            `  Agents launched here can only ever read or write ${clean(b.project.prefix)}.`);
     }
+    catch {
+        /* binding written; whoami confirmation is best-effort */
+    }
+}
+/**
+ * Sign in first when there is no session at all (RTSC-481, extended to `join` by RTSC-492).
+ *
+ * `withAuth` deliberately refuses to start a device flow for someone who was
+ * never signed in: on an arbitrary call that would be a surprise browser prompt
+ * under a misleading "session expired". That reasoning holds for every OTHER
+ * command and is left alone. It does not hold for the two commands that are the WHOLE
+ * instruction someone is handed — `bind` for a new owner, `join` for an invited teammate —
+ * 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.
+ */
+export async function ensureSignedIn() {
+    if (loadConfig().token)
+        return;
+    if (!isInteractive()) {
+        throw new Error("Not signed in. Run `retasc login` first (no TTY here for the device flow).");
+    }
+    console.error("Not signed in yet — authenticating with GitHub first…");
+    await deviceLogin();
+}
+export async function bindAction(opts) {
+    await ensureSignedIn();
+    const cfg = loadConfig();
+    // --- loud on re-bind -------------------------------------------------------
+    // Runs before the org step on purpose: `--org-name` commits an org server-side, and a
+    // run that is about to be refused must not leave one behind (RTSC-297).
+    const guard = await rebindGuard({
+        cwd: process.cwd(),
+        mcpUrl: cfg.mcpUrl,
+        orgId: opts.orgId,
+        projectId: opts.projectId,
+        yes: opts.yes,
+    });
+    if (!guard.proceed)
+        return;
+    const existing = guard.existing;
     // --- resolve org (pick / flag / create) ------------------------------------
     // Track whether THIS run created the org (vs. selected a pre-existing one or
     // took one via --org-id). An org is created and committed server-side BEFORE
@@ -170,79 +382,16 @@ export async function bindAction(opts) {
     // the org this run, name it and print the resume command (RTSC-297).
     let bindingWritten = false;
     try {
-        // --- resolve project (pick / flag / create) --------------------------------
-        let projectId = opts.projectId;
-        let prefix;
-        if (!projectId && opts.project && opts.prefix) {
-            const p = (await api.createProject({ orgId: orgId, name: opts.project, prefix: opts.prefix }));
-            projectId = p.projectId;
-            prefix = p.prefix;
-            console.log(`✓ Created project ${p.prefix}.`);
-        }
-        if (!projectId) {
-            const { projects } = (await api.listProjects({ orgId: orgId }));
-            const list = projects ?? [];
-            if (isInteractive()) {
-                const chosen = await pick("Select a project", list, (p) => `${p.prefix} — ${p.name}`);
-                if (chosen) {
-                    projectId = chosen.id;
-                    prefix = chosen.prefix;
-                }
-                else {
-                    const name = await ask("New project name: ");
-                    const pfx = (await ask("Project prefix (e.g. ACME): ")).toUpperCase();
-                    if (!name || !pfx)
-                        throw new Error("project name and prefix required");
-                    const p = (await api.createProject({ orgId: orgId, name, prefix: pfx }));
-                    projectId = p.projectId;
-                    prefix = p.prefix;
-                    console.log(`✓ Created project ${p.prefix}.`);
-                }
-            }
-            else if (list.length === 1) {
-                projectId = list[0].id;
-                prefix = list[0].prefix;
-            }
-            else {
-                throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
-            }
-        }
-        // --- mint a key for THIS (org, project) and wire the watchdog into THIS folder
-        const minted = (await api.mintKey({
-            orgId: orgId,
-            projectId: projectId,
-            agentName: opts.agent,
-            runtime: opts.runtime ?? "claude-code",
-            keyName: prefix ? `${prefix} key` : undefined,
-        }));
-        console.log(`✓ Minted key for this workspace (${minted.key.slice(0, 14)}…).\n`);
-        // RTSC-92: the secret stays OUT of the repo. Store it in the home keystore
-        // keyed by a workspace id; reuse this folder's existing id (so a re-bind, or a
-        // teammate's committed marker, keeps the same id) or mint a fresh one.
-        const workspaceId = existing?.workspaceId ?? newWorkspaceId();
-        setBinding(workspaceId, {
+        await completeWorkspaceSetup({
             orgId: orgId,
-            projectId: projectId,
-            key: minted.key,
-            url: cfg.mcpUrl,
-            prefix,
-            orgName: undefined,
-            boundPath: cwd,
-            createdAt: Date.now(),
+            opts,
+            existing,
+            // `bind` is the OWNER's command — creating a project is the point of its picker.
+            canCreateProject: true,
+            onBound: () => {
+                bindingWritten = true; // strand window closed — the org is now reachable
+            },
         });
-        bindingWritten = true; // strand window closed — the org is now reachable
-        // Per-folder only (local scope), always watchdog. The marker carries only the
-        // workspace id — no secret — so ./.mcp.json is safe to commit.
-        installMarker({ workspaceId, scope: "local" });
-        // Confirm the binding the same way the agent will see it.
-        try {
-            const b = await resolveBinding(cfg.mcpUrl, minted.key);
-            console.log(`\n✓ This folder is bound to org "${b.org.name}" / project ${b.project.prefix}.\n` +
-                `  Agents launched here can only ever read or write ${b.project.prefix}.`);
-        }
-        catch {
-            /* binding written; whoami confirmation is best-effort */
-        }
     }
     catch (err) {
         const hint = strandRecoveryHint({ createdOrgThisRun, orgId, bindingWritten });

package/dist/commands/claim.js

@@ -193,6 +193,9 @@ export async function claimAction(opts) {
     note(`✓ Claimed ${issueId}${title ? ` — ${title}` : ""}`);
     note(`  worktree: ${plan.path}`);
     note(`  branch:   ${plan.branch}`);
+    // RTSC-446: a fresh worktree checks out tracked files only — deps/artifacts are absent.
+    note(`  Fresh worktree: only tracked files. Run the repo's usual setup (what docs/CI`);
+    note(`  run on a fresh checkout) before your first build or test.`);
     finish(plan.path, plan.branch, issueId, title, claim.claimToken, opts);
 }
 /** Emit machine output / drop into the worktree per the chosen flags. */

package/dist/commands/doctor.js

@@ -1,6 +1,8 @@
 import { loadConfig } from "../config.js";
 import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
+import { runsOk } from "../lib/launcher.js";
+import { clean } from "../lib/text.js";
 // RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
 // 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.
@@ -19,7 +21,76 @@ const bad = (m) => console.log(`  ✗ ${m}`);
 // 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, " ");
+// Shared with join/bind — see lib/text.ts for why anything off the wire is sanitized
+// before it reaches a terminal (RTSC-492).
+/**
+ * RTSC-493: can the registered entry actually be STARTED on this machine?
+ *
+ * Every other check here asks whether the binding is right. This one asks whether it can
+ * run at all, which is a different failure and an invisible one: the entry names a
+ * command, something else spawns it later, and when that command isn't there the only
+ * symptom is an agent with no Retasc tools. Nothing points back here.
+ *
+ * Folders bound before the fix carry a bare `retasc` that npx never installed, and
+ * re-binding is what repairs them, so this is the surface that has to say so.
+ */
+export function launcherVerdict(local, probe = runsOk) {
+    if (!local.command)
+        return null; // HTTP transport spawns nothing
+    // 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;
+    return {
+        startable: Boolean(probe(local.command, probeArgs)),
+        shown: clean([local.command, ...probeArgs].join(" ")),
+    };
+}
+/**
+ * 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
+ * from a bug from a platform we never targeted.
+ *
+ * It says so HERE and not in the README because the README is read by everyone, and for
+ * the majority on macOS a standing disclaimer about platforms they aren't using is pure
+ * noise. `doctor` is the one surface that already knows which machine it's on, so the
+ * people it concerns are exactly the people who see it. On darwin this returns null and
+ * nothing is printed.
+ *
+ * Deliberately NOT a ✗ or a ! — this is context, not a fault in the folder being checked,
+ * and it must not read as "your setup is broken".
+ */
+export function platformNote(platform = process.platform) {
+    if (platform === "darwin")
+        return null;
+    // Windows and Linux are the two we've actually committed to reaching. Everything else
+    // (freebsd, aix, sunos…) is untested AND unplanned, so it must not be told its support
+    // is "on the list" — that would be exactly the unearned promise this note exists to
+    // avoid making. It still gets the note; it just doesn't get the roadmap sentence.
+    const planned = platform === "win32" ? "Windows" : platform === "linux" ? "Linux" : null;
+    // `clean` for the same reason every other interpolation in this file uses it: nothing
+    // reaches a verdict line able to smuggle ANSI escapes. `process.platform` is a Node
+    // build-time constant today, but this is an exported function with a caller-supplied
+    // parameter, and the safe version costs nothing.
+    const name = planned ?? clean(platform);
+    const note = `Note: ${name} is not a platform we test. macOS is the only one we support today.\n` +
+        `      Much of the CLI is plain Node and should work fine here, but nothing on this\n` +
+        `      platform is exercised, so a failure isn't a regression against a promise we\n` +
+        `      made.`;
+    return planned ? `${note} Proper ${planned} support is on the list, as bandwidth allows.` : note;
+}
+function checkLauncher(local) {
+    const v = launcherVerdict(local);
+    if (!v)
+        return;
+    if (v.startable) {
+        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.`);
+}
 export async function doctorAction() {
     const cfg = loadConfig();
     const cwd = process.cwd();
@@ -69,6 +140,10 @@ export async function doctorAction() {
                 bad(`key not accepted by the server: ${msg}. Re-run \`retasc bind\`.`);
             }
         }
+        // Directly under the headline, because "bound to org X" reads as an all-clear and
+        // this is the one way it can be true and the folder still not work (RTSC-493).
+        // Local and independent of the server, so it runs even when the network is down.
+        checkLauncher(local);
         // Caveats below the headline — each is a real risk, none is the common case.
         if (local.workspaceId) {
             // The id resolved, but if it was bound at a different folder, this marker
@@ -124,4 +199,9 @@ export async function doctorAction() {
             `    own, so issues can land in the wrong project.\n` +
             `    Fix:  claude mcp remove -s user retasc`);
     }
+    // 3) Ambient context, not a verdict on this folder — so it trails the checks
+    // rather than framing them, and on macOS it prints nothing at all.
+    const note = platformNote();
+    if (note)
+        console.log(`\n${note}`);
 }