@retasc/cli 1.30.0 → 1.31.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.31.0 (2026-08-23)
+
+- **RTSC-713** — your agent can set Retasc up for you. It runs `bind` itself now, so
+  nothing asks you to open a terminal and type a command: you paste one line into the
+  chat, click Approve in the browser that opens, and restart your agent. The command it
+  runs is `bind --json`, the door built for a machine to drive.
+- **RTSC-713** — `bind --json` reports what it did and what it still needs, one JSON
+  object per line, and prints the approve URL the moment it exists rather than at the
+  end. Your agent posts that URL to you as a link, which is what makes this work on a
+  machine where the browser does not open by itself.
+- **RTSC-713** — a setup that paused is no longer dressed as a crash. "Signed in, but you
+  have not said which project this folder is for" exits 0 and says exactly that; only a
+  real dead end exits non-zero. It used to exit 1 with `✗ UNAUTHENTICATED`, and an agent
+  reading that reasonably concluded setup had failed and stopped, one question short of
+  done, holding a session that had actually worked.
+- **RTSC-713** — sign-in no longer refuses merely because nothing is attached to a
+  terminal. It asks whether a browser can be reached, which is the thing that actually
+  matters. SSH, containers and CI still refuse, and still refuse fast: over SSH the
+  approve link targets `127.0.0.1` on whichever machine opened it, so it could never
+  reach the CLI waiting on the remote host.
+- **RTSC-713** — every outcome names the absolute folder it is about to connect, so a
+  wrong one can be caught before anything is written. A wrong folder has no symptom
+  otherwise: the agent still calls in and the Dash still looks healthy.
+- **RTSC-691** — `retasc login` opens your browser instead of asking you to retype an
+  eight-character code. Click Approve once and you are signed in, and you pick GitHub,
+  Google or a passkey in the Dash where you are usually signed in already, instead of
+  answering that question in the terminal. The device flow is still there and still
+  works; it is the fallback now rather than the only door.
+- **RTSC-691** — the code path stays for the places a browser round trip cannot work:
+  inside a container, and over SSH, where the redirect would target `127.0.0.1` on
+  whichever machine opened the link and so could never reach the CLI waiting on the
+  remote host. `RETASC_NO_BROWSER=1` forces it everywhere.
+- **RTSC-691** — `retasc release <RTSC-NN> --claim-token <token>` exists. Two error
+  messages in `retasc claim` had been telling people to run it for a while, and it was
+  not a command. The token is the one printed when you claimed; the server fences on it,
+  which is what stops one agent releasing another's work. Releasing leaves your worktree
+  and branch alone — `retasc tidy` is what reaps those.
+- **RTSC-691** — `retasc bind` prints "restart your agent" whether or not a human is
+  watching. It was suppressed when output was not a terminal, which is exactly when an
+  agent is the one reading it and the one that has to pass the message on.
+- **RTSC-691** — `bind` clears the credential-less bootstrap entry that would otherwise
+  shadow the binding it just wrote, when the two land in different scopes.
+
 ## 1.30.0 (2026-08-20)
 
 - **RTSC-681** — your agent can read a file you attached to an issue. Uploading has

package/dist/auth.js

@@ -3,6 +3,7 @@ import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { loadConfig, patchConfig } from "./config.js";
 import { ask, isInteractive } from "./lib/prompt.js";
+import { startBrowserLogin } from "./lib/browserLogin.js";
 // The GitHub OAuth App's PUBLIC client id (safe to ship — device flow needs no
 // secret). Baked in so `retasc login` works out-of-the-box; override via env.
 const GITHUB_CLIENT_ID = process.env.RETASC_GITHUB_CLIENT_ID ?? "Ov23linqRy875IU8OYTW";
@@ -29,6 +30,46 @@ async function postForm(url, body) {
     return res.json();
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Can this machine plausibly complete a browser round trip (RTSC-691)?
+ *
+ * Three ways the answer is no, and each of them has cost somebody time:
+ *
+ *   • **No human.** A scripted or CI run has nobody to click, so waiting is waiting for
+ *     nothing.
+ *   • **SSH.** `isInteractive()` is true over SSH, which makes a TTY check exactly the
+ *     wrong gate. The redirect goes to 127.0.0.1 on the machine whose browser opened it,
+ *     so a human clicking on their laptop can never reach a listener on the remote host.
+ *     Not slow — impossible.
+ *   • **Explicitly opted out.** `RETASC_NO_BROWSER` is the documented switch (see
+ *     `cli/src/config.ts`) and is honoured HERE too, not only inside `openBrowser`.
+ *     Reading it in one place and not the other produced the worst outcome available: no
+ *     browser opens AND the caller still waits out the timeout. Deliberately ONE variable
+ *     — a second, undocumented knob is one nobody can find when they need it.
+ */
+export function canOpenBrowser(agentDriven = false) {
+    if (process.env.RETASC_NO_BROWSER)
+        return false;
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT)
+        return false;
+    // RTSC-713 — CI is the case the TTY check used to cover by accident.
+    //
+    // `agentDriven` drops the TTY requirement, because an agent's shell has no TTY and
+    // that was the entire reason cold `bind` was unreachable to one. But "no TTY" was also
+    // the only thing holding this door shut in CI, where nobody can click, the listener
+    // blocks for its full timeout, and the device flow it falls through to cannot complete
+    // either. So the guard the TTY check was silently providing is now stated outright,
+    // and it applies on BOTH paths: an agent running inside CI is still CI.
+    if (process.env.CI)
+        return false;
+    // An agent is a human's hands, not a human's absence — the person is in the chat, and
+    // the URL this door prints is relayed to them there. The property that must still hold
+    // is that a browser on THIS machine can reach the loopback listener, which is what the
+    // SSH check above is for and why it is not relaxed here.
+    if (agentDriven)
+        return true;
+    return isInteractive();
+}
 /**
  * Open a URL in the machine's browser, best effort (RTSC-676).
  *
@@ -49,7 +90,11 @@ function openBrowser(url) {
     const [cmd, args] = process.platform === "darwin"
         ? ["open", [url]]
         : process.platform === "win32"
-            ? ["start", ['""', url]]
+            ? // QUOTED: cmd.exe treats `&` as a command separator, and the sign-in URL is the
+                // first here to carry two query parameters (`?port=…&state=…`). Unquoted it
+                // opens a truncated link (the Dash then reports "that link is incomplete") and
+                // tries to run the remainder as a command.
+                ["start", ['""', `"${url}"`]]
             : ["xdg-open", [url]];
     try {
         const child = spawn(cmd, args, {
@@ -197,6 +242,42 @@ deps = {}) {
     }
     throw new Error("no valid choice — aborting");
 }
+/**
+ * Sign in through the browser and persist the session (RTSC-691).
+ *
+ * Prints the URL BEFORE waiting, unconditionally, for the same reason `announceCode`
+ * does: an auto-open that silently failed must leave the screen exactly as useful as it
+ * was. On a headless box the printed link is the whole path, and when an agent is
+ * driving, that printed line is what it relays to its human.
+ */
+async function browserLogin(deploymentUrl, dashUrl, onUrl) {
+    const { url, port, wait } = await startBrowserLogin(dashUrl);
+    // RTSC-713 — hand the URL to the caller BEFORE the wait, not only to the terminal.
+    //
+    // `startBrowserLogin` was already split in two so the URL exists before blocking; this
+    // is the other half of that split finally being used. An agent backgrounds this
+    // process and tails its output, so the URL reaching stdout here is what lets it post a
+    // clickable link into the chat while this call is still blocked on the click. Printed
+    // AND opened AND handed back: the browser popping up is the nice case, the link in the
+    // chat is the one that always works.
+    onUrl?.(url);
+    console.log(`\n  Open: ${url}\n`);
+    console.log("  Waiting for you to approve it in the browser…");
+    openBrowser(url);
+    const { code } = await wait();
+    const convex = new ConvexHttpClient(deploymentUrl);
+    const res = await convex.action(signIn, {
+        provider: "cli-browser",
+        params: { code, port },
+    });
+    const tokens = res?.tokens;
+    if (!tokens?.token)
+        throw new Error("Sign-in did not return a session token.");
+    // No `loginProvider` recorded: this door does not name an upstream identity, and
+    // writing one would make the next device-flow default a guess rather than a memory of
+    // what actually worked.
+    patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
+}
 /**
  * Run a device-flow login and persist the resulting Convex Auth session to
  * ~/.retasc/config.json. Prints the user code + verification URL.
@@ -204,8 +285,67 @@ deps = {}) {
  * With no `provider`, asks which door when a human is present and falls back to
  * GitHub when one isn't.
  */
-export async function deviceLogin(provider) {
+export async function deviceLogin(provider, opts) {
     const cfg = loadConfig();
+    // RTSC-691 — try the browser round trip FIRST when a human is present.
+    //
+    // For them it removes the eight characters they had to retype, and skips the
+    // which-door question entirely: they pick GitHub, Google or a passkey in the Dash,
+    // where they are often already signed in.
+    //
+    // GATED, and the gate is load-bearing rather than cautious. This path opens a listener
+    // and BLOCKS until somebody clicks. Where nobody can click it blocks for the full
+    // timeout and then falls through, turning a fast, honest refusal into a long hang — in
+    // CI, in a container, and in the CLI's own tests.
+    //
+    // A TTY check alone is NOT that gate, which is the trap here: `isInteractive()` is TRUE
+    // over SSH. On a remote box there is usually no browser to open, `xdg-open` is absent
+    // and its failure is swallowed by design, and — decisively — the redirect targets
+    // 127.0.0.1 on whichever machine opened the link, so a human clicking on their laptop
+    // can never reach a listener on the server. See canOpenBrowser().
+    //
+    // It does not help an agent-driven `bind` either, which was the original hope. An
+    // agent running a blocking command does not see stdout until the process exits, so a
+    // URL printed at the top of a five-minute wait reaches nobody. Making cold `bind`
+    // agent-runnable needs a two-step shape — print and exit, then complete — which is a
+    // different change; see RTSC-678.
+    //
+    // Naming a provider (`--github` / `--google`) still means the device flow, because
+    // that flag is a statement about which upstream identity to use and this path does not
+    // take one.
+    // RTSC-713 — an agent with no browser door has nowhere to fall to, so say so NOW.
+    //
+    // Found by the test for this, which hung. The device flow below prints a code to be
+    // retyped and then asks which door; both need a TTY, and an agent has neither. Falling
+    // through left the process blocked on a prompt nobody could see, which is the worst
+    // available outcome: not a refusal an agent can relay, just silence until something
+    // times out. SSH, containers and CI all land here, and for all three the honest answer
+    // is immediate.
+    if (opts?.agentDriven && !canOpenBrowser(true)) {
+        throw new Error("no browser available on this machine, and signing in needs one. " +
+            "Over SSH or in a container the approve link cannot reach this host: sign in on a " +
+            "machine with a browser and bind there, or run `retasc login` yourself at a terminal.");
+    }
+    if (!provider && canOpenBrowser(opts?.agentDriven)) {
+        try {
+            await browserLogin(cfg.deploymentUrl, cfg.dashUrl, opts?.onUrl);
+            return;
+        }
+        catch (e) {
+            // Every failure here is recoverable by the door below, so say what happened and
+            // carry on rather than ending a sign-in that can still succeed. A container with
+            // no browser is the expected case, not an error.
+            const why = e instanceof Error ? e.message : String(e);
+            console.error(`Browser sign-in didn't complete (${why}). Falling back to a code.`);
+            // RTSC-713 — but an agent has no fallback to fall to. The device flow below prints
+            // a code for someone to retype and then asks which door, both of which need a TTY.
+            // Continuing would hang until timeout and then fail with a message about a prompt
+            // nobody saw. Rethrow so the caller reports SIGN_IN_FAILED, which is honest and
+            // immediate, instead of a wait that ends in a lie.
+            if (opts?.agentDriven)
+                throw e;
+        }
+    }
     const door = provider ?? (await chooseProvider({ remembered: cfg.loginProvider }));
     const convex = new ConvexHttpClient(cfg.deploymentUrl);
     // Exchange the upstream token for a Retasc (Convex Auth) session. The token is

package/dist/commands/bind.js

@@ -9,6 +9,7 @@ import { resolveLauncher, launcherNote, runsOk, selfCommand, versionStamp } from
 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 { 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
@@ -445,8 +446,14 @@ export async function completeWorkspaceSetup(args) {
     //
     // AFTER the confirmation, and after everything that can throw, so it is only ever
     // printed by a run that actually finished. Nothing below it can fail.
+    // RTSC-691 — the restart line prints UNCONDITIONALLY. It was gated on a TTY, which is
+    // false in exactly the case that needs it most: when an agent runs `bind`, the agent is
+    // the only reader of this output, and it is the one that has to tell the human to
+    // restart. A setup that finished but never says so is indistinguishable from one that
+    // failed. The "what now" suggestions stay TTY-only — those are for a person browsing.
+    console.log(`\n${NEXT_STEP}\n`);
     if (isInteractive())
-        console.log(`\n${NEXT_STEP}\n\n${whatNow(pfx, emptyProject)}\n`);
+        console.log(`${whatNow(pfx, emptyProject)}\n`);
 }
 /**
  * The two sentences under `NEXT_STEP`, chosen by whether there is anything to pull yet
@@ -559,10 +566,20 @@ export const NEXT_STEP = "Start your agent in this folder, or restart it if it's
  * because "run this, but run the other one first" is not a single instruction. So the
  * sign-in is explicit, announced, and only when a human is present to authorize it.
  */
-export async function ensureSignedIn() {
+export async function ensureSignedIn(agent) {
     if (loadConfig().token)
         return;
-    if (!isInteractive()) {
+    // RTSC-713 — the no-TTY refusal now depends on whether a DOOR exists, not on whether
+    // this process has a terminal.
+    //
+    // The refusal was right about its own case and wrong about the one that matters here.
+    // Both doors need a human to act, so a process with nobody watching should stop fast.
+    // But an agent-driven run is not nobody watching: the human is in the chat, and the
+    // approve URL reaches them there. What actually has to be true is that a browser on
+    // this machine can reach the loopback listener, which is exactly what
+    // `canOpenBrowser()` decides. So ask it, instead of using "has a TTY" as a proxy for
+    // it — the proxy is what made cold `bind` unreachable to an agent.
+    if (!isInteractive() && !agent) {
         // RTSC-672 — the stamp rides in the HINT, not the message. `formatError` keeps only
         // the first line of a message (deliberately, to strip stack noise), so a second line
         // here would be silently dropped — which is how a diagnostic aimed at silent failures
@@ -573,10 +590,47 @@ export async function ensureSignedIn() {
     // announcing "GitHub" before the question would be wrong for the invited
     // teammate who signed up through Google — the exact person `join` is for.
     console.error("Not signed in yet — let's do that first.");
-    await deviceLogin();
+    await deviceLogin(undefined, agent ? { agentDriven: true, onUrl: agent.onUrl } : undefined);
 }
 export async function bindAction(opts) {
-    await ensureSignedIn();
+    // RTSC-713 — `--json` is the signal that a machine is driving, and it turns three
+    // things on at once: NDJSON on stdout, the browser door without a TTY, and continuable
+    // outcomes instead of thrown errors. One flag rather than three, because they are not
+    // independently useful: structured output nobody can act on, or a door that leads to a
+    // thrown Error, is each worse than neither.
+    const agent = opts.json
+        ? { onUrl: (url) => emit({ event: "approve_url", url }) }
+        : undefined;
+    const folder = process.cwd();
+    /** Continuable: say what is missing, exit 0. See lib/outcome.ts for why 0. */
+    const pause = (o) => {
+        if (agent)
+            emit({ event: "outcome", outcome: { ...o, continuable: true, folder } });
+    };
+    /** Terminal: nothing to be done from here, so exit non-zero and say so. */
+    const stop = (o) => {
+        if (agent)
+            emit({ event: "outcome", outcome: { ...o, continuable: false, folder } });
+        process.exitCode = 1;
+    };
+    try {
+        await ensureSignedIn(agent);
+    }
+    catch (e) {
+        if (!agent)
+            throw e;
+        // Sign-in was ATTEMPTED and did not complete. Distinct from arriving with no session,
+        // which is continuable — collapsing the two is what made the old refusal stop agents
+        // that had actually succeeded.
+        const why = e instanceof Error ? e.message : String(e);
+        stop({
+            state: /no browser|no door|RETASC_NO_BROWSER/i.test(why) ? "NO_SIGN_IN_DOOR" : "SIGN_IN_FAILED",
+            next: `Sign-in did not complete: ${why}. Tell your human what happened. ` +
+                `If this machine has no browser (a container, or SSH to a remote box), they can ` +
+                `sign in on a machine that does and bind there instead.`,
+        });
+        return;
+    }
     const cfg = loadConfig();
     // --- loud on re-bind -------------------------------------------------------
     // Runs before the org step on purpose: `--org-name` commits an org server-side, and a
@@ -611,6 +665,7 @@ export async function bindAction(opts) {
     if (!orgId) {
         const me = (await api.me());
         const orgs = me.orgs ?? [];
+        const pendingInvites = me.pendingInvites ?? [];
         if (isInteractive()) {
             const chosen = await pick("Select an org", orgs, (o) => `${o.name} (${o.slug})`);
             if (chosen) {
@@ -625,13 +680,94 @@ export async function bindAction(opts) {
                 console.log(`✓ Created org "${name}".`);
             }
         }
-        else if (orgs.length === 1) {
-            orgId = orgs[0].id; // unambiguous in a non-interactive run
+        else if (orgs.length === 1 && (!agent || !pendingInvites.length)) {
+            // Unambiguous in a non-interactive run. The invite check is scoped to `agent` ON
+            // PURPOSE: a scripted `bind` with one org has bound to that org since RTSC-91, and
+            // making a pending invitation suddenly turn that into an error would break existing
+            // automation for a question a script cannot answer anyway. The agent CAN ask, so
+            // for it the invite outranks the count.
+            orgId = orgs[0].id;
+        }
+        else if (agent) {
+            // RTSC-713 — the handoff, and the state this whole issue exists for.
+            //
+            // Sign-in SUCCEEDED and the session is on disk. All that is missing is which org
+            // this folder is for, which is a question, not a failure. It used to be
+            // `throw new Error("no org selected — pass --org-id …")`, written for a human at a
+            // shell, and an agent reading a thrown Error correctly concluded the run had failed
+            // and stopped one question short of done.
+            //
+            // Invites are checked BEFORE the count, and outrank a single existing org: someone
+            // holding an invitation who also owns a personal org must still be offered the
+            // team, or `bind` quietly points this folder at the wrong workspace and the join
+            // they were sent never happens.
+            const signedInAs = me.user?.email ?? me.user?.name;
+            pause({
+                state: pendingInvites.length ? "NEEDS_JOIN_OR_CREATE" : "NEEDS_ORG",
+                signedInAs,
+                orgs,
+                pendingInvites: pendingInvites.length ? pendingInvites : undefined,
+                missing: ["--org-id or --org-name", "--project or --project-id"],
+                next: pendingInvites.length
+                    ? `Signed in as ${signedInAs}. They have been invited to ` +
+                        `${pendingInvites.map((i) => `"${i.org}"`).join(", ")}. ASK whether they want to join ` +
+                        `that team or start their own workspace — do not choose for them. Joining uses ` +
+                        `\`join\`; starting fresh re-runs bind with --org-name. Getting this wrong creates a ` +
+                        `second organization that cannot be deleted.`
+                    : orgs.length === 0
+                        ? `Signed in as ${signedInAs}, with no organization yet. Ask what to call their ` +
+                            `workspace and their first project, then re-run with --org-name, --project and ` +
+                            `--prefix. Confirm the folder with them first: this will connect ${folder}.`
+                        : `Signed in as ${signedInAs}, with ${orgs.length} organizations. Ask which one ` +
+                            `THIS FOLDER is for and which project inside it, then re-run with --org-id and ` +
+                            `--project-id. Confirm the folder with them: this will connect ${folder}. ` +
+                            `If the folder plainly matches one of the projects and they pick another, say ` +
+                            `so once, then do as they say.`,
+            });
+            return;
         }
         else {
             throw new Error("no org selected — pass --org-id <id> or --org-name <name> (or run interactively).");
         }
     }
+    // RTSC-713 — settle the project BEFORE entering the strand window, when an agent is
+    // driving.
+    //
+    // Ordering, not tidiness. `completeWorkspaceSetup` resolves the project itself and
+    // ends in `cliError("AMBIGUOUS", …)` when it cannot, but by then this run may already
+    // have created an org — and an abort past that point strands one on the billing rail
+    // with no CLI delete (RTSC-297). Asking here means the pause happens while there is
+    // still nothing to strand.
+    //
+    // `firstProject()`, the from-scratch-or-import fork that mirrors the Dash's "where does
+    // your work come from?", is TTY-only and stays that way. Its question is now asked in
+    // chat instead, which is why the instruction below names the five trackers: without it
+    // someone arriving from Jira invents a project they did not want and leaves an empty
+    // one behind that cannot be deleted (RTSC-530).
+    if (agent && !opts.projectId && !(opts.project && opts.prefix)) {
+        const { projects } = (await api.listProjects({ orgId: orgId }));
+        const list = projects ?? [];
+        if (list.length === 1) {
+            opts = { ...opts, projectId: list[0].id }; // not a choice; asking would be noise
+        }
+        else {
+            pause({
+                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}.`,
+            });
+            return;
+        }
+    }
     // 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).
@@ -652,6 +788,31 @@ export async function bindAction(opts) {
         const hint = strandRecoveryHint({ createdOrgThisRun, orgId, bindingWritten });
         if (hint)
             console.error(hint);
+        if (agent) {
+            // The prose hint above is written for a terminal. An agent needs the same facts as
+            // a state it can act on, and this one IS terminal: a stranded org needs a human
+            // decision, not another pass.
+            stop({
+                state: "REFUSED",
+                org: { id: orgId, name: opts.orgName ?? orgId },
+                next: `Setup failed after the organization was created: ` +
+                    `${err instanceof Error ? err.message : String(err)}. ` +
+                    `Tell your human, and pass on that the organization already exists, so a retry ` +
+                    `must use --org-id ${orgId} rather than --org-name, or they end up with two.`,
+            });
+            return;
+        }
         throw err;
     }
+    // Bound. The folder, the org and the project are all settled and on disk, and the one
+    // thing left is the restart — which the agent has to ask for, because a client reads
+    // its MCP config at startup and nothing here can do it for them.
+    pause({
+        state: "BOUND",
+        org: { id: orgId },
+        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 ` +
+            `does not count; it has to be a new one. After the restart, call setup_status.`,
+    });
 }

package/dist/commands/claim.js

@@ -109,7 +109,11 @@ export async function claimAction(opts) {
         // point at the worktree instead of leaving the user stuck on the error.
         if (requestedId && /ALREADY_CLAIMED/.test(msg) && makeWorktree) {
             note(`  ${requestedId} is held. If it's your session, resume in ${parentDir}/${repoName}-${requestedId.toLowerCase()}`);
-            note(`  or \`retasc release ${requestedId}\` first.`);
+            // Deliberately does NOT suggest `release` here. A lease held by a DIFFERENT session
+            // is fenced: releasing it needs that session's claim token, which this caller does
+            // not have and should not have. Naming a command they cannot run is the dead end
+            // this hint exists to avoid. If it really is abandoned, the reclaimer frees it.
+            note(`  If it isn't yours, wait for the lease to lapse — the server reclaims it automatically.`);
         }
         process.exit(1);
     }
@@ -186,7 +190,11 @@ export async function claimAction(opts) {
             note(`  The branch already exists — attach without -b: git worktree add ${plan.path} ${plan.branch}`);
         }
         else {
-            note(`  Resolve the error and retry, or \`retasc release ${issueId}\` to return it to the pool.`);
+            // We hold this lease and its token, so name the command that actually works,
+            // token included — the caller has no other way to get it once this exits.
+            note(claim.claimToken
+                ? `  Resolve the error and retry, or return it to the pool:\n    retasc release ${issueId} --claim-token ${claim.claimToken}`
+                : `  Resolve the error and retry.`);
         }
         process.exit(1);
     }
@@ -225,3 +233,48 @@ function finish(path, branch, issueId, title, claimToken, opts) {
     note("");
     note(`  cd ${path}`);
 }
+/**
+ * `retasc release <RTSC-NN>` — hand a claimed issue back to the queue (RTSC-691).
+ *
+ * This command is here because two error paths in this same file already told people to
+ * run it (`claim.ts`, the "already held" and "worktree failed" hints) and it did not
+ * exist. A CLI that names a command it does not have is worse than one that says nothing:
+ * it sends somebody to a dead end at the exact moment they are already stuck.
+ *
+ * Deliberately does NOT touch git. The worktree and branch may hold real work, and this
+ * only returns the LEASE — `retasc tidy` is the command that reaps checkouts, and it
+ * refuses to remove anything dirty or unmerged. Keeping the two separate means giving
+ * work back is never the thing that loses it.
+ */
+export async function releaseAction(opts) {
+    const raw = opts.id ?? opts.issueArg;
+    if (!raw) {
+        throw new Error("Which issue? Pass one, e.g. `retasc release RTSC-42 --claim-token <token>`.");
+    }
+    const identifier = normalizeIssueId(raw);
+    if (!isValidIssueId(identifier)) {
+        throw new Error(`Not an issue id: ${raw}. Expected something like RTSC-42.`);
+    }
+    // The token is REQUIRED by the server and is not optional here either.
+    //
+    // `release_issue` is fenced: `assertHolds(issue, claimToken)` proves the caller is the
+    // session that actually holds the lease, which is the whole reason one agent cannot
+    // release another's work. The CLI does not persist claim tokens anywhere, so it cannot
+    // look one up — it prints the token when it claims, and this is where that print gets
+    // used. Refusing here, with the reason, beats sending a call the server will reject
+    // with a fence error the reader has no context for.
+    if (!opts.claimToken) {
+        throw new Error(`Releasing ${identifier} needs its claim token: \`retasc release ${identifier} --claim-token <token>\`.\n` +
+            `  The token is printed when you claim, and is in the \`--json\` output of \`retasc claim\`.\n` +
+            `  It proves you are the session holding the lease — without it the server cannot tell\n` +
+            `  your release from someone else's, and refuses.`);
+    }
+    const conn = resolveMcpConn({ mcpJson: readMcpJson() });
+    await mcpCall(conn, "release_issue", {
+        identifier,
+        claimToken: opts.claimToken,
+        ...(opts.note ? { note: opts.note } : {}),
+    });
+    console.log(`✓ Released ${identifier} back to the queue.`);
+    console.log("  Its worktree and branch are untouched — `retasc tidy` reaps those.");
+}

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ 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";
+import { hasClaudeLocalPlaceholder } from "../lib/binding.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. */
@@ -207,6 +208,37 @@ export function installMcp(opts) {
     console.log(mcpConfigBlock(opts.url, opts.key));
     console.log(`\nYour agent can now reach Retasc at ${opts.url}.`);
 }
+/**
+ * Clear a credential-less placeholder that would SHADOW the marker we are about to write
+ * (RTSC-691).
+ *
+ * Only ever removes an entry `isPlaceholderEntry` recognises — a bare URL with no
+ * credential — and only from the scope we are NOT writing to. Writing our own scope
+ * overwrites in place, so there is nothing to clean there.
+ *
+ * Removal goes through `claude mcp remove`, never by editing `~/.claude.json` ourselves.
+ * That file is rewritten constantly by a running Claude Code, so a read-modify-write from
+ * here would race it and could drop unrelated servers. Best-effort throughout: failing to
+ * tidy a placeholder must never fail a bind that otherwise succeeded, and `doctor`
+ * already reports a shadowed binding if one survives.
+ */
+function clearShadowingPlaceholder(scope) {
+    const dir = process.cwd();
+    // We wrote claude-local, so a folder placeholder is now harmless (local wins). We wrote
+    // the folder, so a claude-local placeholder would take every call — that is the one to
+    // clear.
+    if (scope === "local")
+        return;
+    if (!hasClaudeLocalPlaceholder(dir))
+        return;
+    const r = spawnSync("claude", ["mcp", "remove", "retasc", "-s", "local"], { encoding: "utf8" });
+    if (r.error || r.status !== 0) {
+        console.log("  Note: a credential-less `retasc` entry is still registered in Claude Code's local scope\n" +
+            "  and will shadow this one. Remove it with `claude mcp remove retasc -s local`.");
+        return;
+    }
+    console.log("✓ Removed the placeholder `retasc` entry that would have shadowed this binding.");
+}
 /**
  * RTSC-92: wire the SECRET-FREE watchdog marker into this folder. The key lives
  * in the home keystore under `workspaceId`; this writes only the pointer (env
@@ -231,10 +263,14 @@ export function installMarker(opts) {
     if (res.ok) {
         if (!opts.quiet)
             console.log(`✓ Registered Retasc watchdog (secret-free marker, scope: ${scope}).`);
+        clearShadowingPlaceholder(scope);
         return { where: `Claude Code (${scope})`, wroteFile: false };
     }
     // Always ./.mcp.json, whatever scope was asked for, so always the shared form.
     const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId, shared));
+    // We just wrote the folder marker, whatever scope was asked for, so a claude-local
+    // placeholder would now outrank it.
+    clearShadowingPlaceholder("project");
     if (!opts.quiet) {
         console.log(`✓ Wrote secret-free watchdog marker to ${path}`);
         console.log(`  ${fallbackNote(res)}`);

package/dist/config.js

@@ -5,9 +5,11 @@ import { randomUUID } from "node:crypto";
 // Production defaults. Overridable via env for dev/testing.
 //   RETASC_DEPLOYMENT_URL — Convex deployment (.cloud) for management calls
 //   RETASC_MCP_URL        — the MCP endpoint agents connect to
+//   RETASC_DASH_URL       — the Dash, for the browser sign-in round trip (RTSC-691)
 export const DEFAULTS = {
     deploymentUrl: process.env.RETASC_DEPLOYMENT_URL ?? "https://unique-lyrebird-934.convex.cloud",
     mcpUrl: process.env.RETASC_MCP_URL ?? "https://mcp.retasc.com/mcp",
+    dashUrl: process.env.RETASC_DASH_URL ?? "https://dash.retasc.com",
 };
 /** The dir config lives in. RETASC_DIR overrides it (tests, sandboxes) — same
  *  knob the keystore reads, so the two stay co-located. */
@@ -50,6 +52,7 @@ export function loadConfig() {
     return {
         deploymentUrl: stored.deploymentUrl ?? DEFAULTS.deploymentUrl,
         mcpUrl: stored.mcpUrl ?? DEFAULTS.mcpUrl,
+        dashUrl: stored.dashUrl ?? DEFAULTS.dashUrl,
         token: stored.token,
         refreshToken: stored.refreshToken,
         user: stored.user,

package/dist/index.js

@@ -5,7 +5,7 @@ import { selfCommand, versionStamp } from "./lib/launcher.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
-import { claimAction } from "./commands/claim.js";
+import { claimAction, releaseAction } from "./commands/claim.js";
 import { bindAction, setupFromToken } from "./commands/bind.js";
 import { joinAction } from "./commands/join.js";
 import { chooseInviteOrg, chooseInviteProjects } from "./commands/invite.js";
@@ -195,6 +195,13 @@ program
     // RTSC-495 — the agent's door. Everything this command normally asks was already
     // answered in the Dash, so the token stands in for all of it and nothing is prompted.
     .option("--setup <token>", "Complete setup from a Dash setup code — no sign-in, no prompts")
+    // RTSC-713 — the OTHER agent door, and the one that needs no Dash trip first.
+    //
+    // Three behaviours, deliberately on one flag because none is useful alone: NDJSON
+    // outcomes on stdout, the browser door without a TTY, and continuable states reported
+    // at exit 0 instead of thrown. Structured output an agent cannot act on, or a door
+    // that leads to a thrown Error, is each worse than neither.
+    .option("--json", "Report machine-readable outcomes (for an agent driving setup)")
     .action(async (opts) => {
     // BEFORE requireLogin: the whole point is a machine that has never signed in. The
     // token is the authorization, and asking for a session here would refuse every
@@ -593,6 +600,13 @@ program
 // Normalize --only to the canonical uppercase id so it matches the branch ids
 // scan() derives (rtsc-181/… → RTSC-181), same as `done` does for --id.
 tidyAction({ ...opts, only: opts.only ? String(opts.only).toUpperCase() : undefined }).catch(fail));
+program
+    .command("release [issue]")
+    .description("Hand a claimed issue back to the queue. Leaves your worktree and branch alone.")
+    .option("--id <RTSC-NN>", "The issue to release (or pass it positionally)")
+    .requiredOption("--claim-token <token>", "The claim token printed when you claimed it (the server fences on it)")
+    .option("--note <text>", "Handoff note for whoever picks it up next")
+    .action((issueArg, opts) => releaseAction({ issueArg, ...opts }).catch(fail));
 program
     .command("done")
     .description("Mark the current issue (rtsc-NN/ branch, or --id) done and tear down its worktree+branch.")

package/dist/lib/binding.js

@@ -119,6 +119,55 @@ export function readShadowedBinding(dir) {
         return undefined;
     return parseServerEntry(folderEntry(dir), "folder");
 }
+/**
+ * Is this a PLACEHOLDER entry — a bare URL with no credential of any kind (RTSC-691)?
+ *
+ * RTSC-678's flow starts by pointing the client at `https://mcp.retasc.com/mcp` with
+ * nothing else in it, so the server can answer the handshake with setup instructions.
+ * That entry is not a binding: it cannot authenticate, and every tool call through it
+ * fails. It exists to be replaced by the real one `bind` writes.
+ *
+ * It has to be recognised so it can be REMOVED, because scope precedence would otherwise
+ * make it win. `claude mcp add -t http` writes Claude-local scope by default; a `bind
+ * --scope project` writes `./.mcp.json`; and claude-local beats the folder marker at
+ * runtime (see the precedence note at the top of this file). Left in place, the finished
+ * setup would sit in a file nothing reads while the credential-less entry took every
+ * call — a setup that looks done and works nowhere.
+ *
+ * Deliberately narrow: a `url` and NO `command`, no env credential, no Authorization
+ * header. Anything carrying a credential, or spawning something, is somebody's real
+ * configuration and is never silently removed.
+ */
+export function isPlaceholderEntry(raw, knownUrls = PLACEHOLDER_URLS) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    if (typeof raw.url !== "string" || raw.url.length === 0)
+        return false;
+    if (typeof raw.command === "string")
+        return false;
+    if (raw.env && Object.keys(raw.env).length > 0)
+        return false;
+    // ANY header, not just Authorization. A gateway that injects credentials under some
+    // other name is still somebody's real configuration.
+    if (raw.headers && Object.keys(raw.headers).length > 0)
+        return false;
+    // And it must be the bootstrap URL we ourselves tell people to paste. This is the
+    // clause that matters: Claude Code stores MCP OAuth tokens OUTSIDE the server entry,
+    // keyed by server name, so a fully authorized OAuth binding is byte-identical to a
+    // placeholder by shape alone. RTSC-678 — this issue's parent — is about adding exactly
+    // that OAuth door, so shape-only matching would have grown a way to silently delete a
+    // working binding at the moment we shipped one.
+    return knownUrls.includes(normalizeUrl(raw.url));
+}
+/** The bare URLs we hand out for bootstrapping, normalized. */
+const PLACEHOLDER_URLS = ["https://mcp.retasc.com/mcp"];
+function normalizeUrl(u) {
+    return u.trim().replace(/\/+$/, "").toLowerCase();
+}
+/** Is there a placeholder in Claude Code's LOCAL scope for this folder? */
+export function hasClaudeLocalPlaceholder(dir) {
+    return isPlaceholderEntry(claudeLocalRetascEntry(dir));
+}
 /** A user-scope (global) Retasc server: top-level in Claude Code's config,
  *  NOT under projects[dir]. Illegal under DESIGN §13 override #1 — it applies
  *  to every folder that has no binding of its own, so issues can land in the

package/dist/lib/browserLogin.js

@@ -0,0 +1,80 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+/** How long to wait for the human to click Approve. Generous: they may have to sign in
+ *  to the Dash first, and possibly through GitHub or Google after that. */
+const WAIT_MS = 5 * 60 * 1000;
+/**
+ * Open a loopback listener and return the URL to send the browser to, plus a promise
+ * that resolves when the browser comes back.
+ *
+ * Split in two on purpose. The caller needs the URL BEFORE the wait starts, so it can
+ * print it — a printed URL is what makes this work when the browser fails to open, which
+ * is the common case on a headless Linux box where `xdg-open` is absent.
+ */
+export async function startBrowserLogin(dashUrl) {
+    const state = randomBytes(24).toString("hex");
+    let resolve;
+    let reject;
+    const settled = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // The timeout below rejects this promise whether or not anyone is awaiting it. A caller
+    // that takes `url`/`cancel` and never calls `wait()` would otherwise get an unhandled
+    // rejection, which is fatal on Node 15+. Attaching an inert handler at construction
+    // makes the promise safe to ignore; `wait()` still sees the real rejection.
+    settled.catch(() => { });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const code = url.searchParams.get("code");
+        const gotState = url.searchParams.get("state");
+        // The browser is a person's, so answer it in a way a person can read. Whatever
+        // happens here, the tab is finished with.
+        const reply = (status, body) => {
+            res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(`<!doctype html><meta charset="utf-8"><title>Retasc</title>` +
+                `<body style="font:16px system-ui;padding:3rem;max-width:32rem;margin:auto">${body}</body>`);
+        };
+        if (!code || gotState !== state) {
+            // A mismatched nonce means this redirect did not come from the flow we started.
+            // The code is not forwarded, so it expires unspent two minutes later.
+            reply(400, "<h1>Sign-in could not be verified</h1><p>Close this tab and run <code>retasc login</code> again.</p>");
+            return;
+        }
+        reply(200, "<h1>Signed in</h1><p>You can close this tab and go back to your terminal.</p>");
+        resolve({ code });
+    });
+    await new Promise((res, rej) => {
+        server.once("error", rej);
+        // Port 0: the OS picks a free one. Hard-coding a port would collide with a second
+        // `retasc login` and with whatever else the developer is running.
+        server.listen(0, "127.0.0.1", res);
+    });
+    const port = server.address().port;
+    const timer = setTimeout(() => {
+        reject(new Error(`TIMEOUT: no response from the browser within ${WAIT_MS / 60_000} minutes`));
+    }, WAIT_MS);
+    // Do not hold the process open on this timer alone.
+    timer.unref?.();
+    const close = () => {
+        clearTimeout(timer);
+        // `close()` stops accepting but leaves the browser's idle keep-alive socket open, and
+        // that handle holds the event loop until Node's 5s keepAliveTimeout fires — so the
+        // CLI would appear to hang for five seconds after a successful sign-in.
+        server.closeAllConnections?.();
+        server.close();
+    };
+    return {
+        url: `${dashUrl.replace(/\/+$/, "")}/cli-auth?port=${port}&state=${encodeURIComponent(state)}`,
+        port,
+        wait: async () => {
+            try {
+                return await settled;
+            }
+            finally {
+                close();
+            }
+        },
+        cancel: close,
+    };
+}

package/dist/lib/outcome.js

@@ -0,0 +1,102 @@
+/**
+ * What `bind` reports when an AGENT is driving it (RTSC-713).
+ *
+ * # Why this exists
+ *
+ * An agent decides whether to keep going from three signals, and all three are
+ * structural rather than semantic: the exit code, which stream the output came on, and
+ * whether the text reads like a fault. Before this module, "signed in, session written,
+ * nothing named yet" fired all three:
+ *
+ *     ✗ UNAUTHENTICATED: Not signed in. Run `npx -y @retasc/cli@1.30.0 login` first
+ *       (no TTY here for the device flow).
+ *
+ * An agent that stops there is reading the signals correctly. The signals were wrong.
+ * Sign-in had succeeded, the session was on disk, and the only thing left was a question
+ * it could have asked its human in one sentence.
+ *
+ * So the rule this module enforces: **the exit code and the framing encode "can I
+ * continue?", not "did something unexpected happen?"** A state the flow can be resumed
+ * from exits 0 on stdout and never says error, however incomplete it is. Only a genuine
+ * dead end — nothing the agent or its human can do from here — exits non-zero.
+ *
+ * # Why not just word the instruction better
+ *
+ * Telling the agent "if you see UNAUTHENTICATED it is fine, keep going" asks a model to
+ * override the strongest stop signal it has on the strength of a sentence it read
+ * earlier. Sometimes it will and sometimes it will not, and which one is not something
+ * this codebase controls. Exiting 0 is deterministic. This is the same reasoning that
+ * put the claim nudge and the setup instructions in the server response rather than in
+ * CLAUDE.md: a mechanism beats advice.
+ *
+ * # Why the states live HERE and not in the server's instruction string
+ *
+ * The obvious alternative was a lookup table in `convex/lib/setupInstructions.ts`: "if
+ * the CLI says X do this, if it says Y do that." That is a second copy of this list,
+ * living in a different language, in a different deploy cycle, maintained by whoever
+ * touches it next. They diverge, and the divergence is invisible until an agent acts on
+ * a state that no longer exists.
+ *
+ * This repo has already paid for that once. `setupInstructions.ts` opens by explaining
+ * it was lifted out of `http.ts` "because it now has TWO readers and they must never
+ * diverge", and RTSC-694 was an entire issue spent collapsing one setup command into one
+ * place. So: the CLI owns its states and each one carries its own next step, and the
+ * server instruction says only "run this, act on what it tells you." Adding a state
+ * costs one change, in this file, and no server string can go stale.
+ *
+ * There is a test that greps for these code strings under `convex/`. If one ever appears
+ * there, the split has been broken.
+ */
+/**
+ * Every terminal outcome of an agent-driven `bind`, in two classes.
+ *
+ * CONTINUABLE — the flow is alive and wants something. Exit 0, stdout, no fault
+ * vocabulary. The agent reads it, asks its human the one question that applies, and runs
+ * the next pass.
+ *
+ * TERMINAL — nothing the agent or its human can do inside this flow. Exit non-zero and
+ * say so plainly, because stopping is genuinely the right move.
+ *
+ * Note where NEEDS_SIGN_IN sits. Reaching a command with no session, having not yet
+ * tried to get one, is CONTINUABLE: the answer is to sign in, not to give up. Only a
+ * sign-in that was attempted and failed is terminal. Collapsing those two was the
+ * original bug.
+ */
+export const CONTINUABLE_STATES = [
+    /** No session, and no attempt has been made yet. The browser door is available. */
+    "NEEDS_SIGN_IN",
+    /** Signed in. Zero orgs, or more than one, so which org this folder is for is unknown. */
+    "NEEDS_ORG",
+    /** Org settled. Zero projects, or more than one, so which project is unknown. */
+    "NEEDS_PROJECT",
+    /**
+     * Signed in, and holding an invitation. The choice is join-or-create and it is the
+     * human's to make.
+     *
+     * NOT called PENDING_INVITE, deliberately: `convex/setupStatus.ts` already has a state
+     * by that name and it means something else — a membership offer the server is
+     * surfacing, rather than the reason `bind` stopped. Two different things sharing one
+     * identifier across the boundary is precisely the confusion this file's split exists to
+     * prevent, so this one is named for the decision it is asking for.
+     */
+    "NEEDS_JOIN_OR_CREATE",
+    /** Everything named and written. The folder is bound; the client must restart. */
+    "BOUND",
+];
+export const TERMINAL_STATES = [
+    /** Sign-in was attempted and did not complete: declined, timed out, or rejected. */
+    "SIGN_IN_FAILED",
+    /** No door exists: no browser reachable and no TTY. SSH and CI land here. */
+    "NO_SIGN_IN_DOOR",
+    /** This folder is already bound and the run was refused rather than silently re-pointed. */
+    "ALREADY_BOUND",
+    /** The credential was refused: revoked key, suspended member, deleted workspace. */
+    "REFUSED",
+];
+export function isContinuable(state) {
+    return CONTINUABLE_STATES.includes(state);
+}
+/** 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.30.0",
+  "version": "1.31.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": {