@retasc/cli 1.31.1 → 1.32.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.32.0 (2026-08-23)
+
+- **RTSC-720** — when `bind --json` stops to ask, it hands your agent the exact questions
+  as data: what to call the workspace, the first project, its prefix, and a confirmation
+  naming the precise folder about to be connected — with the flag each answer fills. Your
+  agent presents them instead of paraphrasing a status line, which is the difference
+  between being asked "what should we call it?" and being told "you have no organization"
+  by an agent waiting for you to notice.
+- **RTSC-721** — `retasc unbind` exists. It puts a folder back the way it was before
+  `bind`: the keystore entry, the MCP entry in either location it can live, and the
+  agent key — revoked server-side when your session can, named for the Dash when it
+  cannot. Until now undoing a binding meant hand-editing five places, one of them keyed
+  by an id nothing surfaces, with the key left live throughout. It confirms before
+  removing anything, names the absolute folder, and leaves your sign-in alone —
+  `retasc logout` is still its own decision.
+- **RTSC-721** — `bind` heals a dead binding instead of interrogating you about it. Come
+  back months later, after the workspace was deleted or the key revoked, and `bind` used
+  to ask "Replace it?" about a binding that no longer worked — a confusing question at
+  the exact moment you were least equipped to answer it. It now says the binding is no
+  longer accepted, clears it, and reconnects. Only on the server's own refusal: a network
+  failure still lands on the cautious path, because clearing a healthy credential to fix
+  a problem your machine does not have would be worse than asking.
+
 ## 1.31.1 (2026-08-23)
 
 - **RTSC-715** — setup no longer finishes by wiring a `retasc` command that is not there.

package/dist/commands/bind.js

@@ -3,13 +3,13 @@ import { api, cliError } from "../api.js";
 import { deviceLogin } from "../auth.js";
 import { loadConfig, patchConfig } from "../config.js";
 import { installMarker, printMarkerBlock } from "./mcp.js";
-import { readLocalBinding, resolveBinding } from "../lib/binding.js";
-import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
+import { readLocalBinding, resolveBinding, bindingRefused } from "../lib/binding.js";
+import { getBinding, setBinding, removeBinding, newWorkspaceId } from "../lib/keystore.js";
 import { resolveLauncher, launcherNote, onDurablePath, selfCommand, versionStamp } from "../lib/launcher.js";
 import { ask, confirm, isInteractive } from "../lib/prompt.js";
 import { clean } from "../lib/text.js";
 import { card, DOT } from "../lib/card.js";
-import { emit } from "../lib/outcome.js";
+import { emit, orgQuestions, projectQuestions } from "../lib/outcome.js";
 import { VERSION } from "../version.js";
 // RTSC-508: `ask`/`confirm`/`isInteractive` now live in lib/prompt.ts so `auth.ts`
 // can use them without closing an import cycle (bind → auth → bind). Re-exported
@@ -136,8 +136,43 @@ export async function rebindGuard(args) {
         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 */
+    catch (e) {
+        // RTSC-721 — a binding the server REFUSES is dead, and "Replace it?" is the wrong
+        // question to ask about a corpse.
+        //
+        // This is the months-later return: someone bound a folder, drifted away, and came
+        // back after their org was deleted or their key revoked. The local state is intact
+        // and points at nothing, and the person standing here does not know `unbind` exists —
+        // they ran `bind`, because `bind` is what they remember. Asking them to confirm
+        // replacing "an existing Retasc binding" is confusing precisely when they are least
+        // equipped to answer; there is nothing usable to preserve.
+        //
+        // ONLY on a refusal. `bindingRefused` matches the server's UNAUTHORIZED verdict and
+        // nothing else — a network blip or a 5xx falls through to the cautious path below,
+        // because clearing a healthy credential to fix a problem the machine does not have
+        // would be strictly worse than asking a confusing question. That asymmetry is the
+        // whole design: misread-refusal costs a question, misread-outage costs a credential.
+        //
+        // Non-interactive proceeds WITHOUT --yes, unlike the replace path below. Replacing a
+        // live binding destroys something; clearing a dead one does not, and an agent-driven
+        // `bind` (RTSC-713) that wedged here would need a human to relay a question about
+        // state the human cannot see.
+        if (bindingRefused(e)) {
+            console.log("This folder has a Retasc binding the server no longer accepts — the workspace " +
+                "may have been deleted, or the key revoked. There is nothing usable to keep.");
+            if (isInteractive() && !(await confirm("Clear it and reconnect?", args.yes))) {
+                console.log("Left unchanged.");
+                return { proceed: false, existing };
+            }
+            if (!isInteractive())
+                console.log("Clearing it and continuing.");
+            if (existing.workspaceId)
+                removeBinding(existing.workspaceId);
+            // Reuse the workspace id: the marker in this folder (possibly committed) already
+            // names it, and bind writes a fresh keystore entry under the same id.
+            return { proceed: true, existing };
+        }
+        /* network/unknown failure — key may still be fine; warn before replacing, as ever */
     }
     console.log(`This folder is already bound to ${where}.`);
     if (await confirm("Replace it?", args.yes))
@@ -711,6 +746,27 @@ export async function bindAction(opts) {
                 orgs,
                 pendingInvites: pendingInvites.length ? pendingInvites : undefined,
                 missing: ["--org-id or --org-name", "--project or --project-id"],
+                // RTSC-720 — the questions as data, so the agent presents them instead of
+                // authoring its own from the prose below. On the run that shaped this, the
+                // agent handed this state as a sentence asked its three questions in a
+                // paragraph; and after a restart the sentence read as a STATUS, so it reported
+                // "logged in but no organization" and waited for the human to notice.
+                askHuman: pendingInvites.length
+                    ? [
+                        {
+                            id: "onboarding.invite",
+                            question: `Join "${pendingInvites[0].org}", or start your own workspace?`,
+                            context: `You have a pending invitation. Joining puts your work in that team's ` +
+                                `organization; a new organization cannot be deleted from the terminal ` +
+                                `once created.`,
+                            options: [
+                                { value: "join", label: `Join "${pendingInvites[0].org}"`, detail: "Their projects, shared with the team that invited you." },
+                                { value: "own", label: "Start my own workspace", detail: "Pick this only if the invite was not meant for this work." },
+                            ],
+                            resume: { tool: "join" },
+                        },
+                    ]
+                    : orgQuestions(signedInAs, folder),
                 next: pendingInvites.length
                     ? `Signed in as ${signedInAs}. They have been invited to ` +
                         `${pendingInvites.map((i) => `"${i.org}"`).join(", ")}. ASK whether they want to join ` +
@@ -759,6 +815,7 @@ export async function bindAction(opts) {
                 org: { id: orgId, name: opts.orgName ?? orgId },
                 projects: list,
                 missing: list.length ? ["--project-id"] : ["--project", "--prefix"],
+                askHuman: projectQuestions(folder, list),
                 next: list.length
                     ? `That organization has ${list.length} projects. Ask which one THIS FOLDER is ` +
                         `for, then re-run with --project-id. Confirm the folder with them: this will ` +
@@ -813,6 +870,10 @@ export async function bindAction(opts) {
     pause({
         state: "BOUND",
         org: { id: orgId },
+        // The statement as data (tellHuman, RTSC-717's convention): exact words to relay,
+        // so "restart" survives the trip without being reworded into "you may need to".
+        tellHuman: `Setup is finished and ${folder} is connected. Restart me — start a NEW session, ` +
+            `not a resumed one — and then say "show me my issues".`,
         next: `Setup is complete and ${folder} is connected. TELL YOUR HUMAN it worked, name the ` +
             `folder and the project, and ask them to restart you — your Retasc tools only load ` +
             `when your client starts, so setup is not finished until they do. A resumed session ` +

package/dist/commands/mcp.js

@@ -277,6 +277,55 @@ export function installMarker(opts) {
     }
     return { where: path, wroteFile: true };
 }
+/**
+ * Remove the retasc entry from this folder's ./.mcp.json (RTSC-721).
+ *
+ * The inverse of `writeProjectMcpJson`, and just as narrow: it deletes ONLY the
+ * `retasc` server entry and leaves everything else — other servers, unknown keys —
+ * byte-for-byte where it was. If retasc was the last entry the file still stays,
+ * empty of servers, because deleting a file the user may have hand-edited is a
+ * bigger act than we were asked to perform.
+ *
+ * Returns whether anything was actually removed, so the caller's receipt reports
+ * what happened rather than what was attempted.
+ */
+export function removeProjectMarker(dir) {
+    const path = join(dir, ".mcp.json");
+    if (!existsSync(path))
+        return false;
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return false; // unparseable is not ours to rewrite
+    }
+    if (!doc?.mcpServers?.[SERVER_NAME])
+        return false;
+    delete doc.mcpServers[SERVER_NAME];
+    writeFileSync(path, JSON.stringify(doc, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    return true;
+}
+/**
+ * Ask Claude Code to drop its own retasc entry, best effort (RTSC-721).
+ *
+ * The marker may live in claude-local scope rather than ./.mcp.json (that scope WINS at
+ * runtime, which is exactly why it must not be left behind). `claude mcp remove` is the
+ * only sanctioned way to edit that config. Absent `claude`, or a failure, is reported,
+ * not thrown — unbind must finish its local work even where Claude Code is not installed.
+ */
+export function tryClaudeCliRemove() {
+    try {
+        const r = spawnSync("claude", ["mcp", "remove", SERVER_NAME, "-s", "local"], {
+            encoding: "utf8",
+            timeout: 30_000,
+        });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The MCP config block, printed ONLY when we could not write it anywhere (RTSC-673).
  *

package/dist/commands/unbind.js

@@ -0,0 +1,100 @@
+import { api } from "../api.js";
+import { isLoggedIn } from "../config.js";
+import { readLocalBinding } from "../lib/binding.js";
+import { getBinding, removeBinding, keystorePath } from "../lib/keystore.js";
+import { confirm, isInteractive } from "../lib/prompt.js";
+import { removeProjectMarker, tryClaudeCliRemove } from "./mcp.js";
+/**
+ * `retasc unbind` — put a folder back the way it was before `bind` (RTSC-721).
+ *
+ * Until this existed, undoing a binding meant knowing about, and hand-editing, five
+ * places: the keystore (keyed by an opaque ws_… id nothing surfaces), the folder's
+ * `.mcp.json`, Claude Code's local scope, the session file, and a server-side key that
+ * stayed LIVE through all of it. Mihnea, after repeated onboarding tests: "wipe clean is
+ * quite hard." It is also how you recover from binding the wrong folder — which nearly
+ * happened the same day, a `bind` about to connect `/Users` itself — and a wrong binding
+ * has no symptom once written (RTSC-532).
+ *
+ * Three rules, each earned:
+ *
+ *   • **Say what it will remove, then wait.** Same rule RTSC-716 set for the write side:
+ *     nothing irreversible happens without the human seeing the absolute path. `bind`
+ *     confirms before connecting; disconnecting is not less destructive.
+ *   • **Revoke, don't merely forget.** Dropping the local copy while the key stays live
+ *     is the worse half of what hand-editing did. Best-effort — the session may lack the
+ *     rights, or be signed out — and when it can't, it says where to finish the job
+ *     rather than pretending it did.
+ *   • **The session is left alone.** Signing out is `logout`'s job; conflating the two
+ *     turns "detach this folder" into "log me out everywhere", which nobody asked.
+ */
+export async function unbindAction(opts) {
+    const cwd = process.cwd();
+    const existing = readLocalBinding(cwd);
+    if (!existing) {
+        console.log("This folder has no Retasc binding. Nothing to do.");
+        return;
+    }
+    const entry = existing.workspaceId ? getBinding(existing.workspaceId) : undefined;
+    const keyPrefix = (entry?.key ?? existing.key ?? "").slice(0, 12);
+    console.log(`This will disconnect ${cwd} from Retasc:`);
+    if (entry?.orgName || entry?.prefix) {
+        console.log(`  bound to: ${entry.orgName ?? entry.orgId} / ${entry.prefix ?? entry.projectId}`);
+    }
+    if (existing.workspaceId)
+        console.log(`  keystore entry ${existing.workspaceId} in ${keystorePath()}`);
+    console.log(`  the retasc MCP entry for this folder`);
+    if (keyPrefix)
+        console.log(`  the agent key ${keyPrefix}… (revoked server-side, if this session can)`);
+    // Non-interactive without --yes refuses, exactly as rebindGuard does for a replace:
+    // a script must not be told success for a destruction it never confirmed.
+    if (!(await confirm("Proceed?", opts.yes))) {
+        if (!isInteractive()) {
+            console.error("✗ refusing to unbind non-interactively — pass --yes.");
+            process.exitCode = 1;
+        }
+        else {
+            console.log("Left unchanged.");
+        }
+        return;
+    }
+    // Revoke FIRST, while the keystore still holds what identifies the key. displayPrefix
+    // is how the server names keys (the raw value is never stored there), so the first 12
+    // chars of ours is the join.
+    if (entry?.orgId && keyPrefix && isLoggedIn()) {
+        try {
+            const { keys } = (await api.listKeys({ orgId: entry.orgId }));
+            const mine = (keys ?? []).find((k) => k.displayPrefix === keyPrefix && !k.revokedAt);
+            if (mine) {
+                await api.revokeKey({ keyId: mine.id ?? mine._id });
+                console.log(`✓ Revoked key ${keyPrefix}… server-side.`);
+            }
+            else {
+                console.log(`· Key ${keyPrefix}… not found server-side (already revoked, or the org is gone).`);
+            }
+        }
+        catch (e) {
+            console.log(`· Could not revoke the key from here (${e instanceof Error ? e.message.split("\n")[0] : e}). ` +
+                `Revoke ${keyPrefix}… from the Dash → API Keys.`);
+        }
+    }
+    else if (keyPrefix) {
+        console.log(`· Not signed in — revoke ${keyPrefix}… from the Dash → API Keys.`);
+    }
+    if (existing.workspaceId) {
+        removeBinding(existing.workspaceId);
+        console.log(`✓ Removed keystore entry ${existing.workspaceId}.`);
+    }
+    // The marker can live in either legal location, and claude-local WINS at runtime, so
+    // both are cleared: leaving that one behind is how a "removed" binding keeps answering.
+    const claudeRemoved = tryClaudeCliRemove();
+    const folderRemoved = removeProjectMarker(cwd);
+    if (claudeRemoved)
+        console.log("✓ Removed the Claude Code (local scope) entry.");
+    if (folderRemoved)
+        console.log("✓ Removed the retasc entry from ./.mcp.json.");
+    if (!claudeRemoved && !folderRemoved) {
+        console.log("· No MCP entry found to remove (it may live in a scope this command cannot edit).");
+    }
+    console.log("\nDone. Restart your agent so it stops loading the old server. Your sign-in is untouched — " +
+        "`retasc logout` if you want that too.");
+}

package/dist/index.js

@@ -7,6 +7,7 @@ import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
 import { claimAction, releaseAction } from "./commands/claim.js";
 import { bindAction, setupFromToken } from "./commands/bind.js";
+import { unbindAction } from "./commands/unbind.js";
 import { joinAction } from "./commands/join.js";
 import { chooseInviteOrg, chooseInviteProjects } from "./commands/invite.js";
 import { identityAction } from "./commands/identity.js";
@@ -228,6 +229,13 @@ program
     await bindAction(opts).catch(fail);
 });
 // `retasc doctor` — verify this folder's binding + flag any illegal global server.
+program
+    .command("unbind")
+    .description("Disconnect THIS folder from Retasc: keystore entry, MCP entry, and revoke the key.")
+    .option("-y, --yes", "Don't ask for confirmation")
+    .action(async (opts) => {
+    await unbindAction(opts).catch(fail);
+});
 program
     .command("doctor")
     .description("Check that THIS workspace is correctly and safely bound to one org/project.")

package/dist/lib/binding.js

@@ -103,6 +103,26 @@ export function claudeLocalRetascEntry(dir) {
     }
     return undefined;
 }
+/**
+ * Was this resolveBinding failure the SERVER refusing the key, or the network failing us
+ * (RTSC-721)?
+ *
+ * The difference decides whether a binding may be treated as DEAD. Every path in
+ * `resolveAuth` that declines a caller throws `UNAUTHORIZED: ...` (RTSC-703 pinned that),
+ * and that text rides back through the MCP error content into resolveBinding's throw. A
+ * network outage, a 5xx, or a timeout produces anything BUT that word.
+ *
+ * Matching narrowly matters more than matching completely: clearing a binding on a
+ * misread network blip would destroy a healthy credential to fix a problem the machine
+ * does not have. A refusal we fail to recognise merely falls back to the cautious
+ * "Replace it?" path, which is where every failure landed before this existed.
+ *
+ * NOT `isAuthError` from api.ts — that matcher looks for "unauthenticated"/OIDC shapes
+ * from the SESSION layer and does not match the MCP surface's "UNAUTHORIZED".
+ */
+export function bindingRefused(e) {
+    return /\bUNAUTHORIZED\b/i.test(String(e?.message ?? e));
+}
 /** Read the Retasc binding a folder's agent actually uses, from either legal
  *  location — claude-local first, matching Claude Code's runtime precedence. */
 export function readLocalBinding(dir) {

package/dist/lib/outcome.js

@@ -96,6 +96,52 @@ export const TERMINAL_STATES = [
 export function isContinuable(state) {
     return CONTINUABLE_STATES.includes(state);
 }
+/**
+ * The questions each continuable state asks, as pure builders so they are testable
+ * without a network. bindAction attaches their output to the outcome it emits.
+ */
+export function orgQuestions(signedInAs, folder) {
+    const context = (signedInAs ? `Signed in as ${signedInAs}. ` : "") +
+        `These three answers create the workspace; the folder question is what connects ` +
+        `THIS folder to it.`;
+    return [
+        { id: "org.name", question: "What should your workspace (organization) be called?", context, input: "text", resume: { tool: "bind", arg: "--org-name" } },
+        { id: "project.name", question: "And the first project?", input: "text", resume: { tool: "bind", arg: "--project" } },
+        { id: "project.prefix", question: "A short prefix for issue ids?", input: "text", hint: "e.g. ACME", resume: { tool: "bind", arg: "--prefix" } },
+        {
+            // The folder rides IN the exchange, not after it. It earned this on the run that
+            // shaped RTSC-720: the human was standing in /Users, the outcome named the path,
+            // and the agent caught it before anything was written. A wrong binding has no
+            // symptom once written (RTSC-532).
+            id: "bind.folder",
+            question: `Connect ${folder} to that project?`,
+            options: [
+                { value: "yes", label: `Yes — ${folder} is the right folder` },
+                { value: "no", label: "No — I am in the wrong folder", detail: "Open the right one and run setup there instead." },
+            ],
+            resume: { tool: "bind" },
+        },
+    ];
+}
+export function projectQuestions(folder, projects) {
+    if (projects.length) {
+        return [
+            {
+                id: "project.pick",
+                question: `Which project is ${folder} for?`,
+                options: projects.map((p) => ({
+                    value: p.id,
+                    label: `${p.prefix ?? ""} — ${p.name ?? p.id}`.trim(),
+                })),
+                resume: { tool: "bind", arg: "--project-id" },
+            },
+        ];
+    }
+    return [
+        { id: "project.name", question: "What is the first project called?", input: "text", resume: { tool: "bind", arg: "--project" } },
+        { id: "project.prefix", question: "A short prefix for issue ids?", input: "text", hint: "e.g. ACME", resume: { tool: "bind", arg: "--prefix" } },
+    ];
+}
 /** stdout, one line, no trailing prose. Never stderr: see the module header. */
 export function emit(e) {
     process.stdout.write(JSON.stringify(e) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.31.1",
+  "version": "1.32.0",
   "description": "Retasc CLI \u2014 the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {