@retasc/cli 1.0.0 → 1.1.0

package/README.md

@@ -21,19 +21,25 @@ This installs the `retasc` command. Requires Node.js ≥ 18.
 ## Quickstart
 
 ```sh
-# 1. Sign in with GitHub (device flow)
+# 1. Sign in with GitHub (device flow) — once per machine
 retasc login
 
-# 2. Create an org + project, mint an agent key, and wire it into your agent — one shot
-retasc init --org "Acme" --project "Acme" --prefix ACME
+# 2. Bind THIS folder to one org + project (pick or create), and wire the watchdog
+cd ~/acme
+retasc bind
 
-# 3. Your agent (e.g. Claude Code) can now pull work over MCP
+# 3. Your agent (e.g. Claude Code) can now pull work over MCP — scoped to this folder
 ```
 
-`retasc init` creates the org and project, mints an agent API key, and registers the Retasc
-MCP server with your agent (writing `.mcp.json` or registering with Claude Code). From then on
-your agent calls `next_issue` / `next_batch` to atomically claim the top unblocked, prioritized
-work — and several agents can run at once without ever claiming the same issue.
+`retasc bind` is the per-workspace binder: it picks (or creates) an org + project, mints an
+agent API key for that pair, and wires the Retasc MCP server into **this folder only**. The key
+is stored in your home keystore (`~/.retasc/bindings.json`); the folder's `.mcp.json` is a
+**secret-free marker** (safe to commit). Each workspace is bound to exactly one org/project, so
+an agent can never file issues into the wrong one — the server enforces it by the key. From then
+on your agent calls `next_issue` / `next_batch` to atomically claim the top unblocked,
+prioritized work, and several agents run at once without ever claiming the same issue.
+
+Run `retasc whoami` (shows this folder's binding) or `retasc doctor` (checks it) any time.
 
 ## What the agent gets over MCP
 
@@ -50,8 +56,10 @@ work — and several agents can run at once without ever claiming the same issue
 | Command | What it does |
 |---------|--------------|
 | `retasc login` / `retasc logout` | Sign in / out (GitHub device flow) |
-| `retasc whoami` | Show the signed-in user and their orgs |
-| `retasc init …` | Create org + project, mint a key, wire the MCP — one shot |
+| `retasc bind` | Bind THIS folder to one org + project, wire the watchdog (the per-workspace setup) |
+| `retasc whoami` | Show this folder's org/project binding, plus your orgs |
+| `retasc doctor` | Check this folder is correctly + safely bound |
+| `retasc init …` | Create org + project, mint a key, wire the MCP — one shot (non-interactive) |
 | `retasc org create` / `retasc project create` | Create orgs / projects |
 | `retasc key mint \| list \| rotate \| revoke` | Manage agent API keys |
 | `retasc mcp install` | Register the Retasc MCP server with your agent |

package/dist/api.js

@@ -6,6 +6,7 @@ import { loadConfig } from "./config.js";
 // importing the parent's generated api.
 const fns = {
     me: makeFunctionReference("manage:me"),
+    listProjects: makeFunctionReference("manage:listProjects"),
     createOrg: makeFunctionReference("manage:createOrg"),
     createProject: makeFunctionReference("manage:createProject"),
     renameProjectPrefix: makeFunctionReference("manage:renameProjectPrefix"),
@@ -23,6 +24,7 @@ function client() {
 }
 export const api = {
     me: () => client().query(fns.me, {}),
+    listProjects: (args) => client().query(fns.listProjects, args),
     createOrg: (args) => client().mutation(fns.createOrg, args),
     createProject: (args) => client().mutation(fns.createProject, args),
     renameProjectPrefix: (args) => client().mutation(fns.renameProjectPrefix, args),

package/dist/commands/bind.js

@@ -0,0 +1,163 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { api } from "../api.js";
+import { loadConfig } from "../config.js";
+import { installMarker } from "./mcp.js";
+import { readLocalBinding, resolveBinding } from "../lib/binding.js";
+import { setBinding, newWorkspaceId } from "../lib/keystore.js";
+function isInteractive() {
+    return Boolean(stdin.isTTY && stdout.isTTY);
+}
+async function ask(question) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirm(question, assumeYes) {
+    if (assumeYes)
+        return true;
+    if (!isInteractive())
+        return false;
+    const a = (await ask(`${question} [y/N] `)).toLowerCase();
+    return a === "y" || a === "yes";
+}
+/** Pick from a list interactively, or return undefined to fall through to create. */
+async function pick(label, items, render) {
+    if (!items.length)
+        return undefined;
+    console.log(`\n${label}:`);
+    items.forEach((it, i) => console.log(`  ${i + 1}) ${render(it)}`));
+    console.log(`  ${items.length + 1}) + create new`);
+    const a = await ask("Choose a number: ");
+    const n = Number(a);
+    if (Number.isInteger(n) && n >= 1 && n <= items.length)
+        return items[n - 1];
+    return undefined; // create-new (or invalid → treated as create)
+}
+export async function bindAction(opts) {
+    const cfg = loadConfig();
+    const cwd = process.cwd();
+    // --- loud on re-bind -------------------------------------------------------
+    const existing = readLocalBinding(cwd);
+    if (existing) {
+        let where = "an existing Retasc binding";
+        try {
+            const b = await resolveBinding(existing.url || cfg.mcpUrl, existing.key);
+            where = `org "${b.org.name}" / project ${b.project.prefix}`;
+        }
+        catch {
+            /* key may be stale/revoked — still warn before replacing */
+        }
+        console.log(`This folder is already bound to ${where}.`);
+        if (!(await confirm("Replace it?", opts.yes))) {
+            console.log("Left unchanged.");
+            return;
+        }
+    }
+    // --- resolve org (pick / flag / create) ------------------------------------
+    let orgId = opts.orgId;
+    if (!orgId && opts.orgName) {
+        const org = (await api.createOrg({ name: opts.orgName }));
+        orgId = org.orgId;
+        console.log(`✓ Created org "${opts.orgName}".`);
+    }
+    if (!orgId) {
+        const me = (await api.me());
+        const orgs = me.orgs ?? [];
+        if (isInteractive()) {
+            const chosen = await pick("Select an org", orgs, (o) => `${o.name} (${o.slug})`);
+            if (chosen) {
+                orgId = chosen.id;
+            }
+            else {
+                const name = await ask("New org name: ");
+                if (!name)
+                    throw new Error("org name required");
+                orgId = (await api.createOrg({ name })).orgId;
+                console.log(`✓ Created org "${name}".`);
+            }
+        }
+        else if (orgs.length === 1) {
+            orgId = orgs[0].id; // unambiguous in a non-interactive run
+        }
+        else {
+            throw new Error("no org selected — pass --org-id <id> or --org-name <name> (or run interactively).");
+        }
+    }
+    // --- resolve project (pick / flag / create) --------------------------------
+    let projectId = opts.projectId;
+    let prefix;
+    if (!projectId && opts.project && opts.prefix) {
+        const p = (await api.createProject({ orgId: orgId, name: opts.project, prefix: opts.prefix }));
+        projectId = p.projectId;
+        prefix = p.prefix;
+        console.log(`✓ Created project ${p.prefix}.`);
+    }
+    if (!projectId) {
+        const { projects } = (await api.listProjects({ orgId: orgId }));
+        const list = projects ?? [];
+        if (isInteractive()) {
+            const chosen = await pick("Select a project", list, (p) => `${p.prefix} — ${p.name}`);
+            if (chosen) {
+                projectId = chosen.id;
+                prefix = chosen.prefix;
+            }
+            else {
+                const name = await ask("New project name: ");
+                const pfx = (await ask("Project prefix (e.g. ACME): ")).toUpperCase();
+                if (!name || !pfx)
+                    throw new Error("project name and prefix required");
+                const p = (await api.createProject({ orgId: orgId, name, prefix: pfx }));
+                projectId = p.projectId;
+                prefix = p.prefix;
+                console.log(`✓ Created project ${p.prefix}.`);
+            }
+        }
+        else if (list.length === 1) {
+            projectId = list[0].id;
+            prefix = list[0].prefix;
+        }
+        else {
+            throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
+        }
+    }
+    // --- mint a key for THIS (org, project) and wire the watchdog into THIS folder
+    const minted = (await api.mintKey({
+        orgId: orgId,
+        projectId: projectId,
+        agentName: opts.agent,
+        runtime: opts.runtime ?? "claude-code",
+        keyName: prefix ? `${prefix} key` : undefined,
+    }));
+    console.log(`✓ Minted key for this workspace (${minted.key.slice(0, 14)}…).\n`);
+    // RTSC-92: the secret stays OUT of the repo. Store it in the home keystore
+    // keyed by a workspace id; reuse this folder's existing id (so a re-bind, or a
+    // teammate's committed marker, keeps the same id) or mint a fresh one.
+    const workspaceId = existing?.workspaceId ?? newWorkspaceId();
+    setBinding(workspaceId, {
+        orgId: orgId,
+        projectId: projectId,
+        key: minted.key,
+        url: cfg.mcpUrl,
+        prefix,
+        orgName: undefined,
+        boundPath: cwd,
+        createdAt: Date.now(),
+    });
+    // Per-folder only (local scope), always watchdog. The marker carries only the
+    // workspace id — no secret — so ./.mcp.json is safe to commit.
+    installMarker({ workspaceId, scope: "local" });
+    // Confirm the binding the same way the agent will see it.
+    try {
+        const b = await resolveBinding(cfg.mcpUrl, minted.key);
+        console.log(`\n✓ This folder is bound to org "${b.org.name}" / project ${b.project.prefix}.\n` +
+            `  Agents launched here can only ever read or write ${b.project.prefix}.`);
+    }
+    catch {
+        /* binding written; whoami confirmation is best-effort */
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,78 @@
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "../config.js";
+import { readLocalBinding, resolveBinding } from "../lib/binding.js";
+import { getBinding } from "../lib/keystore.js";
+// RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
+// safely bound. Bound? Key valid (resolves to an org/project)? Watchdog wired?
+// And — the safety check — is there an illegal machine-global Retasc server that
+// could shadow per-folder bindings and leak issues across orgs?
+const ok = (m) => console.log(`  ✓ ${m}`);
+const warn = (m) => console.log(`  ! ${m}`);
+const bad = (m) => console.log(`  ✗ ${m}`);
+/** A user-scope (global) Retasc MCP server lives at the top level of
+ * ~/.claude.json; per-folder ones live under projects[path]. A top-level one is
+ * illegal under §13 — it would apply to every workspace. Best-effort detection. */
+function hasGlobalClaudeServer() {
+    const path = join(homedir(), ".claude.json");
+    if (!existsSync(path))
+        return false;
+    try {
+        const doc = JSON.parse(readFileSync(path, "utf8"));
+        return Boolean(doc?.mcpServers?.retasc);
+    }
+    catch {
+        return false;
+    }
+}
+export async function doctorAction() {
+    const cfg = loadConfig();
+    const cwd = process.cwd();
+    console.log(`Retasc workspace check — ${cwd}\n`);
+    // 1) Is this folder bound?
+    const local = readLocalBinding(cwd);
+    if (!local) {
+        bad("not bound — no Retasc MCP server in ./.mcp.json. Run `retasc bind`.");
+    }
+    else if (local.markerOnly) {
+        // RTSC-92: marker present (e.g. a cloned repo) but no key in this machine's
+        // keystore. Safe — the agent gets no tools — but the user must bind.
+        warn(`workspace marker present (${local.workspaceId}) but no key in your keystore.`);
+        bad("not usable yet on this machine — run `retasc bind` to mint your own key.");
+    }
+    else {
+        if (local.workspaceId) {
+            ok(`bound (secret-free marker → home keystore, ${local.workspaceId}).`);
+            // The id resolved, but if it was bound at a different folder, this marker
+            // may have reused someone else's id — surface it rather than silently use it.
+            const entry = getBinding(local.workspaceId);
+            if (entry?.boundPath && entry.boundPath !== cwd) {
+                warn(`this workspace id was bound at a different folder:\n` +
+                    `    ${entry.boundPath}\n` +
+                    `    If you didn't move this repo, re-run \`retasc bind\` to mint a key for THIS folder.`);
+            }
+        }
+        else if (local.legacy) {
+            ok("bound (legacy inline-key .mcp.json).");
+            warn("the key is stored IN this folder. Run `retasc bind` to move it to the keystore (secret-free marker).");
+        }
+        // 2) Does the key resolve to an org/project?
+        try {
+            const b = await resolveBinding(local.url || cfg.mcpUrl, local.key);
+            ok(`key valid → org "${b.org.name}" / project ${b.project.prefix} (${b.project.name}).`);
+        }
+        catch (e) {
+            bad(`key not accepted by the server: ${String(e?.message ?? e)}. Re-run \`retasc bind\`.`);
+        }
+    }
+    // 3) The safety check: any illegal global Retasc server?
+    if (hasGlobalClaudeServer()) {
+        bad("a GLOBAL Retasc MCP server is registered (~/.claude.json top level).\n" +
+            "    This applies to every workspace and can leak issues across orgs.\n" +
+            "    Remove it:  claude mcp remove -s user retasc");
+    }
+    else {
+        ok("no illegal global Retasc server.");
+    }
+}

package/dist/commands/mcp.js

@@ -2,6 +2,18 @@ import { spawnSync } from "node:child_process";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 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. */
+export function normalizeScope(s) {
+    if (s === "project")
+        return "project";
+    if (s === "user") {
+        console.error("  ! Global (--scope user) is not allowed for Retasc — each workspace must bind to\n" +
+            "    exactly one org/project. Using per-folder scope (local) instead.");
+        return "local";
+    }
+    return "local";
+}
 /** The MCP server entry we wire into an agent's config. */
 export function mcpServerEntry(url, key) {
     return {
@@ -31,6 +43,21 @@ export function mcpProxyEntry(url, key) {
 export function mcpProxyConfigBlock(url, key) {
     return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key) } }, null, 2);
 }
+/**
+ * RTSC-92: the SECRET-FREE watchdog marker. No key — only the opaque workspace
+ * id, which the proxy resolves to a key through the home keystore. Safe to
+ * commit; doubles as the "this repo is a Retasc workspace" marker.
+ */
+export function mcpMarkerEntry(workspaceId) {
+    return {
+        command: "retasc",
+        args: ["mcp-proxy"],
+        env: { RETASC_WORKSPACE: workspaceId },
+    };
+}
+export function mcpMarkerConfigBlock(workspaceId) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpMarkerEntry(workspaceId) } }, null, 2);
+}
 /** Try `claude mcp add`. Returns true on success, false if claude is absent or errored. */
 function tryClaudeCli(url, key, scope) {
     const args = [
@@ -54,6 +81,17 @@ function tryClaudeCliWatchdog(url, key, scope) {
     ];
     return runClaudeAdd(args);
 }
+/** Try `claude mcp add` for the secret-free stdio marker (RTSC-92). */
+function tryClaudeCliMarker(workspaceId, scope) {
+    const args = [
+        "mcp", "add",
+        "--transport", "stdio",
+        "--scope", scope,
+        "--env", `RETASC_WORKSPACE=${workspaceId}`,
+        SERVER_NAME, "--", "retasc", "mcp-proxy",
+    ];
+    return runClaudeAdd(args);
+}
 function runClaudeAdd(args) {
     const r = spawnSync("claude", args, { encoding: "utf8" });
     if (r.error)
@@ -90,7 +128,7 @@ function writeProjectMcpJson(entry) {
  * can paste it into any other MCP client.
  */
 export function installMcp(opts) {
-    const scope = opts.scope ?? "user";
+    const scope = opts.scope ?? "local";
     // Watchdog mode (RTSC-44): wire the stdio proxy so claims stay alive automatically.
     if (opts.watchdog) {
         const viaClaude = tryClaudeCliWatchdog(opts.url, opts.key, scope);
@@ -120,3 +158,23 @@ export function installMcp(opts) {
     console.log(mcpConfigBlock(opts.url, opts.key));
     console.log(`\nYour agent can now reach Retasc at ${opts.url}.`);
 }
+/**
+ * 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
+ * RETASC_WORKSPACE). Prefers the `claude` CLI, falls back to ./.mcp.json.
+ */
+export function installMarker(opts) {
+    const scope = opts.scope ?? "local";
+    const viaClaude = tryClaudeCliMarker(opts.workspaceId, scope);
+    if (viaClaude) {
+        console.log(`✓ Registered Retasc watchdog (secret-free marker, scope: ${scope}).`);
+    }
+    else {
+        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId));
+        console.log(`✓ Wrote secret-free watchdog marker to ${path}`);
+        console.log("  (Claude Code CLI not detected — used .mcp.json instead.)");
+    }
+    console.log("\nMarker block (any stdio MCP client) — no secret, safe to commit:\n");
+    console.log(mcpMarkerConfigBlock(opts.workspaceId));
+    console.log("\nThe key lives in your home keystore (~/.retasc/bindings.json), not in the repo.");
+}

package/dist/commands/tidy.js

@@ -0,0 +1,257 @@
+import { spawnSync } from "node:child_process";
+import { dirname, resolve, sep } from "node:path";
+import { resolveMcpConn, readMcpJson, mcpCall, isValidIssueId } from "../lib/claim.js";
+import { issueIdFromBranch, classifyBranch, parseWorktreePorcelain, } from "../lib/tidy.js";
+// `retasc tidy` / `retasc done` (RTSC-93). The CLI already creates the worktree +
+// branch on claim (commands/claim.ts); this closes the loop — it tears them down
+// when the issue is done, reading status read-only from the control plane and
+// doing the git here. The Retasc server never touches git; the CLI is the hands.
+function git(args, cwd) {
+    return spawnSync("git", args, { encoding: "utf8", cwd });
+}
+function gitOut(args, cwd) {
+    const r = git(args, cwd);
+    if (r.status !== 0)
+        return null;
+    return (r.stdout ?? "").trim();
+}
+function note(msg) {
+    process.stderr.write(msg + "\n");
+}
+const BASE = "origin/main";
+/** Resolve the MCP connection + the main checkout, or exit with a clear message. */
+function setup() {
+    const conn = resolveMcpConn({ mcpJson: readMcpJson() });
+    if (!conn.key) {
+        note("✗ No Retasc MCP key found. Run `retasc mcp install`, or set RETASC_MCP_KEY.");
+        process.exit(1);
+    }
+    const commonDir = gitOut(["rev-parse", "--git-common-dir"]);
+    if (!commonDir) {
+        note("✗ Not inside a git repository.");
+        process.exit(1);
+    }
+    // --git-common-dir always points at the MAIN checkout's .git, even from a linked
+    // worktree — so worktree/branch ops always run against the main checkout.
+    const mainCheckout = dirname(resolve(commonDir));
+    const currentBranch = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]);
+    return { conn, mainCheckout, currentBranch };
+}
+/** Build the reconciled branch table: every issue-shaped branch (local ∪ remote)
+ *  joined with its issue status (read-only) and merged-into-main state. */
+async function scan(ctx, only) {
+    const { conn, mainCheckout } = ctx;
+    // Refresh so merged-state + the remote list are current. Best-effort.
+    git(["fetch", "origin", "--prune"], mainCheckout);
+    const worktrees = parseWorktreePorcelain(gitOut(["worktree", "list", "--porcelain"], mainCheckout) ?? "");
+    const wtByBranch = new Map();
+    for (const w of worktrees)
+        if (w.branch)
+            wtByBranch.set(w.branch, w.path);
+    const refList = (refspec, strip) => (gitOut(["for-each-ref", "--format=%(refname:short)", refspec], mainCheckout) ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => (strip ? s.replace(strip, "") : s));
+    const locals = refList("refs/heads/");
+    const remotes = refList("refs/remotes/origin/", "origin/").filter((b) => b !== "HEAD");
+    const localSet = new Set(locals);
+    const remoteSet = new Set(remotes);
+    let branches = [...new Set([...locals, ...remotes])]
+        .filter((b) => issueIdFromBranch(b) !== null)
+        .sort();
+    if (only)
+        branches = branches.filter((b) => issueIdFromBranch(b) === only);
+    if (branches.length === 0)
+        return [];
+    // Read issue statuses — read-only against the control plane, one per unique id.
+    const uniqueIds = [...new Set(branches.map((b) => issueIdFromBranch(b)))];
+    const statusById = new Map();
+    await Promise.all(uniqueIds.map(async (id) => {
+        try {
+            const issue = (await mcpCall(conn, "get_issue", { identifier: id }));
+            statusById.set(id, typeof issue?.status === "string" ? issue.status : null);
+        }
+        catch {
+            statusById.set(id, null); // not found / error → untracked, never reaped
+        }
+    }));
+    return branches.map((branch) => {
+        const issue = issueIdFromBranch(branch);
+        const status = issue ? (statusById.get(issue) ?? null) : null;
+        const remote = remoteSet.has(branch);
+        // Merged check prefers the remote ref (authoritative); falls back to the local.
+        const ref = remote ? `origin/${branch}` : branch;
+        const merged = git(["merge-base", "--is-ancestor", ref, BASE], mainCheckout).status === 0;
+        return {
+            branch,
+            issue,
+            status,
+            merged,
+            verdict: classifyBranch({ status, merged }),
+            local: localSet.has(branch),
+            remote,
+            worktree: wtByBranch.get(branch) ?? null,
+        };
+    });
+}
+const VERDICT_LABEL = {
+    reap: "reap",
+    orphan: "orphan — review",
+    active: "active — keep",
+    untracked: "untracked",
+};
+function printTable(rows) {
+    const w = Math.max(...rows.map((r) => r.branch.length), 6);
+    note(`  ${"branch".padEnd(w)}  issue      status     merged  verdict`);
+    for (const r of rows) {
+        note(`  ${r.branch.padEnd(w)}  ${(r.issue ?? "—").padEnd(9)}  ${(r.status ?? "—").padEnd(9)}  ` +
+            `${(r.merged ? "yes" : "no").padEnd(6)}  ${VERDICT_LABEL[r.verdict]}`);
+    }
+}
+/** Delete one branch's artifacts (worktree → local branch → remote branch),
+ *  refusing anything unsafe. Returns whether it acted. */
+function reap(row, ctx, force) {
+    const { mainCheckout, currentBranch } = ctx;
+    if (row.branch === currentBranch) {
+        note(`  · skip ${row.branch} — it's your current branch (cd elsewhere to remove it)`);
+        return "skipped";
+    }
+    // `row.merged` was computed from the REMOTE ref, but we force-delete the LOCAL
+    // branch below. If the local branch carries commits not yet on origin/main
+    // (committed-but-unpushed), skip unless --force — so `branch -D` can't silently
+    // discard them. (--force is the consented escape hatch.)
+    if (row.local && !force) {
+        const localOnMain = git(["merge-base", "--is-ancestor", row.branch, BASE], mainCheckout).status === 0;
+        if (!localOnMain) {
+            note(`  · skip ${row.branch} — local branch has commits not on ${BASE} (unpushed?); --force to delete`);
+            return "skipped";
+        }
+    }
+    if (row.worktree) {
+        const insideTarget = resolve(process.cwd()) === resolve(row.worktree) ||
+            resolve(process.cwd()).startsWith(resolve(row.worktree) + sep);
+        if (insideTarget) {
+            note(`  · skip ${row.branch} — you're inside its worktree; cd out and re-run`);
+            return "skipped";
+        }
+        // Distinguish "clean" from "couldn't determine": a null (git error / stale
+        // path) must NOT read as clean. `worktree remove` (no --force) is the backstop.
+        const st = gitOut(["status", "--porcelain"], row.worktree);
+        if (st === null) {
+            note(`  · skip ${row.branch} — couldn't read its worktree state (${row.worktree})`);
+            return "skipped";
+        }
+        if (st !== "") {
+            note(`  · skip ${row.branch} — worktree has uncommitted changes (${row.worktree})`);
+            return "skipped";
+        }
+        const rm = git(["worktree", "remove", row.worktree], mainCheckout);
+        if (rm.status !== 0) {
+            note(`  ✗ ${row.branch}: worktree remove failed — ${(rm.stderr || "").trim().split("\n")[0]}`);
+            return "failed";
+        }
+    }
+    // -D is safe here: either the local branch is on origin/main (verified above) or
+    // the user passed --force. `--` guards against any future caller bypassing the
+    // issueIdFromBranch filter (the regex already forbids leading-dash names).
+    if (row.local) {
+        const d = git(["branch", "-D", "--", row.branch], mainCheckout);
+        if (d.status !== 0) {
+            note(`  ✗ ${row.branch}: local delete failed — ${(d.stderr || "").trim().split("\n")[0]}`);
+            return "failed";
+        }
+    }
+    if (row.remote) {
+        const p = git(["push", "origin", "--delete", row.branch], mainCheckout);
+        if (p.status !== 0) {
+            note(`  ✗ ${row.branch}: remote delete failed — ${(p.stderr || "").trim().split("\n")[0]}`);
+            return "failed";
+        }
+    }
+    note(`  ✓ reaped ${row.branch}`);
+    return "deleted";
+}
+/**
+ * `retasc tidy` — reconcile every `rtsc-NN/*` branch against its issue status and
+ * merged-state, then (with --prune) delete the ones whose work is done and on
+ * main. Dry-run by default. Orphans (done but unmerged) are only deleted with
+ * --force; untracked branches (no matching issue) are never touched.
+ */
+export async function tidyAction(opts) {
+    const ctx = setup();
+    const rows = await scan(ctx, opts.only);
+    if (rows.length === 0) {
+        note(opts.only ? `· No branch found for ${opts.only}.` : "· No issue branches (rtsc-NN/…) found.");
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+    }
+    else {
+        printTable(rows);
+    }
+    const reapable = rows.filter((r) => r.verdict === "reap");
+    const orphans = rows.filter((r) => r.verdict === "orphan");
+    const targets = [...reapable, ...(opts.force ? orphans : [])];
+    if (!opts.prune) {
+        note("");
+        const n = reapable.length;
+        note(n
+            ? `→ ${n} branch${n === 1 ? "" : "es"} reapable. Run \`retasc tidy --prune\` to delete${orphans.length ? `, \`--force\` to also clear ${orphans.length} orphan(s)` : ""}.`
+            : orphans.length
+                ? `→ no clean reaps; ${orphans.length} orphan(s) need review (done but unmerged) — \`--prune --force\` to delete.`
+                : "→ nothing to reap.");
+        return;
+    }
+    if (targets.length === 0) {
+        note("");
+        note(orphans.length ? "→ only orphans remain; re-run with --force to delete them." : "→ nothing to reap.");
+        return;
+    }
+    note("");
+    let deleted = 0;
+    let failed = 0;
+    for (const row of targets) {
+        const r = reap(row, ctx, !!opts.force);
+        if (r === "deleted")
+            deleted++;
+        else if (r === "failed")
+            failed++;
+    }
+    note(`✓ reaped ${deleted} branch${deleted === 1 ? "" : "es"}.${failed ? ` ${failed} failed.` : ""}`);
+    if (failed)
+        process.exitCode = 1; // let scripts/CI see a partial failure
+}
+/**
+ * `retasc done` — the symmetric close to `retasc claim`: mark the current issue
+ * (from the `rtsc-NN/` branch, or --id) done, then tear down its worktree+branch.
+ * Run it after the PR merges; an unmerged branch is kept (reported as an orphan)
+ * unless you pass --force. Run from the main checkout for full teardown — from
+ * inside the worktree it can't remove the tree you're standing in.
+ */
+export async function doneAction(opts) {
+    const conn = resolveMcpConn({ mcpJson: readMcpJson() });
+    if (!conn.key) {
+        note("✗ No Retasc MCP key found. Run `retasc mcp install`, or set RETASC_MCP_KEY.");
+        process.exit(1);
+    }
+    const currentBranch = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]);
+    // Normalize an explicit --id to the canonical uppercase form so `done --id rtsc-93`
+    // matches the uppercased branch ids (and is sent canonically to save_issue).
+    const issueId = opts.id ? opts.id.toUpperCase() : currentBranch ? issueIdFromBranch(currentBranch) : null;
+    if (!issueId || !isValidIssueId(issueId)) {
+        note("✗ Not on a rtsc-NN/ branch — pass --id <RTSC-NN>.");
+        process.exit(1);
+    }
+    try {
+        await mcpCall(conn, "save_issue", { identifier: issueId, status: "done" });
+    }
+    catch (e) {
+        note(`✗ Couldn't mark ${issueId} done: ${String(e?.message ?? e).split("\n")[0]}`);
+        process.exit(1);
+    }
+    note(`✓ ${issueId} → done`);
+    note("  tidying its branch…");
+    await tidyAction({ prune: true, force: opts.force, only: issueId });
+}

package/dist/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
-import { installMcp } from "./commands/mcp.js";
+import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate } from "./commands/gate.js";
 import { claimAction } from "./commands/claim.js";
+import { bindAction } from "./commands/bind.js";
+import { doctorAction } from "./commands/doctor.js";
+import { readLocalBinding, resolveBinding } from "./lib/binding.js";
+import { tidyAction, doneAction } from "./commands/tidy.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
 import { api } from "./api.js";
@@ -11,7 +15,7 @@ const program = new Command();
 program
     .name("retasc")
     .description("Retasc — sign in, create projects, mint agent API keys, and wire your agent to the MCP server.")
-    .version("1.0.0");
+    .version("1.1.0");
 function requireLogin() {
     if (!isLoggedIn()) {
         console.error("Not signed in. Run `retasc login` first.");
@@ -51,9 +55,32 @@ program
 });
 program
     .command("whoami")
-    .description("Show the signed-in user and their orgs.")
+    .description("Show THIS folder's org/project binding, plus the signed-in user and their orgs.")
     .action(async () => {
-    requireLogin();
+    // RTSC-91 (§13): lead with the binding for the folder you're in — the same
+    // "you are in org X / project Y" heads-up the agent gets — so a human can
+    // confirm scope before any work. Resolved from the local key, server-enforced.
+    const local = readLocalBinding(process.cwd());
+    if (local?.markerOnly) {
+        console.log("This folder → has a Retasc marker but no key on this machine. Run `retasc bind`.\n");
+    }
+    else if (local) {
+        try {
+            const b = await resolveBinding(local.url || loadConfig().mcpUrl, local.key);
+            console.log(`This folder → org "${b.org.name}" / project ${b.project.prefix} (${b.project.name})`);
+            console.log(`             as ${b.member.name}${b.member.session ? ` · session ${b.member.session}` : ""}\n`);
+        }
+        catch (e) {
+            console.log(`This folder → bound, but the key did not resolve: ${String(e?.message ?? e)}\n`);
+        }
+    }
+    else {
+        console.log("This folder → not bound. Run `retasc bind`.\n");
+    }
+    if (!isLoggedIn()) {
+        console.log("Not signed in (management). Run `retasc login` to manage orgs/projects.");
+        return;
+    }
     try {
         const me = await api.me();
         console.log(JSON.stringify(me, null, 2));
@@ -72,7 +99,7 @@ program
     .requiredOption("--prefix <PREFIX>", "Project prefix, e.g. XEN")
     .option("--agent <name>", "Agent member name (default: auto, \"{you}'s {runtime}\")")
     .option("--runtime <runtime>", "Agent runtime: claude-code | codex | opencode | …", "claude-code")
-    .option("--scope <scope>", "MCP install scope: local | user | project", "user")
+    .option("--scope <scope>", "MCP install scope: local | project (per-folder only)", "local")
     .option("--no-watchdog", "Wire a plain direct connection instead of the liveness watchdog")
     .action(async (opts) => {
     requireLogin();
@@ -95,14 +122,41 @@ program
             keyName: `${project.prefix} key`,
         }));
         console.log(`✓ Minted API key (${minted.key.slice(0, 14)}…).`);
-        const cfg = patchConfig({ defaultOrgId: orgId, defaultProjectPrefix: project.prefix });
+        // RTSC-91 (§13, override #2): never persist a global default org — binding
+        // is a per-folder act. (The prefix is kept only as a gate convenience.)
+        const cfg = patchConfig({ defaultProjectPrefix: project.prefix });
         console.log("");
-        installMcp({ url: cfg.mcpUrl, key: minted.key, scope: opts.scope, watchdog: opts.watchdog });
+        installMcp({ url: cfg.mcpUrl, key: minted.key, scope: normalizeScope(opts.scope), watchdog: opts.watchdog });
     }
     catch (e) {
         fail(e);
     }
 });
+// `retasc bind` — the canonical per-workspace binder (DESIGN §13). Interactive
+// pick/create org → project, mint, wire the watchdog into THIS folder; loud on
+// re-bind. Prefer this over `init` for binding an existing org/project.
+program
+    .command("bind")
+    .description("Bind THIS workspace folder to one org + project (pick/create), and wire the watchdog.")
+    .option("--org-id <id>", "Use an existing org id")
+    .option("--org-name <name>", "Create a new org with this name")
+    .option("--project-id <id>", "Use an existing project id")
+    .option("--project <name>", "Create a new project with this name (with --prefix)")
+    .option("--prefix <PREFIX>", "Prefix for a new project, e.g. ACME")
+    .option("--agent <name>", "Agent member name (default: auto)")
+    .option("--runtime <runtime>", "Agent runtime", "claude-code")
+    .option("-y, --yes", "Don't prompt to confirm replacing an existing binding")
+    .action(async (opts) => {
+    requireLogin();
+    await bindAction(opts).catch(fail);
+});
+// `retasc doctor` — verify this folder's binding + flag any illegal global server.
+program
+    .command("doctor")
+    .description("Check that THIS workspace is correctly and safely bound to one org/project.")
+    .action(async () => {
+    await doctorAction().catch(fail);
+});
 // --- org / project ---------------------------------------------------------
 const org = program.command("org").description("Manage orgs.");
 org
@@ -163,7 +217,7 @@ key
     .option("--runtime <runtime>", "Agent runtime: claude-code | codex | opencode | …", "claude-code")
     .option("--name <label>", "Key label")
     .option("--install", "Also wire the key into your agent via MCP")
-    .option("--scope <scope>", "MCP install scope if --install", "user")
+    .option("--scope <scope>", "MCP install scope if --install: local | project", "local")
     .action(async (opts) => {
     requireLogin();
     try {
@@ -179,7 +233,7 @@ key
         if (opts.install) {
             const cfg = loadConfig();
             console.log("");
-            installMcp({ url: cfg.mcpUrl, key: res.key, scope: opts.scope, watchdog: true });
+            installMcp({ url: cfg.mcpUrl, key: res.key, scope: normalizeScope(opts.scope), watchdog: true });
         }
     }
     catch (e) {
@@ -232,12 +286,12 @@ mcp
     .command("install")
     .description("Register the Retasc MCP server with your agent (Claude Code) or write .mcp.json.")
     .requiredOption("--key <key>", "A Retasc API key (from `retasc key mint`)")
-    .option("--scope <scope>", "local | user | project", "user")
+    .option("--scope <scope>", "local | project (per-folder only)", "local")
     .option("--url <url>", "Override the MCP URL")
     .option("--no-watchdog", "Wire a plain direct connection instead of the liveness watchdog (default: watchdog on)")
     .action((opts) => {
     const cfg = loadConfig();
-    installMcp({ url: opts.url ?? cfg.mcpUrl, key: opts.key, scope: opts.scope, watchdog: opts.watchdog });
+    installMcp({ url: opts.url ?? cfg.mcpUrl, key: opts.key, scope: normalizeScope(opts.scope), watchdog: opts.watchdog });
 });
 // Internal: the watchdog proxy, spawned by the harness (not for manual use).
 mcp
@@ -288,6 +342,20 @@ addClaimFlags(program
 addClaimFlags(program
     .command("next")
     .description("Claim the next unblocked issue and drop into a fresh worktree (alias of `claim`).")).action((opts) => claimAction(opts).catch(fail));
+// --- branch hygiene (close the worktree+branch claim opened) ----------------
+program
+    .command("tidy")
+    .description("Reconcile rtsc-NN/* branches against their issue status; reap the done+merged ones.")
+    .option("--prune", "Delete reapable branches + worktrees (default: dry-run, just report)")
+    .option("--force", "Also delete orphans (issue done but branch unmerged)")
+    .option("--json", "Emit the reconciled branch table as JSON")
+    .action((opts) => tidyAction(opts).catch(fail));
+program
+    .command("done")
+    .description("Mark the current issue (rtsc-NN/ branch, or --id) done and tear down its worktree+branch.")
+    .option("--id <RTSC-NN>", "The issue to close (default: derived from the current branch)")
+    .option("--force", "Tear down even if the branch isn't merged into main yet")
+    .action((opts) => doneAction(opts).catch(fail));
 // --- config ----------------------------------------------------------------
 program
     .command("config")

package/dist/lib/binding.js

@@ -0,0 +1,68 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getBinding } from "./keystore.js";
+/** Read the Retasc MCP entry from a folder's ./.mcp.json, if any. */
+export function readLocalBinding(dir) {
+    const path = join(dir, ".mcp.json");
+    if (!existsSync(path))
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const s = doc?.mcpServers?.retasc;
+    if (!s)
+        return undefined;
+    // Canonical (RTSC-92): secret-free marker → resolve the key from the keystore.
+    const workspaceId = s.env?.RETASC_WORKSPACE;
+    if (workspaceId) {
+        const entry = getBinding(workspaceId);
+        if (entry)
+            return { key: entry.key, url: entry.url, watchdog: true, workspaceId };
+        // Marker present but no keystore entry (e.g. a cloned repo) → needs binding.
+        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true };
+    }
+    // Legacy inline-key forms (pre-RTSC-92): key in env or the Authorization header.
+    if (s.env?.RETASC_MCP_KEY) {
+        return { key: String(s.env.RETASC_MCP_KEY), url: String(s.env.RETASC_MCP_URL ?? ""), watchdog: true, legacy: true };
+    }
+    const auth = s.headers?.Authorization ?? s.headers?.authorization;
+    if (auth) {
+        const m = String(auth).match(/^Bearer\s+(.+)$/i);
+        return { key: m ? m[1].trim() : String(auth).trim(), url: String(s.url ?? ""), watchdog: false, legacy: true };
+    }
+    return undefined;
+}
+/** Resolve a key's org/project by calling the MCP `whoami` tool (server-enforced
+ * scope — the same banner the agent sees). Throws on an invalid/revoked key. */
+export async function resolveBinding(url, key) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${key}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name: "whoami", arguments: {} },
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`MCP server returned ${res.status}`);
+    const body = await res.json();
+    if (body?.error)
+        throw new Error(body.error.message ?? "MCP error");
+    const result = body?.result;
+    if (result?.isError)
+        throw new Error(result?.content?.[0]?.text ?? "key not accepted");
+    const text = result?.content?.[0]?.text;
+    if (!text)
+        throw new Error("empty whoami response");
+    return JSON.parse(text);
+}

package/dist/lib/keystore.js

@@ -0,0 +1,52 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+/** The dir the keystore lives in. RETASC_DIR overrides it (tests, sandboxes). */
+function keystoreDir() {
+    return process.env.RETASC_DIR || join(homedir(), ".retasc");
+}
+export function keystorePath() {
+    return join(keystoreDir(), "bindings.json");
+}
+export function loadKeystore() {
+    const p = keystorePath();
+    if (!existsSync(p))
+        return { version: 1, bindings: {} };
+    try {
+        const doc = JSON.parse(readFileSync(p, "utf8"));
+        return { version: 1, bindings: doc?.bindings ?? {} };
+    }
+    catch {
+        // Corrupt keystore — don't crash; treat as empty (a re-bind heals it).
+        return { version: 1, bindings: {} };
+    }
+}
+export function saveKeystore(ks) {
+    mkdirSync(keystoreDir(), { recursive: true });
+    const p = keystorePath();
+    writeFileSync(p, JSON.stringify(ks, null, 2) + "\n", "utf8");
+    try {
+        chmodSync(p, 0o600); // secrets — user-only
+    }
+    catch {
+        /* best effort (e.g. Windows) */
+    }
+}
+export function getBinding(workspaceId) {
+    return loadKeystore().bindings[workspaceId];
+}
+export function setBinding(workspaceId, entry) {
+    const ks = loadKeystore();
+    ks.bindings[workspaceId] = entry;
+    saveKeystore(ks);
+}
+export function removeBinding(workspaceId) {
+    const ks = loadKeystore();
+    delete ks.bindings[workspaceId];
+    saveKeystore(ks);
+}
+/** A fresh opaque workspace id for a marker. Not secret, not a path. */
+export function newWorkspaceId() {
+    return `ws_${randomUUID()}`;
+}

package/dist/lib/tidy.js

@@ -0,0 +1,58 @@
+// Pure helpers for `retasc tidy` / `retasc done` (RTSC-93). Side-effect-free
+// (no git, no network) so branch→issue parsing, verdict classification, and the
+// worktree-porcelain parse can be unit-tested. The git + API work lives in
+// ../commands/tidy.ts.
+//
+// The principle: detecting a stale branch is a JOIN of two facts — the issue's
+// status (Retasc / control plane, read-only) and whether the branch is merged
+// (git / execution plane). This file is just the join logic; it owns no state.
+/**
+ * The issue id embedded in a `rtsc-NN/<slug>` branch name, normalized to the
+ * uppercase id (`rtsc-37/foo` → `RTSC-37`). Returns null for branches that don't
+ * follow the convention (`main`, `hotfix/x`, a bare `rtsc-37` with no slash) —
+ * those are never matched, so they can never be auto-deleted. Generic over the
+ * prefix, so it also matches `xen-12/…`.
+ */
+export function issueIdFromBranch(branch) {
+    const m = branch.match(/^([a-z][a-z0-9]*)-(\d+)\//);
+    return m ? `${m[1].toUpperCase()}-${m[2]}` : null;
+}
+/**
+ * Decide what to do with a branch from the join of issue status (control plane)
+ * and merged-into-main (execution plane):
+ *   - done/canceled + merged   → reap     (safe to delete; work is on main)
+ *   - done/canceled + unmerged → orphan   (review — work may have landed elsewhere)
+ *   - todo/doing/blocked       → active   (keep — work in progress)
+ *   - no matching issue        → untracked (report only — never auto-delete)
+ * `status` is null when no issue maps to the branch (off-convention name, or the
+ * issue wasn't found).
+ */
+export function classifyBranch(opts) {
+    const { status, merged } = opts;
+    if (status === null)
+        return "untracked";
+    if (status === "done" || status === "canceled")
+        return merged ? "reap" : "orphan";
+    return "active";
+}
+/**
+ * Parse `git worktree list --porcelain` into {path, branch}. Entries are blank-
+ * line separated; each starts with `worktree <path>`, and a `branch refs/heads/x`
+ * line names its branch (absent for detached worktrees).
+ */
+export function parseWorktreePorcelain(out) {
+    return out
+        .split(/\n\n+/)
+        .map((block) => {
+        const lines = block.split("\n");
+        const pathLine = lines.find((l) => l.startsWith("worktree "));
+        if (!pathLine)
+            return null;
+        const branchLine = lines.find((l) => l.startsWith("branch "));
+        const branch = branchLine
+            ? branchLine.slice("branch ".length).trim().replace(/^refs\/heads\//, "")
+            : null;
+        return { path: pathLine.slice("worktree ".length).trim(), branch };
+    })
+        .filter((w) => w !== null);
+}

package/dist/proxy.js

@@ -8,8 +8,26 @@
 import { createInterface } from "node:readline";
 import { hostname } from "node:os";
 import { applyObservation, heartbeatRequest, isClaimLost, } from "./lib/watchdog.js";
-const MCP_URL = process.env.RETASC_MCP_URL || "https://mcp.retasc.com/mcp";
-const KEY = process.env.RETASC_MCP_KEY || "";
+import { getBinding } from "./lib/keystore.js";
+// RTSC-92: resolve the workspace key. Canonical path — a secret-free marker sets
+// RETASC_WORKSPACE; we look the key up in the home keystore (never in the repo).
+// Legacy path — RETASC_MCP_KEY inlined in an old ./.mcp.json still works.
+function resolveKeyUrl() {
+    const envUrl = process.env.RETASC_MCP_URL || "https://mcp.retasc.com/mcp";
+    if (process.env.RETASC_MCP_KEY) {
+        return { key: process.env.RETASC_MCP_KEY, url: envUrl };
+    }
+    const wsId = process.env.RETASC_WORKSPACE;
+    if (wsId) {
+        const entry = getBinding(wsId);
+        if (entry)
+            return { key: entry.key, url: entry.url || envUrl };
+    }
+    return { key: "", url: envUrl };
+}
+const resolved = resolveKeyUrl();
+let MCP_URL = resolved.url;
+const KEY = resolved.key;
 const HEARTBEAT_MS = Number(process.env.RETASC_HEARTBEAT_MS) || 10 * 60 * 1000;
 const leases = new Map();
 let hbSeq = -1; // out-of-band heartbeat ids are negative — never collide with the harness's
@@ -63,6 +81,28 @@ async function adoptSessionKey() {
         log(`session-key mint failed (${String(e?.message ?? e)}) — using the workspace key`);
     }
 }
+/**
+ * RTSC-91 (DESIGN §13, D2): announce the binding to the HUMAN on startup, so the
+ * org/project this session will write into is visible in the harness's MCP logs
+ * before any work. Best-effort — never blocks serving traffic.
+ */
+async function announceBinding() {
+    try {
+        const resp = await postRemote({
+            jsonrpc: "2.0",
+            id: -1001,
+            method: "tools/call",
+            params: { name: "whoami", arguments: {} },
+        });
+        const r = toolResult(resp);
+        if (r?.org && r?.project) {
+            log(`bound → org "${r.org.name}" / project ${r.project.prefix}`);
+        }
+    }
+    catch {
+        /* announcement is best-effort */
+    }
+}
 // The tool result payload — the JSON inside result.content[0].text — or the raw result.
 function toolResult(resp) {
     try {
@@ -133,6 +173,7 @@ export async function runProxy() {
     // Adopt a per-session key BEFORE serving traffic, so even the first claim is
     // attributed to this session. stdin buffers in the OS pipe meanwhile.
     await adoptSessionKey();
+    await announceBinding();
     const timer = setInterval(() => void heartbeatAll(), HEARTBEAT_MS);
     timer.unref?.(); // the timer alone must not keep the process alive
     const rl = createInterface({ input: process.stdin });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {