@retasc/cli 1.7.1 → 1.8.0

package/dist/commands/bind.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { api } 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";
@@ -63,7 +64,42 @@ export async function pick(label, items, render, askFn = ask) {
     }
     throw new Error("no valid choice — aborting");
 }
+/**
+ * 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
+ * later step throws, that org is stranded (no project, no key, no binding) and
+ * unreachable from the CLI. There's no CLI-callable org delete, so we surface
+ * the id and the resume command instead (RTSC-297, Option 2).
+ *
+ * It fires ONLY for an org THIS run created that never got bound. A merely
+ * SELECTED org (or one already bound before the failure) is not ours to
+ * reclaim, and returns null — nothing extra is printed.
+ */
+export function strandRecoveryHint(args) {
+    const { createdOrgThisRun, orgId, bindingWritten } = args;
+    if (!createdOrgThisRun || !orgId || bindingWritten)
+        return null;
+    return (`\n✗ Aborted before this folder was bound. A new org was created (${orgId}) ` +
+        `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 -------------------------------------------------------
@@ -106,10 +142,20 @@ export async function bindAction(opts) {
         }
     }
     // --- 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
+    // the project step runs, so any abort in the project/mint/bind steps below
+    // strands it: no project, no key, no local binding — invisible from the CLI,
+    // and (orgs land on the billing rail) accumulating against the account on
+    // repeated aborts. There's no CLI-callable org delete, so instead we name the
+    // stranded org in the error and print the command to resume (RTSC-297). A
+    // merely-SELECTED org must never trigger this — it isn't ours to reclaim.
     let orgId = opts.orgId;
+    let createdOrgThisRun = false;
     if (!orgId && opts.orgName) {
         const org = (await api.createOrg({ name: opts.orgName }));
         orgId = org.orgId;
+        createdOrgThisRun = true;
         console.log(`✓ Created org "${opts.orgName}".`);
     }
     if (!orgId) {
@@ -125,6 +171,7 @@ export async function bindAction(opts) {
                 if (!name)
                     throw new Error("org name required");
                 orgId = (await api.createOrg({ name })).orgId;
+                createdOrgThisRun = true;
                 console.log(`✓ Created org "${name}".`);
             }
         }
@@ -135,76 +182,89 @@ export async function bindAction(opts) {
             throw new Error("no org selected — pass --org-id <id> or --org-name <name> (or run interactively).");
         }
     }
-    // --- 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;
+    // Everything from here to the binding write is the strand window: the org
+    // exists but the workspace isn't bound yet. If we abort in it after creating
+    // 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 {
-                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}.`);
+                throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
             }
         }
-        else if (list.length === 1) {
-            projectId = list[0].id;
-            prefix = list[0].prefix;
+        // --- 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, {
+            orgId: orgId,
+            projectId: projectId,
+            key: minted.key,
+            url: cfg.mcpUrl,
+            prefix,
+            orgName: undefined,
+            boundPath: cwd,
+            createdAt: Date.now(),
+        });
+        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}.`);
         }
-        else {
-            throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
+        catch {
+            /* binding written; whoami confirmation is best-effort */
         }
     }
-    // --- 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, {
-        orgId: orgId,
-        projectId: projectId,
-        key: minted.key,
-        url: cfg.mcpUrl,
-        prefix,
-        orgName: undefined,
-        boundPath: cwd,
-        createdAt: Date.now(),
-    });
-    // 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 });
+        if (hint)
+            console.error(hint);
+        throw err;
     }
 }

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,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";
 // 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,6 +21,41 @@ const bad = (m) => console.log(`  ✗ ${m}`);
 // 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, " ");
+/**
+ * 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(" ")),
+    };
+}
+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 +105,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

package/dist/commands/mcp.js

@@ -1,6 +1,8 @@
 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 { VERSION } from "../version.js";
 export const SERVER_NAME = "retasc";
 /** Normalize a user-supplied scope string. `user` (global) is refused and
  * downgraded to `local`, loudly — per-folder binding is the only right way. */
@@ -32,31 +34,31 @@ export function mcpConfigBlock(url, key) {
  * claimed issues' leases alive automatically. url+key go via env (not a header,
  * since this is a spawned command). Harness-agnostic: any stdio MCP client works.
  */
-export function mcpProxyEntry(url, key) {
+export function mcpProxyEntry(url, key, launcher) {
     return {
-        command: "retasc",
-        args: ["mcp-proxy"],
+        command: launcher.command,
+        args: [...launcher.args, "mcp-proxy"],
         env: { RETASC_MCP_URL: url, RETASC_MCP_KEY: key },
     };
 }
 /** Copy-pasteable watchdog block for Codex / OpenCode / any stdio MCP client. */
-export function mcpProxyConfigBlock(url, key) {
-    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key) } }, null, 2);
+export function mcpProxyConfigBlock(url, key, launcher) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key, launcher) } }, null, 2);
 }
 /**
  * RTSC-92: the SECRET-FREE watchdog marker. No key — only the opaque workspace
  * id, which the proxy resolves to a key through the home keystore. Safe to
  * commit; doubles as the "this repo is a Retasc workspace" marker.
  */
-export function mcpMarkerEntry(workspaceId) {
+export function mcpMarkerEntry(workspaceId, launcher) {
     return {
-        command: "retasc",
-        args: ["mcp-proxy"],
+        command: launcher.command,
+        args: [...launcher.args, "mcp-proxy"],
         env: { RETASC_WORKSPACE: workspaceId },
     };
 }
-export function mcpMarkerConfigBlock(workspaceId) {
-    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpMarkerEntry(workspaceId) } }, null, 2);
+export function mcpMarkerConfigBlock(workspaceId, launcher) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpMarkerEntry(workspaceId, launcher) } }, null, 2);
 }
 // --- `claude mcp add` argv builders (pure, exported for tests) -------------
 // RTSC-99: the stdio builders put SERVER_NAME *before* the variadic `--env`
@@ -75,7 +77,7 @@ export function buildHttpAddArgs(url, key, scope) {
     ];
 }
 /** Build argv for the stdio watchdog proxy (RTSC-44). */
-export function buildWatchdogAddArgs(url, key, scope) {
+export function buildWatchdogAddArgs(url, key, scope, launcher) {
     return [
         "mcp", "add",
         SERVER_NAME,
@@ -83,28 +85,28 @@ export function buildWatchdogAddArgs(url, key, scope) {
         "--scope", scope,
         "--env", `RETASC_MCP_URL=${url}`,
         "--env", `RETASC_MCP_KEY=${key}`,
-        "--", "retasc", "mcp-proxy",
+        "--", launcher.command, ...launcher.args, "mcp-proxy",
     ];
 }
 /** Build argv for the secret-free stdio marker (RTSC-92). */
-export function buildMarkerAddArgs(workspaceId, scope) {
+export function buildMarkerAddArgs(workspaceId, scope, launcher) {
     return [
         "mcp", "add",
         SERVER_NAME,
         "--transport", "stdio",
         "--scope", scope,
         "--env", `RETASC_WORKSPACE=${workspaceId}`,
-        "--", "retasc", "mcp-proxy",
+        "--", launcher.command, ...launcher.args, "mcp-proxy",
     ];
 }
 function tryClaudeCli(url, key, scope) {
     return runClaudeAdd(buildHttpAddArgs(url, key, scope));
 }
-function tryClaudeCliWatchdog(url, key, scope) {
-    return runClaudeAdd(buildWatchdogAddArgs(url, key, scope));
+function tryClaudeCliWatchdog(url, key, scope, launcher) {
+    return runClaudeAdd(buildWatchdogAddArgs(url, key, scope, launcher));
 }
-function tryClaudeCliMarker(workspaceId, scope) {
-    return runClaudeAdd(buildMarkerAddArgs(workspaceId, scope));
+function tryClaudeCliMarker(workspaceId, scope, launcher) {
+    return runClaudeAdd(buildMarkerAddArgs(workspaceId, scope, launcher));
 }
 function runClaudeAdd(args) {
     const r = spawnSync("claude", args, { encoding: "utf8" });
@@ -167,17 +169,23 @@ export function installMcp(opts) {
     const scope = opts.scope ?? "local";
     // Watchdog mode (RTSC-44): wire the stdio proxy so claims stay alive automatically.
     if (opts.watchdog) {
-        const res = tryClaudeCliWatchdog(opts.url, opts.key, scope);
+        // Only the stdio forms spawn a command; the plain HTTP entry below carries a URL and
+        // needs nothing installed, so resolving is scoped to the branch that depends on it.
+        const resolved = resolveLauncher({ version: VERSION, install: opts.install });
+        const note = launcherNote(resolved);
+        if (note)
+            console.log(note);
+        const res = tryClaudeCliWatchdog(opts.url, opts.key, scope, resolved.launcher);
         if (res.ok) {
             console.log(`✓ Registered Retasc with the liveness watchdog (stdio proxy, scope: ${scope}).`);
         }
         else {
-            const path = writeProjectMcpJson(mcpProxyEntry(opts.url, opts.key));
+            const path = writeProjectMcpJson(mcpProxyEntry(opts.url, opts.key, resolved.launcher));
             console.log(`✓ Wrote watchdog MCP config to ${path}`);
             console.log(`  ${fallbackNote(res)}`);
         }
         console.log("\nWatchdog MCP config (Codex / OpenCode / any stdio MCP client):\n");
-        console.log(mcpProxyConfigBlock(opts.url, opts.key));
+        console.log(mcpProxyConfigBlock(opts.url, opts.key, resolved.launcher));
         console.log("\nThe watchdog keeps your claims alive automatically — no per-claim heartbeats. If it ever isn't running you just fall back to the normal lease timeout (safe).");
         return;
     }
@@ -201,16 +209,28 @@ export function installMcp(opts) {
  */
 export function installMarker(opts) {
     const scope = opts.scope ?? "local";
-    const res = tryClaudeCliMarker(opts.workspaceId, scope);
+    // 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);
+    if (note)
+        console.log(note);
+    // `local` scope lands in this machine's own Claude config, where the absolute path is
+    // both correct and fastest. `project` scope, and the ./.mcp.json fallback below, are
+    // SHARED — a path under this user's home directory would leak their username into a
+    // committed file and break every teammate who clones it. See portableLauncher.
+    const shared = portableLauncher(resolved, VERSION);
+    const res = tryClaudeCliMarker(opts.workspaceId, scope, scope === "project" ? shared : resolved.launcher);
     if (res.ok) {
         console.log(`✓ Registered Retasc watchdog (secret-free marker, scope: ${scope}).`);
     }
     else {
-        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId));
+        // Always ./.mcp.json, whatever scope was asked for, so always the shared form.
+        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId, shared));
         console.log(`✓ Wrote secret-free watchdog marker to ${path}`);
         console.log(`  ${fallbackNote(res)}`);
     }
     console.log("\nMarker block (any stdio MCP client) — no secret, safe to commit:\n");
-    console.log(mcpMarkerConfigBlock(opts.workspaceId));
+    console.log(mcpMarkerConfigBlock(opts.workspaceId, shared));
     console.log("\nThe key lives in your home keystore (~/.retasc/bindings.json), not in the repo.");
 }

package/dist/index.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { VERSION } from "./version.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate } from "./commands/gate.js";
@@ -15,16 +13,11 @@ import { tidyAction, doneAction } from "./commands/tidy.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
 import { api, formatError } from "./api.js";
-// Single source of truth for the version: read package.json at runtime from the
-// compiled file's location (dist/index.js -> ../package.json). A JSON import won't
-// work here — tsconfig has rootDir "src", so importing ../package.json is outside
-// rootDir and fails tsc.
-const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
 const program = new Command();
 program
     .name("retasc")
     .description("Retasc — sign in, create projects, mint agent API keys, and wire your agent to the MCP server.")
-    .version(pkg.version);
+    .version(VERSION);
 function requireLogin() {
     if (!isLoggedIn()) {
         console.error("Not signed in. Run `retasc login` first.");

package/dist/lib/binding.js

@@ -26,13 +26,17 @@ function parseServerEntry(s, source) {
     if (!s)
         return undefined;
     // Canonical (RTSC-92): secret-free marker → resolve the key from the keystore.
+    // RTSC-493: the spawned command, when this is one of the stdio forms.
+    const spawn = typeof s.command === "string"
+        ? { command: s.command, args: Array.isArray(s.args) ? s.args.map(String) : [] }
+        : {};
     const workspaceId = s.env?.RETASC_WORKSPACE;
     if (workspaceId) {
         const entry = getBinding(workspaceId);
         if (entry)
-            return { key: entry.key, url: entry.url, watchdog: true, workspaceId, source };
+            return { key: entry.key, url: entry.url, watchdog: true, workspaceId, source, ...spawn };
         // Marker present but no keystore entry (e.g. a cloned repo) → needs binding.
-        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true, source };
+        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true, source, ...spawn };
     }
     // Legacy inline-key forms (pre-RTSC-92): key in env or the Authorization header.
     if (s.env?.RETASC_MCP_KEY) {
@@ -42,6 +46,7 @@ function parseServerEntry(s, source) {
             watchdog: true,
             legacy: true,
             source,
+            ...spawn,
         };
     }
     const auth = s.headers?.Authorization ?? s.headers?.authorization;

package/dist/lib/launcher.js

@@ -0,0 +1,182 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const PKG = "@retasc/cli";
+// Windows shims are .cmd files, which cannot be spawned without a shell. Everywhere
+// else a shell is an injection surface for no benefit, so it stays off.
+//
+// WINDOWS IS NOT A SUPPORTED PLATFORM. The branches below are written to npm's
+// documented layout and unit-tested for shape, but nothing here has ever been RUN on
+// Windows. Treat them as best effort: they may well work, and a Windows bug report is
+// not a regression against anything we claim. Kept rather than removed because throwing
+// on win32 would break someone for whom it currently works, for no gain.
+const WIN = process.platform === "win32";
+/**
+ * Does `command […args] --version` actually run, and print something version-shaped?
+ *
+ * Executing is the whole point. A binary can exist on disk and still be unusable (wrong
+ * arch, broken symlink, a shim whose target was removed), and the version check also
+ * guards against spawning some UNRELATED program that happens to be called `retasc`.
+ */
+export function runsOk(command, args = []) {
+    let r;
+    try {
+        r = spawnSync(command, [...args, "--version"], {
+            encoding: "utf8",
+            shell: WIN,
+            timeout: 60_000,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (r.error || r.status !== 0)
+        return null;
+    const out = (r.stdout || "").trim();
+    // Our `--version` prints a bare semver (commander's .version()). Anything else is a
+    // different program, and pointing a marker at it would be worse than not writing one.
+    return /^\d+\.\d+\.\d+/.test(out) ? out : null;
+}
+/** npm's global prefix, or null when npm itself can't be run. */
+export function npmGlobalPrefix() {
+    let r;
+    try {
+        r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", shell: WIN, timeout: 60_000 });
+    }
+    catch {
+        return null;
+    }
+    if (r.error || r.status !== 0)
+        return null;
+    const out = (r.stdout || "").trim();
+    return out || null;
+}
+/**
+ * Where npm puts the `retasc` shim for a global install.
+ *
+ * `npm bin -g` was REMOVED in npm 9, so it can't be asked directly — the prefix has to
+ * be turned into a bin path by hand, and the layout differs by platform: POSIX nests a
+ * `bin/`, Windows puts the `.cmd` shim straight in the prefix root.
+ */
+export function globalBinCandidates(prefix, win = WIN) {
+    return win
+        ? [join(prefix, "retasc.cmd"), join(prefix, "retasc")]
+        : [join(prefix, "bin", "retasc")];
+}
+/**
+ * A launcher safe to write into a SHARED file.
+ *
+ * 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.
+ */
+export function portableLauncher(r, version) {
+    if (r.how !== "absolute")
+        return r.launcher;
+    return { command: "npx", args: ["-y", `${PKG}@${version}`] };
+}
+/** Install (or upgrade to) an exact version globally. Returns null on success. */
+function installGlobal(version) {
+    // A cold global install takes seconds with no output of its own. Silence here reads as
+    // a hang in the middle of a bind, so say what is happening before it starts.
+    console.log("  Installing the retasc CLI so your agent can start it…");
+    let r;
+    try {
+        r = spawnSync("npm", ["install", "-g", `${PKG}@${version}`], {
+            encoding: "utf8",
+            shell: WIN,
+            // A cold global install pulls the tarball and its deps; 60s is not always enough.
+            timeout: 180_000,
+        });
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    if (r.error)
+        return r.error.message;
+    if (r.status !== 0) {
+        // EACCES is by far the common one (a prefix owned by root), and its first line is
+        // the useful part — the rest is npm's log-file boilerplate.
+        const msg = (r.stderr || r.stdout || "").trim().split("\n")[0];
+        return msg || `npm exited ${r.status}`;
+    }
+    return null;
+}
+/**
+ * Decide what the marker should name, and prove it before returning it.
+ *
+ * Order matters. An already-working `retasc` is left alone (no surprise installs for
+ * someone who already manages their own). Otherwise we try to make one, and if the
+ * install lands somewhere PATH can't see, the ABSOLUTE path to that binary is used
+ * instead — verified to run, full speed, and immune to whatever is wrong with PATH.
+ *
+ * npx is last on purpose. It works, but it costs a registry round-trip on every agent
+ * start (measured ~2.4s against ~0.06s for the binary), and unpinned it would resolve
+ * `latest` each time, so an agent's MCP server could change version mid-project without
+ * anyone asking. It is pinned here for exactly that reason.
+ */
+export function resolveLauncher(opts) {
+    // 1. Already usable? Leave it alone.
+    if (runsOk("retasc")) {
+        return { launcher: { command: "retasc", args: [] }, how: "on-path", verified: true };
+    }
+    const npxLauncher = { command: "npx", args: ["-y", `${PKG}@${opts.version}`] };
+    // Last resort, so it is probed too rather than assumed — the point of this whole
+    // module is that nothing gets written into a marker on faith.
+    const npxFallback = (reason) => ({
+        launcher: npxLauncher,
+        how: "npx",
+        reason,
+        verified: runsOk("npx", npxLauncher.args) !== null,
+    });
+    if (opts.install === false)
+        return npxFallback("install not attempted");
+    // 2. Try to make `retasc` real.
+    const failure = installGlobal(opts.version);
+    // 3. Prove it, by running it. An exit code of 0 is not evidence the command resolves:
+    //    npm can install happily into a prefix whose bin directory PATH never searches.
+    if (!failure) {
+        if (runsOk("retasc")) {
+            return { launcher: { command: "retasc", args: [] }, how: "installed", verified: true };
+        }
+        // Installed, but PATH can't see it. Name the file directly — this is the case a
+        // shell one-liner can never recover from, because the shell fails before our code runs.
+        const prefix = npmGlobalPrefix();
+        for (const bin of prefix ? globalBinCandidates(prefix) : []) {
+            if (existsSync(bin) && runsOk(bin)) {
+                return { launcher: { command: bin, args: [] }, how: "absolute", binPath: bin, verified: true };
+            }
+        }
+    }
+    // 4. Nothing durable. Fall back, pinned, and let the caller say why.
+    return npxFallback(failure ?? "installed, but the binary could not be located or run");
+}
+/** What to tell the user about the outcome. One line, or none when nothing happened. */
+export function launcherNote(r) {
+    switch (r.how) {
+        case "on-path":
+            return null; // nothing changed; saying so is noise
+        case "installed":
+            return "✓ Installed `retasc` so your agent can start it directly.";
+        case "absolute":
+            return (`✓ Installed retasc at ${r.binPath}\n` +
+                "  Its folder isn't on your PATH, so your agent will use the full path above.\n" +
+                `  To type \`retasc\` yourself, add this to your shell profile:\n` +
+                `    export PATH="${r.binPath?.replace(/\/retasc$/, "")}:$PATH"`);
+        case "npx":
+            // Unverified is the one outcome where the workspace is written but NOT working.
+            // Say that outright: the whole defect this replaces was a setup that reported
+            // success and left the agent unable to start.
+            if (!r.verified) {
+                return (`! Couldn't install retasc${r.reason ? ` (${r.reason})` : ""}, and npx can't start it either.\n` +
+                    "  The marker was written, but your agent will NOT be able to start Retasc yet.\n" +
+                    "  Install the CLI, then run `retasc bind` again:  npm install -g @retasc/cli");
+            }
+            return (`! Couldn't install retasc globally${r.reason ? ` (${r.reason})` : ""}.\n` +
+                "  Your agent will start it through npx instead, which works but is slower\n" +
+                "  and needs the network. To fix it later, run:  npm install -g @retasc/cli");
+    }
+}

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Single source of truth for the version, read from package.json at runtime relative to
+// the COMPILED file (dist/version.js -> ../package.json). A JSON import won't work:
+// tsconfig has rootDir "src", so importing ../package.json is outside it.
+//
+// It lives in its own module because two places now need it — `--version`, and the
+// pinned npx fallback the MCP marker may name (RTSC-493). A marker pinned to a version
+// this build doesn't match would spawn a different CLI than the one that wrote it.
+export const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;

package/package.json

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