@retasc/cli 1.31.1 → 1.33.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.33.0 (2026-08-23)
+
+- **RTSC-722** — the setup questions arrive as a matrix your agent can actually render.
+  1.32.0 sent three of the four as free text, and a picker cannot draw a question with no
+  options, so the whole set collapsed back into the numbered list in prose that RTSC-720
+  existed to remove. They now carry defaults derived from the folder you are standing in:
+  in `~/the egg` you get `The Egg`, `The Egg`, `EGG`, and the folder confirm, four clicks
+  instead of three typed answers. Every question keeps a "Something else" escape.
+  Folders that name nothing about the work (`/Users`, your home directory, `src`, a
+  dotfile, anything too long for the server to accept) suggest nothing and fall back to
+  text, because a plausible wrong default is worse than no default when what you are
+  confirming is which folder gets connected. Picking a project in an org that has more
+  than four is a picker too now, instead of an unrenderable list of every project.
+
+## 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 { answeredElsewhere, ELSEWHERE_VALUE, 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))
@@ -605,6 +640,31 @@ export async function bindAction(opts) {
         ? { onUrl: (url) => emit({ event: "approve_url", url }) }
         : undefined;
     const folder = process.cwd();
+    // RTSC-722 — the escape option's value is a sentinel, and this is where it stops being
+    // an answer. Every suggested question offers "Something else", and the agent is told to
+    // put the chosen value in the named flag; without this a human declining the suggestion
+    // creates a workspace literally called `__ask_me__`. Strip it here, at the boundary, so
+    // no downstream site has to know: the flag reads as unanswered, and the re-ask drops
+    // the suggestion this human just declined instead of offering it again.
+    const declined = answeredElsewhere(opts);
+    if (declined.size) {
+        opts = {
+            ...opts,
+            orgName: opts.orgName === ELSEWHERE_VALUE ? undefined : opts.orgName,
+            project: opts.project === ELSEWHERE_VALUE ? undefined : opts.project,
+            prefix: opts.prefix === ELSEWHERE_VALUE ? undefined : opts.prefix,
+            projectId: opts.projectId === ELSEWHERE_VALUE ? undefined : opts.projectId,
+        };
+    }
+    // What the agent has ALREADY collected, so the re-ask asks only for the rest. Computed
+    // after the strip: a sentinel is a decline, never an answer.
+    const answered = new Set();
+    if (opts.orgName)
+        answered.add("org.name");
+    if (opts.project)
+        answered.add("project.name");
+    if (opts.prefix)
+        answered.add("project.prefix");
     /** Continuable: say what is missing, exit 0. See lib/outcome.ts for why 0. */
     const pause = (o) => {
         if (agent)
@@ -711,6 +771,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, declined, answered),
                 next: pendingInvites.length
                     ? `Signed in as ${signedInAs}. They have been invited to ` +
                         `${pendingInvites.map((i) => `"${i.org}"`).join(", ")}. ASK whether they want to join ` +
@@ -758,15 +839,31 @@ export async function bindAction(opts) {
                 state: "NEEDS_PROJECT",
                 org: { id: orgId, name: opts.orgName ?? orgId },
                 projects: list,
-                missing: list.length ? ["--project-id"] : ["--project", "--prefix"],
-                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 ` +
-                        `connect ${folder}.`
-                    : `That organization has no projects yet. Ask what they are working on, and ` +
-                        `whether they want to bring a backlog across from Linear, Jira, Asana, ClickUp ` +
-                        `or Shortcut rather than start empty. Then re-run with --project and --prefix. ` +
-                        `Confirm the folder with them: this will connect ${folder}.`,
+                // RTSC-722 — once THIS run created the org, `--org-name` is a trap: the obvious
+                // agent move is to replay the previous argv with the missing flag added, which
+                // re-enters createOrg, hits `CONFLICT: org slug is taken` and exits 1. The
+                // instructions say a non-zero exit means stop, so the run dies one flag from
+                // working, with a stranded org. Naming --org-id here is what makes the retry
+                // survivable. The REFUSED branch below already warns about this; this pause is
+                // the one that reaches it, and did not.
+                missing: [
+                    ...(createdOrgThisRun ? [`--org-id ${orgId}`] : []),
+                    ...(list.length ? ["--project-id"] : ["--project", "--prefix"]),
+                ],
+                askHuman: projectQuestions(folder, list, declined),
+                next: (createdOrgThisRun
+                    ? `The organization "${opts.orgName}" now EXISTS — it was created by this run. ` +
+                        `Every retry from here must pass --org-id ${orgId} and must NOT pass ` +
+                        `--org-name again, which would try to create a second one and fail. `
+                    : "") +
+                    (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 ` +
+                            `connect ${folder}.`
+                        : `That organization has no projects yet. Ask what they are working on, and ` +
+                            `whether they want to bring a backlog across from Linear, Jira, Asana, ClickUp ` +
+                            `or Shortcut rather than start empty. Then re-run with --project and --prefix. ` +
+                            `Confirm the folder with them: this will connect ${folder}.`),
             });
             return;
         }
@@ -813,6 +910,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

@@ -47,6 +47,7 @@
  * There is a test that greps for these code strings under `convex/`. If one ever appears
  * there, the split has been broken.
  */
+import { homedir } from "node:os";
 /**
  * Every terminal outcome of an agent-driven `bind`, in two classes.
  *
@@ -96,6 +97,197 @@ 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.
+ */
+/**
+ * Names suggested from the folder, or null when the folder does not name anything
+ * (RTSC-722).
+ *
+ * Every question in the setup matrix needs OPTIONS, because a picker cannot render a
+ * question that has none — which is exactly why RTSC-720's three free-text questions
+ * came out as prose. The folder is where the defaults come from: somebody working in
+ * `~/the egg` almost certainly wants a workspace called The Egg, and the common case
+ * becomes a click rather than three typed answers.
+ *
+ * NULL for a folder that names nothing, and this guard is load-bearing rather than
+ * tidy. The run before this one had a human standing in `/Users` — suggesting "Users"
+ * as their workspace name would have made a WRONG binding easier to accept, which is
+ * the opposite of what the folder confirmation exists for. Home, root, a dotfile and
+ * the usual meaningless container directories all decline to suggest, and those
+ * questions fall back to text.
+ */
+const UNHELPFUL = new Set([
+    "users", "home", "root", "src", "lib", "tmp", "temp", "var", "opt", "etc", "desktop",
+    "documents", "downloads", "projects", "project", "code", "dev", "developer", "repos",
+    "repo", "workspace", "work", "apps", "app", "api", "web", "www", "site", "server",
+    "client", "backend", "frontend", "main", "new", "new folder", "untitled folder", "untitled",
+    "node modules", "git", "github", "test", "tests", "build", "dist",
+]);
+/** Longest suggestion worth offering. The server caps an org name at 120 (manage.ts
+ *  MAX_ORG_NAME), but a picker option is read at a glance and a folder whose basename
+ *  runs past this is not a workspace name anyway. */
+const MAX_SUGGESTED_NAME = 48;
+/** Case-folded, trailing-separator-free, for comparing two paths for sameness. */
+const samePath = (a, b) => a.replace(/[/\\]+$/, "").toLowerCase() === b.replace(/[/\\]+$/, "").toLowerCase();
+export function suggestNames(folder, home = homedir()) {
+    const trimmed = folder.replace(/[/\\]+$/, "");
+    // The home directory names the HUMAN, not the work. It is the likeliest wrong folder
+    // after `/Users` itself, and "Kim" as a workspace name is plausible enough to click
+    // past — which is exactly the wrong-folder binding the confirm exists to catch. The
+    // basename check below cannot see this: "kim" is not a generic container word.
+    // Case-insensitively, because macOS and Windows filesystems are: `/users/kim` and
+    // `/Users/kim` are the same directory and only one of them would match an exact compare.
+    if (home && samePath(trimmed, home))
+        return null;
+    const raw0 = trimmed.split(/[/\\]/).pop() ?? "";
+    // Fold accents to their ASCII base BEFORE splitting. The split treats every character
+    // outside [A-Za-z0-9] as a SEPARATOR, so without this `café-api` silently becomes
+    // "Caf Api" and `résumé` becomes "R Sum" — a confident, wrong, pre-filled default,
+    // which is the one thing this function's null-return exists to avoid. A basename that
+    // is entirely non-Latin already returns null (no words survive); it is the MIXED case
+    // that mangles.
+    const base = raw0.normalize("NFD").replace(/\p{Diacritic}/gu, "");
+    // Anything still outside ASCII after folding (CJK, Cyrillic, emoji) cannot be
+    // transliterated honestly, so decline rather than drop characters.
+    if (/[^\x20-\x7E]/.test(base))
+        return null;
+    // A dotfile directory, an empty basename (root), or a generic container names nothing
+    // about the work. `-2`/` 2` suffixes are stripped first, so "New Folder 2" and
+    // "project-3" decline the same way their unsuffixed forms do.
+    const generic = base.toLowerCase().replace(/[\s._-]+\d+$/, "").replace(/[_-]+/g, " ").trim();
+    if (!base || base.startsWith(".") || UNHELPFUL.has(generic))
+        return null;
+    const words = base.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (!words.length)
+        return null;
+    const name = words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+    // Do not offer a default the server will reject, or one a picker cannot show.
+    if (name.length > MAX_SUGGESTED_NAME)
+        return null;
+    // Must satisfy the server's own rule — /^[A-Z][A-Z0-9]{1,9}$/ (manage.ts). A suggested
+    // default the server then rejects is worse than no suggestion, because the human
+    // accepted it and the failure arrives afterwards, attributed to nothing they did.
+    const joined = words.join("").toUpperCase().replace(/[^A-Z0-9]/g, "");
+    // A mid-word truncation reads as a typo, and the prefix then appears in EVERY issue id
+    // in the project (renaming one is owner-gated and Dash-only). `a-very-long-project-name`
+    // as AVERYLONGP is worse than no suggestion; its initials, AVLPN, is a real prefix.
+    const prefix = joined.length <= 10
+        ? joined
+        : words.map((w) => w[0]).join("").toUpperCase().replace(/[^A-Z0-9]/g, "");
+    if (!/^[A-Z][A-Z0-9]{1,9}$/.test(prefix))
+        return null;
+    return { name, prefix };
+}
+/**
+ * The escape every suggested question carries, so the matrix never traps anyone.
+ *
+ * The value is a SENTINEL, not a word. `toElicitation` turns the option list into a JSON
+ * schema `enum`, and the instructions tell the agent to put the chosen value in the named
+ * flag — so a human-readable escape value like "other" arrives as `--org-name other` and
+ * names the workspace "other". `bind` rejects this exact string on every answer flag
+ * (`answeredElsewhere` below), so a mistake costs one more question rather than a wrongly
+ * named workspace. Enforced in the command, not in the wording: an instruction the agent
+ * can misread is not a guard.
+ */
+export const ELSEWHERE_VALUE = "__ask_me__";
+/** A picker renders at most four options (AskUserQuestion caps there, and a longer list
+ *  stops being scannable anyway). Emitting more is the RTSC-722 defect. */
+export const MAX_OPTIONS = 4;
+const ELSEWHERE = { value: ELSEWHERE_VALUE, label: "Something else — I'll tell you" };
+/**
+ * Which answers came back as the escape, so the re-ask does NOT re-offer the suggestion
+ * the human just declined. Without this the same matrix comes back unchanged and the
+ * exchange loops: suggestion, "something else", same suggestion.
+ */
+export function answeredElsewhere(opts) {
+    const out = new Set();
+    if (opts.orgName === ELSEWHERE_VALUE)
+        out.add("org.name");
+    if (opts.project === ELSEWHERE_VALUE)
+        out.add("project.name");
+    if (opts.prefix === ELSEWHERE_VALUE)
+        out.add("project.prefix");
+    return out;
+}
+export function orgQuestions(signedInAs, folder, declined = new Set(), answered = new Set()) {
+    const context = (signedInAs ? `Signed in as ${signedInAs}. ` : "") +
+        `These three answers create the workspace; the folder question is what connects ` +
+        `THIS folder to it.`;
+    const g = suggestNames(folder);
+    // With a usable folder name every question carries options, so all four render as ONE
+    // matrix and the common case is four clicks on pre-filled defaults. Without one they
+    // stay text — a wrong suggestion is worse than a typed answer.
+    // `hint` is documented on BOTH sides of the mirror (here and convex/lib/askHuman.ts) as
+    // meaningful only with `input: "text"`, so it rides the text branch only. A question
+    // showing THEEGG does not also need "e.g. ACME".
+    const suggested = (value, arg, id, question, hint) => g && !declined.has(id)
+        ? { id, question, options: [{ value, label: value }, ELSEWHERE], resume: { tool: "bind", arg } }
+        : { id, question, input: "text", ...(hint ? { hint } : {}), resume: { tool: "bind", arg } };
+    // An answer already in hand is not a question. Declining ONE of the three used to
+    // re-emit all three, so a human who had already named their project was asked for it a
+    // second time, and could answer differently the second time.
+    const all = [
+        { ...suggested(g?.name ?? "", "--org-name", "org.name", "What should your workspace (organization) be called?"), context },
+        suggested(g?.name ?? "", "--project", "project.name", "And the first project?"),
+        suggested(g?.prefix ?? "", "--prefix", "project.prefix", "A short prefix for issue ids?", "e.g. ACME"),
+        {
+            // 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" },
+        },
+    ];
+    return all.filter((q) => !answered.has(q.id));
+}
+export function projectQuestions(folder, projects, declined = new Set()) {
+    if (projects.length) {
+        // RTSC-722 again, on the path the first pass missed. A picker renders at most FOUR
+        // options, so an org with five projects reproduced the exact failure this issue is
+        // about: unrenderable, so the question degrades to prose. Show three and an escape;
+        // the outcome carries the FULL list in `projects`, so "none of these" means the agent
+        // reads that list out and passes the id the human picks — an escape, not a dead end.
+        const shown = projects.length <= MAX_OPTIONS ? projects : projects.slice(0, MAX_OPTIONS - 1);
+        const options = shown.map((p) => ({
+            value: p.id,
+            label: `${p.prefix ?? ""} — ${p.name ?? p.id}`.trim(),
+        }));
+        if (shown.length < projects.length) {
+            options.push({
+                value: ELSEWHERE_VALUE,
+                label: `None of these — show me all ${projects.length}`,
+            });
+        }
+        return [
+            {
+                id: "project.pick",
+                question: `Which project is ${folder} for?`,
+                options,
+                resume: { tool: "bind", arg: "--project-id" },
+            },
+        ];
+    }
+    // Same rule as orgQuestions: options where the folder names something, text where it
+    // does not. This path is reached with an org already chosen and no projects in it.
+    const g = suggestNames(folder);
+    const pick = (id) => g && !declined.has(id);
+    return [
+        pick("project.name")
+            ? { id: "project.name", question: "What is the first project called?", options: [{ value: g.name, label: g.name }, ELSEWHERE], resume: { tool: "bind", arg: "--project" } }
+            : { id: "project.name", question: "What is the first project called?", input: "text", resume: { tool: "bind", arg: "--project" } },
+        pick("project.prefix")
+            ? { id: "project.prefix", question: "A short prefix for issue ids?", options: [{ value: g.prefix, label: g.prefix }, ELSEWHERE], resume: { tool: "bind", arg: "--prefix" } }
+            : { 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.33.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": {