@retasc/cli 1.8.0 → 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,15 +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
@@ -24,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())
@@ -33,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
@@ -44,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
@@ -83,64 +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) {
-    // RTSC-481 — sign in first when there is no session at all.
-    //
-    // `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 here, because bind is the single
-    // instruction the Dash hands a brand-new owner, and "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.
-    if (!loadConfig().token) {
-        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();
-    }
-    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
@@ -187,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/doctor.js

@@ -2,6 +2,7 @@ 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.
@@ -20,7 +21,8 @@ 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?
  *
@@ -43,6 +45,39 @@ export function launcherVerdict(local, probe = runsOk) {
         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)
@@ -164,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}`);
 }

package/dist/commands/join.js

@@ -0,0 +1,200 @@
+import { api, formatError } from "../api.js";
+import { loadConfig } from "../config.js";
+import { parseInviteCode } from "../lib/invite.js";
+import { selfCommand } from "../lib/launcher.js";
+import { clean } from "../lib/text.js";
+import { VERSION } from "../version.js";
+import { ask, confirm, ensureSignedIn, isInteractive, pickExisting, rebindGuard, completeWorkspaceSetup, } from "./bind.js";
+/** A ghost whose origin predates `sourceLabel`. Never invent a tool we don't know. */
+const UNKNOWN_SOURCE = "another tool";
+/**
+ * A stop that cannot loop forever.
+ *
+ * The loop is driven by a server list that shrinks on every claim, so it terminates on its
+ * own — but it is a `while (true)` around a network call, and a backend that ever returned
+ * an unchanged list would spin a human's terminal rather than fail. Well above any real
+ * number of migrated tools.
+ */
+const MAX_IDENTITY_ROUNDS = 10;
+/** How one row reads: the person, and the tool they were carried in from. */
+function ghostRow(g) {
+    // BOTH fields are third-party text: the name was typed by someone in ClickUp/Jira/Asana
+    // and carried across verbatim, and `sourceLabel` is the adapter's own record of where.
+    // They print into a terminal that acts on escape sequences, right above a prompt.
+    return `${clean(g.name)}      from ${clean(g.sourceLabel ?? UNKNOWN_SOURCE)}`;
+}
+/**
+ * "Which of these imported people is you?" — the CLI half of RTSC-433/473.
+ *
+ * Mirrors the Dash notice (`dash/src/components/GhostClaim.tsx`) deliberately, down to the
+ * confirm wording in `dash/src/lib/ghostPrompt.ts`. Two surfaces asking the same
+ * irreversible question in two different voices is how someone ends up answering the one
+ * they trust less.
+ *
+ * Never fatal. Everything here is about attribution; the bind that follows is what makes
+ * the folder work, and a failure to offer a claim must not cost someone their workspace.
+ */
+export async function identityLoop(orgId, opts, orgLabel, 
+// Injected so the question itself can be pinned by tests. It is asked once per human per
+// org and it is irreversible, so "we ran it live and it looked right" is not evidence —
+// the live orgs available to us have all already answered, which exercises only the
+// silent path. What has to be provable is the loud one.
+deps = {}) {
+    const d = {
+        claimableGhosts: api.claimableGhosts,
+        claimGhost: api.claimGhost,
+        dismissGhostPrompt: api.dismissGhostPrompt,
+        askFn: ask,
+        confirmFn: confirm,
+        interactive: isInteractive,
+        ...deps,
+    };
+    // `--yes` may SKIP this question. It may never answer it: claiming pulls another human's
+    // authorship AND their dispatch lane onto your account, irreversibly, and there is no
+    // CLI path back. A scripted run has nobody to be wrong on behalf of.
+    if (!d.interactive() || opts.yes)
+        return;
+    for (let round = 0; round < MAX_IDENTITY_ROUNDS; round++) {
+        let ghosts;
+        try {
+            const res = await d.claimableGhosts({ orgId });
+            if (res.asked || !res.ghosts.length)
+                return;
+            ghosts = res.ghosts;
+        }
+        catch (e) {
+            const { message } = formatError(e);
+            console.error(`  ! Couldn't check for imported history (${message}). Carrying on.`);
+            return;
+        }
+        console.log(round === 0
+            ? `\nWhen ${orgLabel ?? "this org"} migrated, some people were carried across.\n` +
+                "One of them may be you:"
+            : "\nAnything else here you recognise?");
+        // "Don't ask again" is not decoration. Declining writes `ghostPromptDismissedAt` on the
+        // member row and `claimGhost` refuses for good afterwards, org-wide — so a bare "none
+        // of these are me" would read as "none of these ClickUp ones" and quietly close the
+        // door on a second tool's placeholder too.
+        // Compared by REFERENCE below, not by a magic id value: a sentinel that is merely a
+        // row with an empty id would let any future ghost with a falsy id read as a decline —
+        // and a decline is permanent.
+        const NONE = { id: "", name: "None of these are me (don't ask again)", sourceLabel: null };
+        // No label: the heading above is the prompt, and `choose` would print a second one.
+        const chosen = await pickExisting("", [...ghosts, NONE], (g) => (g === NONE ? g.name : ghostRow(g)), d.askFn);
+        if (chosen === NONE) {
+            try {
+                await d.dismissGhostPrompt({ orgId });
+            }
+            catch (e) {
+                console.error(`  ! ${formatError(e).message}`);
+            }
+            return;
+        }
+        // Confirm before claiming — it is irreversible and it moves dispatch routing, so it
+        // must not be a single keystroke on a row in a list. Same qualitative wording as the
+        // Dash: counting "12 issues, 4 comments" would mean an org-wide scan on exactly the
+        // orgs that just ingested a migration.
+        const from = clean(chosen.sourceLabel ?? UNKNOWN_SOURCE);
+        const question = `\n  Link "${clean(chosen.name)}" to your account? Everything they wrote, commented on,\n` +
+            `  or were assigned in ${from} becomes yours. This can't be undone.`;
+        if (!(await d.confirmFn(question))) {
+            // NOT a dismissal. They declined THIS row, which is not the same as "none of these
+            // are me" — and dismissing is permanent, so it only ever happens when said outright.
+            console.log("  Left unlinked.");
+            continue;
+        }
+        try {
+            const res = await d.claimGhost({ orgId, memberId: chosen.id });
+            console.log(`✓ Linked ${clean(res.name)}.`);
+        }
+        catch (e) {
+            // SOURCE_ALREADY_CLAIMED, IMPORT_RUNNING, NOT_CLAIMABLE — all readable, all reachable
+            // by racing the Dash, and none of them a reason to abandon the setup.
+            const { code, message, hint } = formatError(e);
+            console.error(`  ✗ ${code ? `${code}: ` : ""}${message}`);
+            if (hint)
+                console.error(`    → ${hint}`);
+            return;
+        }
+        // Claiming one ClickUp identity removes EVERY remaining ClickUp row (`claimableGhosts`
+        // filters by spent source), so the next round can only ever offer a different tool.
+    }
+}
+export async function joinAction(link, opts) {
+    // Client-side, before anything else: the code is what the server matches, and someone
+    // who pasted the wrong thing should hear it here rather than as "not recognized".
+    const code = parseInviteCode(link);
+    await ensureSignedIn();
+    // --- 2. redeem ------------------------------------------------------------
+    // Any failure here stops the run. A dead invite means there is no org to bind to, and
+    // binding this folder to nothing would be worse than stopping.
+    const res = (await api.acceptInvite({ code }));
+    const orgLabel = res.slug ? clean(res.slug) : undefined;
+    const where = orgLabel ? ` "${orgLabel}"` : "";
+    if (res.alreadyMember) {
+        // Not a failure: the code stays unconsumed by design, so the person it was meant for
+        // can still use it. Say so and carry on into the folder half.
+        console.log(`• You're already a member of org${where} (${res.role}).`);
+    }
+    else {
+        console.log(`✓ Joined org${where} as a ${res.role}.`);
+    }
+    if (opts.bind === false) {
+        // `--no-bind` is redeem-only, exactly as `join` behaved before RTSC-492 — including
+        // asking nothing, so anything scripted against it sees the same output and the same
+        // exit code. The identity prompt still reaches them through the Dash.
+        return;
+    }
+    // --- 3. identity ----------------------------------------------------------
+    // BEFORE anything about this folder, including the re-bind guard. Ghosts are rows in
+    // `members`, which carries an `orgId` and no `projectId`: the question belongs to the org
+    // just joined, and this is the only time `join` asks it. Gating it behind the folder half
+    // would mean someone whose folder is already bound elsewhere — who declines the re-bind —
+    // silently never sees it, and their imported history stays stranded.
+    await identityLoop(res.orgId, opts, orgLabel);
+    // --- the folder half ------------------------------------------------------
+    const cfg = loadConfig();
+    const self = selfCommand(VERSION);
+    const resume = `${self} bind --org-id ${res.orgId}`;
+    const guard = await rebindGuard({
+        cwd: process.cwd(),
+        mcpUrl: cfg.mcpUrl,
+        orgId: res.orgId,
+        projectId: opts.projectId,
+        yes: opts.yes,
+    });
+    if (!guard.proceed) {
+        // The membership landed either way — never let a declined or no-op re-bind read as a
+        // failed join. `rebindGuard` has already said what it did with the folder, INCLUDING
+        // setting a non-zero exit code for the non-interactive refusal, so don't paper over
+        // that with a line that reads like everything is finished.
+        if (process.exitCode)
+            console.error(`  You did join org${where}; only the folder was left alone.`);
+        else
+            console.log(`  You're a member of org${where}. Nothing else to do here.`);
+        return;
+    }
+    try {
+        await completeWorkspaceSetup({
+            orgId: res.orgId,
+            orgLabel,
+            opts,
+            existing: guard.existing,
+            // `createProject` is `requireOwner`, and an invite only ever grants `member`. Offering
+            // "+ create new" here would be offering a refusal dressed as a choice.
+            canCreateProject: false,
+        });
+    }
+    catch (e) {
+        // Say what SUCCEEDED before reporting the failure, and name the command that resumes.
+        // The membership (and any identity claim) already landed and cannot be re-done: the
+        // invite is consumed now, so re-running `join` with the same link would report
+        // "already used" and read like the whole thing failed.
+        console.error(`\n  You did join org${where} — only this folder's setup didn't finish.`);
+        console.error(`  Resume with:  ${resume}`);
+        throw e;
+    }
+    if (isInteractive()) {
+        console.log("\nStart your agent in this folder and it'll pull from the queue.");
+    }
+}

package/dist/commands/mcp.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
-import { resolveLauncher, launcherNote, portableLauncher } from "../lib/launcher.js";
+import { resolveLauncher, launcherNote, portableLauncher, } from "../lib/launcher.js";
 import { VERSION } from "../version.js";
 export const SERVER_NAME = "retasc";
 /** Normalize a user-supplied scope string. `user` (global) is refused and
@@ -211,8 +211,10 @@ export function installMarker(opts) {
     const scope = opts.scope ?? "local";
     // RTSC-493: resolve BEFORE writing anything. The marker names a command something else
     // will spawn later, so it has to name one that has been proved to run on this machine.
-    const resolved = resolveLauncher({ version: VERSION, install: opts.install });
-    const note = launcherNote(resolved);
+    const resolved = opts.launcher ?? resolveLauncher({ version: VERSION, install: opts.install });
+    // Only announce a resolve we did ourselves — a caller that passed one in already printed
+    // its note at the point in ITS sequence where the install actually happened.
+    const note = opts.launcher ? null : launcherNote(resolved);
     if (note)
         console.log(note);
     // `local` scope lands in this machine's own Claude config, where the absolute path is

package/dist/index.js

@@ -6,6 +6,7 @@ import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate } from "./commands/gate.js";
 import { claimAction } from "./commands/claim.js";
 import { bindAction } from "./commands/bind.js";
+import { joinAction } from "./commands/join.js";
 import { doctorAction } from "./commands/doctor.js";
 import { billingAction } from "./commands/billing.js";
 import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
@@ -320,7 +321,11 @@ members
         const res = (await api.createInvite({ orgId: opts.orgId, expiresInDays: opts.expiresDays }));
         console.log(`✓ Invite code: ${res.code}`);
         console.log(`  Expires ${new Date(res.expiresAt).toISOString().slice(0, 10)}. Single-use — shown once.`);
-        console.log(`  Share it; they run:  retasc login && retasc join ${res.code}`);
+        // RTSC-492: one command, and one that needs nothing installed first. `join` signs
+        // them in, binds the folder and wires their agent, so this must not tell them to run
+        // `retasc login` first — nor name a `retasc` binary they don't have yet.
+        console.log(`  Share it. In the folder their agent works in, they run:`);
+        console.log(`      npx @retasc/cli join ${res.code}`);
     }
     catch (e) {
         fail(e);
@@ -354,25 +359,23 @@ members
         fail(e);
     }
 });
+// RTSC-492 — the WHOLE of an invited teammate's setup, in one command run from the folder
+// their agent will work in: sign in, redeem, claim any imported history, pick the project,
+// make `retasc` durable, mint a key, bind the folder and wire the MCP marker. It signs
+// itself in (no `requireLogin` gate) because "run this, but run the other one first" is
+// not a single instruction.
 program
     .command("join")
-    .description("Redeem an invite code to join an org (as the signed-in GitHub user).")
-    .argument("<code>", "The invite code you were given")
-    .action(async (code) => {
-    requireLogin();
-    try {
-        const res = (await api.acceptInvite({ code }));
-        const where = res.slug ? ` "${res.slug}"` : "";
-        if (res.alreadyMember) {
-            console.log(`• You're already a member of org${where} (${res.role}). Nothing to do.`);
-        }
-        else {
-            console.log(`✓ Joined org${where} as ${res.role}. It'll show up in \`retasc whoami\`.`);
-        }
-    }
-    catch (e) {
-        fail(e);
-    }
+    .description("Join an org from an invite link and set this folder up completely — one command.")
+    .argument("<link>", "The invite link you were given (or just the rtscinv_… code)")
+    .option("--no-bind", "Redeem only — don't set this folder up")
+    .option("--project-id <id>", "Which project to bind to (skips the picker)")
+    .option("--agent <name>", "Agent member name (default: auto)")
+    .option("--runtime <runtime>", "Agent runtime", "claude-code")
+    .option("-y, --yes", "Don't prompt to replace an existing binding, and skip the identity question")
+    .allowExcessArguments(false)
+    .action(async (link, opts) => {
+    await joinAction(link, opts).catch(fail);
 });
 // --- mcp wiring ------------------------------------------------------------
 const mcp = program.command("mcp").description("Wire the Retasc MCP server into your agent.");

package/dist/lib/invite.js

@@ -0,0 +1,38 @@
+// RTSC-492 — turn whatever the person was handed into the code the server matches.
+//
+// An invite reaches someone as a LINK (`https://dash.retasc.com/join#rtscinv_…`), and a
+// link is what they paste. `acceptInvite` matches an exact string, and it should stay that
+// way: normalising a paste is a property of the edge that accepts typed input, not of the
+// mutation that grants membership. So the unwrapping happens here.
+/** Every invite code the product has ever minted starts with this. */
+const INVITE_PREFIX = "rtscinv_";
+/**
+ * The invite code inside a link, a bare code, or a code someone pasted with prose
+ * around it.
+ *
+ * One rule rather than a parser: find the first token that LOOKS like an invite code,
+ * anywhere in the input. That covers the fragment (`…/join#rtscinv_x`), a query string
+ * (`?code=rtscinv_x`), a path segment, an email client's `<…>` wrapper and a trailing
+ * period from a sentence, without needing to know which of those the sender used — and
+ * without the URL-shape guessing that gets one of them wrong.
+ *
+ * A token that isn't our shape is still passed through UNCHANGED as long as it can't be a
+ * link. A future code format then keeps working with no CLI release, and the server's
+ * "That invite code isn't recognized" stays the authority on what's valid. Something
+ * link-shaped with no code in it is the one case we refuse locally, because forwarding a
+ * URL as a code can only ever produce that same message with none of the diagnosis.
+ */
+export function parseInviteCode(input) {
+    const raw = String(input ?? "").trim();
+    // Hex today, but accept the wider token charset a future format might use rather than
+    // pinning this to `[0-9a-f]{48}` and having to ship a release to read a new code.
+    const match = raw.match(new RegExp(`${INVITE_PREFIX}[A-Za-z0-9_-]+`));
+    if (match)
+        return match[0];
+    const bare = raw.replace(/^[<"'(]+|[>"'.,)]+$/g, "");
+    if (bare && !/[\s/:]/.test(bare))
+        return bare;
+    throw new Error(raw
+        ? "That doesn't contain an invite code. Paste the whole invite link, or just the `rtscinv_…` code."
+        : "No invite code given. Pass the invite link, or just the `rtscinv_…` code.");
+}

package/dist/lib/launcher.js

@@ -78,6 +78,24 @@ export function portableLauncher(r, version) {
         return r.launcher;
     return { command: "npx", args: ["-y", `${PKG}@${version}`] };
 }
+/**
+ * How to spell "run this CLI again", for a message printed BEFORE anything has been made
+ * durable (RTSC-492).
+ *
+ * `join` can stop for reasons that have nothing to do with us — an org with no projects,
+ * a mint that failed — and every one of those has to name the command that resumes. Until
+ * `resolveLauncher` has run there may be no `retasc` on this machine at all, so telling
+ * someone to type `retasc bind …` would be telling them to type a command that does not
+ * exist. That is the same defect as a marker naming a missing binary, just aimed at the
+ * human instead of the agent.
+ *
+ * Decided from argv rather than by probing: it costs no subprocess, and it names the form
+ * they DEMONSTRABLY have — they just used it. npx unpacks the package into its own `_npx`
+ * cache and puts nothing on PATH, so a script path under that cache is proof of an npx run.
+ */
+export function selfCommand(version, argv1 = process.argv[1] ?? "") {
+    return /[\\/]_npx[\\/]/.test(argv1) ? `npx -y ${PKG}@${version}` : "retasc";
+}
 /** Install (or upgrade to) an exact version globally. Returns null on success. */
 function installGlobal(version) {
     // A cold global install takes seconds with no output of its own. Silence here reads as

package/dist/lib/text.js

@@ -0,0 +1,21 @@
+/**
+ * Strip control characters from a string before printing it (RTSC-261, RTSC-492).
+ *
+ * Anything that came off the wire is untrusted output: it reaches `console.log` in a
+ * terminal that acts on escape sequences, so a value carrying `\x1b[…` can move the cursor,
+ * clear the line, or overwrite text the user is reading. That matters most where the text
+ * sits next to a decision — a name in a confirm prompt could be dressed up to look like the
+ * prompt itself.
+ *
+ * The riskiest strings in the product are the ones this exists for: an imported member's
+ * display name is chosen in ClickUp/Jira/Asana by someone who is not our user, carried
+ * across by a migration verbatim, and then shown to a human about to make an irreversible
+ * choice about it.
+ *
+ * Mirrors `sanitize` in `convex/lib/userError.ts` and the inline cleanup in `formatError`.
+ * The three are one rule; this is the copy the CLI's own printing paths share.
+ */
+export function clean(s) {
+    // eslint-disable-next-line no-control-regex
+    return String(s).replace(/[\x00-\x1f\x7f\u0085\u2028\u2029]/g, " ");
+}

package/package.json

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