@retasc/cli 1.49.1 → 1.51.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.51.0 (2026-09-13)
+
+- TODO: describe this release, and name the RTSC issue behind it.
+
+## 1.50.0 (2026-09-11)
+
+- **RTSC-901** — `retasc plan`: which subscription pays for each of your agents, listed
+  and set one line per (agent, harness). Retasc cannot read this anywhere — no transcript
+  field, telemetry attribute or environment variable carries it, and the only machine
+  source sits behind the human's own keychain — so it is asked for once and kept.
+  The options are READ FROM THE SERVER on every run, never compiled in: a tier a vendor
+  ships this morning is on the list this afternoon, on the build you already have.
+- **RTSC-901** — `bind` asks the same question at setup, but only when `--runtime` was
+  STATED. That flag defaults to `claude-code`, which is a fine label for a row and the
+  wrong subject for this question: `retasc setup` wires every harness on the machine, so
+  asking "which Claude plan?" of someone setting up Codex records a fact about the wrong
+  product. Left unstated, the question falls to the first MCP handshake, which knows
+  which harness actually connected.
+- A non-interactive run answers nothing rather than defaulting. A plan nobody chose reads
+  on the Agents page exactly like one they did.
+
 ## 1.49.1 (2026-09-09)
 
 - **RTSC-879** — the proxy sends NO `Authorization` header when it has no key, instead of

package/dist/api.js

@@ -16,6 +16,12 @@ const fns = {
     createProject: makeFunctionReference("manage:createProject"),
     renameProjectPrefix: makeFunctionReference("manage:renameProjectPrefix"),
     listKeys: makeFunctionReference("manage:listKeys"),
+    // RTSC-901 — the roster (for the agent rows and their plans) and the plan catalogue.
+    // The catalogue is fetched on every run and never cached to disk: a list cached in
+    // the client is the release-shaped list this issue exists to avoid.
+    listOrgMembers: makeFunctionReference("manage:listOrgMembers"),
+    listPlanCatalogue: makeFunctionReference("plans:listCatalogue"),
+    setMemberPlan: makeFunctionReference("plans:setMemberPlan"),
     mintKey: makeFunctionReference("manage:mintKey"),
     rotateKey: makeFunctionReference("manage:rotateKey"),
     revokeKey: makeFunctionReference("manage:revokeKey"),
@@ -210,6 +216,9 @@ export const api = {
     createProject: (args) => withAuth(() => client().mutation(fns.createProject, args)),
     renameProjectPrefix: (args) => withAuth(() => client().mutation(fns.renameProjectPrefix, args)),
     listKeys: (args) => withAuth(() => client().query(fns.listKeys, args)),
+    listOrgMembers: (args) => withAuth(() => client().query(fns.listOrgMembers, args)),
+    listPlanCatalogue: (args) => withAuth(() => client().query(fns.listPlanCatalogue, args)),
+    setMemberPlan: (args) => withAuth(() => client().mutation(fns.setMemberPlan, args)),
     mintKey: (args) => withAuth(() => client().action(fns.mintKey, args)),
     rotateKey: (args) => withAuth(() => client().action(fns.rotateKey, args)),
     revokeKey: (args) => withAuth(() => client().mutation(fns.revokeKey, args)),

package/dist/commands/bind.js

@@ -604,6 +604,45 @@ export async function completeWorkspaceSetup(args) {
     // 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.
+    // RTSC-901 — which plan pays for this agent. Asked ONCE, here, because this is the
+    // moment the agent row exists and a person is already at the keyboard.
+    //
+    // Three things this must not do, all of them worse than not knowing: block a
+    // non-interactive run (`select` returns null and we move on), ask again when this
+    // human already answered for this runtime (the roster hands back an inherited plan,
+    // so `plan` is set and the row is skipped), or fail the bind. The bind is the
+    // critical path and the plan is a nicety on top of it, so ANY failure here is
+    // swallowed — a missing plan costs a line on the Agents page, a failed bind costs
+    // the whole setup.
+    //
+    // Placed before the receipt so the last thing on screen is still the next step.
+    //
+    // ONLY WHEN THE RUNTIME WAS STATED. `--runtime` defaults to claude-code, which is a
+    // fine LABEL for a row and a bad subject for this question: `retasc setup` wires
+    // every harness on the machine, so asking "which Claude plan?" of someone setting up
+    // Codex records a fact about the wrong product, and a wrong plan is worse than none.
+    // Unstated, the question goes to the first handshake instead — `setup_status` reaches
+    // the same `askHuman` payload with the harness that actually connected.
+    if (isInteractive() && opts.runtimeStated) {
+        try {
+            const [roster, catalogue] = await Promise.all([
+                api.listOrgMembers({ orgId }),
+                api.listPlanCatalogue({ orgId }),
+            ]);
+            const runtime = opts.runtime ?? "claude-code";
+            const unanswered = roster.filter((m) => m.isAgent && m.mine && m.canSetPlan && m.runtime === runtime && !m.plansByClass?.[m.planBucket]);
+            // Exactly one, or we do not know which this bind created — and asking about the
+            // wrong agent records a fact under the wrong name.
+            if (unanswered.length === 1) {
+                const { askAndSet } = await import("./plan.js");
+                const cat = catalogue;
+                await askAndSet(orgId, unanswered[0], cat.byClass, { otherId: cat.otherId, declinedId: cat.declinedId });
+            }
+        }
+        catch {
+            // Never let this cost the bind. `retasc plan` asks the same question later.
+        }
+    }
     console.log(`\n${NEXT_STEP}\n`);
     if (isInteractive())
         console.log(`${whatNow(pfx, emptyProject)}\n`);

package/dist/commands/plan.js

@@ -0,0 +1,205 @@
+import { api } from "../api.js";
+import { ask, isInteractive, select } from "../lib/prompt.js";
+// Every value below came off the wire, and `cli/src/lib/text.ts` is the repo's rule
+// for that: an agent name or a plan label carrying \x1b[ can move the cursor, clear
+// the line and rewrite the rows above it. That matters most HERE, because this
+// command prints a list and then asks a question the reader answers by number, and
+// `mintKey` stores `agentName` and `runtime` verbatim — so any member of the org can
+// choose what lands on an owner's terminal.
+import { clean } from "../lib/text.js";
+// Nothing about plans is compiled in here — not the list, and not the two terminal
+// answers either. `cli/src/lib/outcome.ts` records why the CLI cannot import
+// `convex/lib`, and a mirrored copy of the vocabulary would be a second thing to keep
+// in step. So the ids come from the catalogue payload and the runtime class comes off
+// the roster row, both resolved server-side.
+/** What an agent nobody has answered for prints. Not a plan, so not from the server. */
+const NOT_SET = "Not set";
+// RTSC-901 — `retasc plan`: which plan pays for each of your agents.
+//
+// Retasc cannot see this. No hook payload, transcript field or telemetry attribute
+// carries the plan or the usage gauge, and the only machine source is an undocumented
+// per-account endpoint that needs the human's own credential. Retasc does not ask an
+// agent to read a credential store, so the fact is asked for and a person answers it.
+//
+// The options are READ FROM THE SERVER on every run, never compiled in. That is the
+// whole design: a tier a vendor shipped this morning is on this list this afternoon,
+// on the build you already have.
+/** The `retasc plan` list, and the picker when an agent is named. */
+export async function planAction(opts) {
+    const me = await api.me();
+    let orgId = opts.orgId;
+    if (!orgId) {
+        if (me.orgs.length === 0)
+            throw new Error("You're not a member of any org yet.");
+        if (me.orgs.length > 1) {
+            const list = me.orgs.map((o) => `  ${o.id}  ${o.name}${o.slug ? ` (${o.slug})` : ""}`);
+            throw new Error(`Several orgs — pass --org-id <id>:\n${list.join("\n")}`);
+        }
+        orgId = me.orgs[0].id;
+    }
+    const [roster, catalogue] = await Promise.all([
+        api.listOrgMembers({ orgId: orgId }),
+        api.listPlanCatalogue({ orgId: orgId }),
+    ]);
+    // Yours first. An owner can set anyone's, but the question this command answers is
+    // almost always about the machine it is being run on.
+    const agents = roster
+        .filter((m) => m.isAgent)
+        .sort((a, b) => Number(b.mine) - Number(a.mine) || a.name.localeCompare(b.name));
+    if (agents.length === 0) {
+        console.log("No agents in this org yet. Run `retasc setup` to wire one up.");
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(agents.flatMap((m) => classesOf(m).map((cls) => ({
+            id: m.id,
+            name: m.name,
+            runtime: m.runtime,
+            runtimeClass: cls,
+            plan: m.plansByClass?.[cls] ?? null,
+            canSet: m.canSetPlan,
+        }))), null, 2));
+        return;
+    }
+    const chosen = opts.agent
+        ? agents.find((m) => m.id === opts.agent || m.name.toLowerCase().includes(opts.agent.toLowerCase()))
+        : null;
+    if (opts.agent && !chosen) {
+        throw new Error(`No agent matching "${clean(opts.agent)}". Run \`retasc plan\` to see them.`);
+    }
+    if (!chosen) {
+        // ONE LINE PER (agent, harness), which is the unit an answer fills and the unit
+        // the Dash's Agents page draws. Listing one line per MEMBER read the plan for the
+        // runtime the member was BOUND as and nothing else, so an agent running both
+        // Claude Code and Codex showed one of them here and the other only in the Dash —
+        // and the terminal could not set the one it did not show.
+        console.log("");
+        for (const m of agents) {
+            for (const cls of classesOf(m)) {
+                const own = m.plansByClass?.[cls] ?? null;
+                const plan = own?.label ?? NOT_SET;
+                const tag = own?.inherited ? "  (from your other agent)" : "";
+                // Inlined rather than hoisted to a local: `plan901.test.ts` reads THIS file and
+                // requires every wire value to be cleaned at its print site, and a local hides
+                // which wire value the interpolation is carrying.
+                console.log(`  ${clean(m.name).padEnd(28)} ${clean(classLabel(m, cls)).padEnd(14)} ${clean(plan)}${tag}`);
+            }
+        }
+        const unset = agents.reduce((n, m) => n + (m.canSetPlan ? classesOf(m).filter((c) => !m.plansByClass?.[c]).length : 0), 0);
+        console.log("");
+        if (unset > 0)
+            console.log(`  ${unset} without a plan. Set one with \`retasc plan --agent <name>\`.`);
+        console.log("  You can also set these in the Dash under Agents.");
+        return;
+    }
+    if (!chosen.canSetPlan) {
+        throw new Error(`"${clean(chosen.name)}" is not yours to set. An owner or admin can set anyone's.`);
+    }
+    const cat = catalogue;
+    // A member can host several harnesses, and they are separate accounts with separate
+    // plans. Picking the agent is therefore not enough to know what is being answered —
+    // so when there is more than one, that is its own question, asked first.
+    const classes = classesOf(chosen);
+    let cls = classes[0];
+    if (classes.length > 1) {
+        const picked = await select(`\n${clean(chosen.name)} runs ${classes.length} harnesses. Which one?`, classes.map((c) => ({
+            id: c,
+            label: clean(classLabel(chosen, c)),
+            note: chosen.plansByClass?.[c] ? `Currently ${clean(chosen.plansByClass[c].label)}` : "No plan recorded",
+        })));
+        if (picked === null)
+            return;
+        cls = picked;
+    }
+    await askAndSet(orgId, {
+        ...chosen,
+        // The catalogue to offer. `unknown` is the bucket for a harness we cannot place,
+        // and it has no catalogue — so the picker is `other` and `declined`, which is
+        // the same answer the server gives for a null class.
+        planClass: cls === "unknown" ? null : cls,
+        runtimeName: classLabel(chosen, cls),
+        // Send the WIRE runtime for the member's own harness and the CLASS for a
+        // sibling. Both file under the same key, but the wire value is also recorded on
+        // an `other` answer as the restock signal's record of which harness said it, and
+        // "codex-mcp-client" teaches more there than "codex". For a sibling harness the
+        // roster does not tell us the wire value, so the class is the honest best.
+        runtime: cls === chosen.planBucket ? chosen.runtime : cls,
+    }, cat.byClass, { otherId: cat.otherId, declinedId: cat.declinedId });
+}
+/** The harness classes this agent should be answered for. `planClasses` is the
+ *  server's set, built from the member's own session keys; the bound runtime is the
+ *  fallback for a Dash loaded against an older backend. */
+function classesOf(m) {
+    const list = m.planClasses ?? [];
+    return list.length > 0 ? list : [m.planBucket];
+}
+/** What to call one of an agent's harnesses. The member's own runtime keeps its full
+ *  name ("Claude Code"); a sibling harness is named by its class, which is all the
+ *  roster knows about it. */
+function classLabel(m, cls) {
+    if (cls === m.planBucket && m.runtimeName)
+        return m.runtimeName;
+    return CLASS_NAMES[cls] ?? cls;
+}
+/** Class -> display name. Small and local: these are the eight buckets in
+ *  `convex/lib/runtime.ts`, and the CLI cannot import it (see `lib/outcome.ts`). A
+ *  class not here prints as itself, which is the same rule `runtimeLabel` follows. */
+const CLASS_NAMES = {
+    claude: "Claude Code",
+    codex: "Codex",
+    opencode: "OpenCode",
+    gemini: "Gemini",
+    cursor: "Cursor",
+    grok: "Grok",
+    ci: "CI",
+    unknown: "Unreported",
+};
+/**
+ * Put the list to the human and record what they pick.
+ *
+ * Exported so `retasc setup` asks the identical question through the identical code.
+ * Two copies of a question drift into two questions.
+ */
+export async function askAndSet(orgId, agent, byClass, 
+/** `otherId` / `declinedId`, straight from the catalogue payload. */
+ids) {
+    if (!isInteractive())
+        return false;
+    const options = (agent.planClass && byClass[agent.planClass]) || [];
+    const name = clean(agent.runtimeName || "this runtime");
+    const who = clean(agent.name);
+    const choices = [
+        // The catalogue is ours, but it is still served: clean it like anything else.
+        ...options.map((o) => ({ id: o.planId, label: clean(o.label), note: o.note ? clean(o.note) : null })),
+        // Always last, always present. The catalogue is knowingly incomplete, so there has
+        // to be somewhere for the plan we have not heard of to go — and on a runtime we do
+        // not know at all, these two ARE the list.
+        { id: ids.otherId, label: "Something else", note: "A plan that is not listed" },
+        { id: ids.declinedId, label: "Not shared", note: "Nothing is recorded, and you will not be asked again" },
+    ];
+    const heading = options.length > 0
+        ? `\nWhich plan pays for ${who}'s ${name} usage?`
+        : `\nRetasc has no plan list for ${name} yet. Which plan pays for ${who}?`;
+    const picked = await select(heading, choices);
+    if (picked === null)
+        return false;
+    let label;
+    if (picked === ids.otherId) {
+        label = await ask("Plan name, as it is billed: ");
+        if (!label.trim()) {
+            console.log("Nothing typed, so nothing recorded. Run `retasc plan` when you know it.");
+            return false;
+        }
+    }
+    // `agent.runtime` is what the CALLER decided this answer is about: the member's wire
+    // runtime for its own harness, the class for a sibling. It used to be the member's
+    // bound runtime unconditionally, so choosing the Codex line wrote the Claude key —
+    // the answer vanished from the row that asked for it and appeared on one that had
+    // not. `planStorageClassOf` maps a class to itself, so both spellings file alike.
+    const res = await api.setMemberPlan({ orgId, memberId: agent.id, runtime: agent.runtime ?? "", planId: picked, label });
+    console.log(`\n  ${who}: ${clean(res.label)}`);
+    // Both doors, every time. A person told once where to change something will not
+    // remember; a person told at the moment they answer knows they are not locked in.
+    console.log("  Change it any time with `retasc plan`, or in the Dash under Agents.\n");
+    return true;
+}

package/dist/index.js

@@ -231,7 +231,16 @@ program
     // 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) => {
+    .action(async (opts, cmd) => {
+    // RTSC-901 — was the runtime STATED, or is it the default sitting there?
+    //
+    // `--runtime` labels the agent row and defaults to claude-code, which is right for
+    // the label: most binds are Claude Code and a row needs a name. It is NOT right as
+    // the subject of the plan question. `retasc setup` wires every harness on the
+    // machine, so the folder rarely has one provider, and asking "which Claude plan?"
+    // of someone setting up Codex records a fact about the wrong product. When the
+    // flag was not stated, the plan question is left to the handshake, which knows.
+    opts.runtimeStated = cmd.getOptionValueSource("runtime") === "cli";
     // 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
     // caller this flag exists for.
@@ -596,6 +605,19 @@ program
 // RTSC-780 — the once-per-machine half of setup. `bind` runs this itself the first
 // time, so most people never type it; it exists on its own for the second harness
 // installed after a bind, and for re-running after an upgrade moved the launcher.
+// RTSC-901 — which plan pays for each agent. Asked once at setup and changeable here
+// forever after, which is the other half of the promise the setup receipt makes.
+program
+    .command("plan")
+    .description("Show or set which plan pays for each of your agents.")
+    .option("--org-id <id>", "Org, when you're in more than one")
+    .option("--agent <nameOrId>", "Set the plan for one agent")
+    .option("--json", "Machine-readable")
+    .allowExcessArguments(false)
+    .action(async (opts) => {
+    const { planAction } = await import("./commands/plan.js");
+    await planAction(opts);
+});
 program
     .command("setup")
     .description("Detect the MCP harnesses on this machine and wire Retasc into each, once.")

package/dist/lib/prompt.js

@@ -36,3 +36,43 @@ export async function confirm(question, assumeYes) {
     const a = (await ask(`${question} [y/N] `)).toLowerCase();
     return a === "y" || a === "yes";
 }
+/**
+ * Ask a human to PICK, by number, never to type a name (RTSC-901).
+ *
+ * Typing is how a plan called "Max 20x" gets recorded as "max20", "Max20x" and
+ * "MAX 20X" across three machines and then fails to group. Numbers make the common
+ * answer mechanical and leave typing for the case that genuinely needs it, which is
+ * an option this list does not have.
+ *
+ * Returns the chosen `id`, or `null` when there is nobody to ask: a non-interactive
+ * run SKIPS the question rather than blocking a script or guessing an answer. A
+ * question nobody answered has to stay unanswered — that is the difference between
+ * "not asked" and a wrong fact recorded forever.
+ *
+ * Enter alone takes `defaultId` when one is given, so the common path is one keypress.
+ */
+export async function select(question, choices, defaultId) {
+    if (!isInteractive() || choices.length === 0)
+        return null;
+    stdout.write(`${question}\n`);
+    for (let i = 0; i < choices.length; i++) {
+        const c = choices[i];
+        const mark = c.id === defaultId ? " (default)" : "";
+        stdout.write(`  ${String(i + 1).padStart(2)}. ${c.label}${mark}\n`);
+        if (c.note)
+            stdout.write(`      ${c.note}\n`);
+    }
+    // Three tries, then give up rather than loop at someone. A person who has typed
+    // nonsense three times is not going to type a number on the fourth, and a CLI that
+    // will not let go of the terminal is worse than an unanswered question.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const raw = await ask(defaultId ? `Number [${choices.findIndex((c) => c.id === defaultId) + 1}]: ` : "Number: ");
+        if (!raw && defaultId)
+            return defaultId;
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+            return choices[n - 1].id;
+        stdout.write(`  Pick a number between 1 and ${choices.length}.\n`);
+    }
+    return null;
+}

package/dist/lib/worktreeReport.js

@@ -0,0 +1,172 @@
+// RTSC-962 — the worktree census, as a PURE decision.
+//
+// The proxy watches for git worktrees on `rtsc-NN/<slug>` branches that no claim this
+// session took covers, and reports them so the server can record a provisional hold.
+// That closes the one transition Retasc could never see: an agent starting work. (The
+// end of work is fenced — `done` rejects on CLAIM_MISMATCH — and the start was not, so
+// an agent could build ~2,000 lines against an issue the queue showed as free. RTSC-910.)
+//
+// Everything decidable without I/O lives here, so every branch is unit-testable: which
+// trees count, which are ignored, and what the payload looks like. The proxy supplies
+// the three facts only the filesystem knows (the porcelain output, whether a tree is
+// dirty, its last commit time) and does nothing else.
+//
+// REPORT-ONLY, in both directions. Nothing here claims, blocks, or rewrites an agent's
+// request; and a report that fails is swallowed by the caller, never surfaced as a
+// failure of the tool call it rode alongside.
+import { issueIdFromBranch, parseWorktreePorcelain } from "./tidy.js";
+/**
+ * How recently a worktree must have been touched to count as ACTIVE.
+ *
+ * This is what stops an abandoned worktree parking an issue. A tree nobody has
+ * committed in for a day and that has no uncommitted work in it is finished business —
+ * somebody forgot to run `retasc tidy` — and reporting it would withhold an issue from
+ * dispatch on the strength of a directory. A day is deliberately generous: a real agent
+ * working across a weekend has uncommitted changes, which satisfies the other arm.
+ */
+export const ACTIVE_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Is this tree worth reporting? Dirty OR committed within the window.
+ *
+ * The two arms cover the two shapes real in-flight work takes: edits not yet committed
+ * (the RTSC-910 case, for most of its life) and commits not yet merged.
+ */
+export function isActive(state, now) {
+    if (state.dirty)
+        return true;
+    return state.lastCommitAt !== undefined && now - state.lastCommitAt < ACTIVE_WINDOW_MS;
+}
+/**
+ * The `rtsc-NN/<slug>` worktrees in this porcelain output, as {path, branch} pairs.
+ *
+ * Detached trees are dropped (`branch` is null — there is no issue to name) and so is
+ * any branch off the convention. The prefix match is `issueIdFromBranch`, the SAME
+ * parser `retasc tidy` uses to decide what it may delete and the mirror of the server's
+ * `branchForIssue` — so a branch this reports a hold for is exactly a branch a claim
+ * would have handed out.
+ *
+ * The MAIN checkout is included when it is itself on such a branch: an agent working in
+ * the shared checkout (the thing the claim contract tells it not to do) still leaves a
+ * branch to find, and that is the case most worth catching.
+ */
+export function candidateTrees(porcelain) {
+    const out = [];
+    for (const w of parseWorktreePorcelain(porcelain)) {
+        if (!w.branch)
+            continue; // detached, or bare
+        const identifier = issueIdFromBranch(w.branch);
+        if (!identifier)
+            continue;
+        out.push({ path: w.path, branch: w.branch, identifier });
+    }
+    return out;
+}
+/**
+ * The payload to send, from the candidate trees plus what git said about each.
+ *
+ * Two exclusions, both deliberate:
+ *  - INACTIVE trees (see `isActive`) — an abandoned directory must not park an issue.
+ *  - Issues THIS session already holds a lease on. It claimed them; the server knows;
+ *    a hold would be a worse copy of a fact it already has, and `report_worktrees`
+ *    would ignore it anyway. Skipping here keeps the payload honest rather than
+ *    relying on the server to discard most of it.
+ *
+ * Returns [] when there is nothing to say, which the caller uses to skip the call
+ * entirely — a proxy in a repo with no agent worktrees makes no requests at all.
+ */
+export function buildReport(opts) {
+    const heldSet = new Set(opts.held);
+    const reports = [];
+    const seen = new Set();
+    for (const t of opts.trees) {
+        if (heldSet.has(t.identifier))
+            continue; // we claimed it — nothing to report
+        if (seen.has(t.identifier))
+            continue; // one hold per issue, whatever the tree count
+        const st = opts.state.get(t.path);
+        if (!st)
+            continue; // git couldn't read the tree — say nothing rather than guess
+        if (!isActive(st, opts.now))
+            continue;
+        seen.add(t.identifier);
+        reports.push({
+            identifier: t.identifier,
+            branch: t.branch,
+            dirty: st.dirty,
+            ...(st.lastCommitAt !== undefined ? { lastCommitAt: st.lastCommitAt } : {}),
+        });
+    }
+    return reports;
+}
+/**
+ * Which holds are worth saying out loud right now, and the bookkeeping that keeps it to
+ * ONCE PER HOLD — mutating `announced` in place.
+ *
+ * Two rules, and the first one is the whole point:
+ *
+ *  - ANNOUNCE EACH HOLD ONCE. The instinct is to repeat the line until the agent acts,
+ *    and it is wrong: it is the failure the server-side riders are written against
+ *    (RTSC-463 — "a paragraph repeated on every claim becomes wallpaper"). A hold stands
+ *    for an hour, in which an agent can make a hundred tool calls. A line on all of them
+ *    is not obeyed more, it is skipped — and it teaches the agent to skip the next one.
+ *    The case that actually matters, a reader about to act on the issue, is caught again
+ *    server-side by the `get_issue` rider, which has the context to say something useful.
+ *  - FORGET a hold that has gone (claimed, closed, lapsed), so a genuinely new sighting
+ *    of the same issue later speaks up again.
+ *
+ * Pure but for `announced`, which is the caller's own set — so the ordering rule that
+ * matters (never mark a hold announced unless the line actually reached the response)
+ * stays enforceable by the caller, and testable here.
+ */
+export function holdsToAnnounce(active, announced, held = []) {
+    for (const id of [...announced])
+        if (!active.has(id))
+            announced.delete(id);
+    // Never announce a hold for an issue this session now HOLDS. The scan that confirmed
+    // the hold runs before the claim, so without this the very response to
+    // `claim_issue RTSC-N` carries "nobody holds RTSC-N, run `claim_issue RTSC-N`" — a
+    // line that contradicts the result it is stapled to, and which burns the single
+    // announcement this hold ever gets.
+    const heldSet = new Set(held);
+    return [...active.keys()].filter((id) => !announced.has(id) && !heldSet.has(id));
+}
+/**
+ * The line appended to the agent's own response when the server confirms a hold this
+ * proxy reported (RTSC-962).
+ *
+ * It rides the RESPONSE rather than a tool description for the reason RTSC-463 gives: a
+ * description is fetched once at `tools/list`, so it never reaches a session already
+ * running, and this has to land adjacent to the moment it is about.
+ *
+ * SHORT, and it names the branch, because the reader's next action is to look at that
+ * branch. Fires only while the hold stands — it clears the moment somebody claims.
+ */
+export function unclaimedNotice(holds, byIssue) {
+    if (holds.length === 0)
+        return "";
+    const parts = holds.map((id) => `\`${byIssue.get(id) ?? id}\` (${id})`);
+    const which = parts.length === 1 ? parts[0] : parts.join(", ");
+    const verb = parts.length === 1 ? "exists" : "exist";
+    const ids = holds.join(", ");
+    return (`⚑ Unclaimed work: a worktree on ${which} ${verb} on this machine and nobody holds ` +
+        `${ids}. If it is yours, run \`claim_issue ${holds[0]}\` now; if not, leave it — do not ` +
+        `start a second branch for it.`);
+}
+/** The JSON-RPC `report_worktrees` call the proxy sends out-of-band. */
+export function reportRequest(rpcId, worktrees) {
+    return {
+        jsonrpc: "2.0",
+        id: rpcId,
+        method: "tools/call",
+        params: { name: "report_worktrees", arguments: { worktrees } },
+    };
+}
+/** The issue ids the server confirmed it holds, from a `report_worktrees` result. */
+export function holdsFrom(result) {
+    if (!result || typeof result !== "object")
+        return [];
+    const holds = result.holds;
+    if (!Array.isArray(holds))
+        return [];
+    return holds.filter((h) => typeof h === "string");
+}

package/dist/proxy.js

@@ -17,6 +17,7 @@ import { mintSessionKey, appendFallbackNotice, recordSession, nameWorkspace, RPC
 import { readHookRecord, clearHookRecord, modelFromTranscript } from "./lib/sessionHook.js";
 import { VERSION } from "./version.js";
 import { attachRoot, isLocalAttachCall, mergeAttachTool, readAttachFile, resolveAttachPath, uploadFailureMessage, uploadUrlWith, } from "./lib/attachFile.js";
+import { buildReport, candidateTrees, holdsFrom, holdsToAnnounce, reportRequest, unclaimedNotice, } from "./lib/worktreeReport.js";
 import { MAX_FETCH_BYTES, downloadFailureMessage, existingDownload, isLocalFetchCall, mergeFetchTool, resolveDownloadTarget, writeDownloadedFile, } from "./lib/fetchFile.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
 // the direct commands (claim/tidy/done) can never diverge. The proxy carries its
@@ -42,6 +43,74 @@ const UNBOUND_MESSAGE = `This folder (${UNBOUND ?? process.cwd()}) is not bound
 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
+// RTSC-962 — the worktree census. The server cannot read git and never will; this
+// process can, and a `rtsc-NN/<slug>` worktree is an agent saying in the filesystem
+// "I am working on RTSC-NN". Reporting it lets the queue SEE work somebody started
+// without claiming, which is the one transition Retasc had no gate for.
+//
+// Throttled: `git worktree list` is milliseconds, but a `git status` per tree is not,
+// on a large repo — and this is triggered by the agent's tool calls, which can arrive
+// several a second.
+const WORKTREE_SCAN_MS = Number(process.env.RETASC_WORKTREE_SCAN_MS) || 30_000;
+let lastWorktreeScan = 0;
+// Issue → branch for the holds the server last confirmed, so the notice can name the
+// branch. Rebuilt from each scan: a hold that has been claimed (or has lapsed) drops
+// off the server's list and must stop being announced.
+let activeHolds = new Map();
+// Holds already announced to the agent. ONCE PER HOLD, not once per call.
+//
+// The temptation is to repeat the line until the agent acts, and it is the wrong
+// instinct — it is the exact failure the server-side riders are written against
+// (RTSC-463: "a paragraph repeated on every claim becomes wallpaper"). A hold stands for
+// an hour, during which an agent can easily make a hundred tool calls; a line on every
+// one of them does not get more obeyed, it gets skipped, and it teaches the agent to
+// skip the NEXT one too. Saying it once is what keeps it readable — and the case that
+// actually matters, a reader about to act on the issue, is caught again server-side by
+// the `get_issue` rider, which has the full context to say something useful.
+//
+// Cleared when a hold goes away, so a genuinely new sighting of the same issue later
+// speaks up again.
+const announcedHolds = new Set();
+// One scan at a time. The throttle alone is not enough: a scan that outruns the window
+// (a slow disk, a huge repo) would otherwise overlap with the next one and multiply the
+// git processes it was meant to bound.
+let scanning = false;
+/**
+ * One git command, ASYNC, returning stdout — or null if git failed or could not be run.
+ *
+ * Deliberately not `spawnSync`, which the rest of this file uses for its one-shot
+ * startup probe. This runs every 30 seconds for the life of the session, and the proxy
+ * is a stdio relay: a synchronous child blocks the event loop, so every message in
+ * flight — the agent's own tool calls included — waits for git. Never rejects; a census
+ * that cannot read the disk says nothing rather than failing anything.
+ */
+function git(args, cwd) {
+    return new Promise((resolveOut) => {
+        let out = "";
+        let settled = false;
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveOut(v);
+        };
+        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+        // A git that hangs (a credential prompt, a network remote, a stuck lock) must not
+        // wedge the census — same reasoning as REAP_TIMEOUT_MS, shorter because these are
+        // local, read-only commands that should take milliseconds.
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            done(null);
+        }, 5_000);
+        timer.unref?.();
+        child.stdout?.on("data", (d) => {
+            out += String(d);
+        });
+        child.on("error", () => done(null));
+        child.on("close", (code) => done(code === 0 ? out : null));
+    });
+}
 // RTSC-646: the credential-death warning fires ONCE with its full explanation. A
 // revoked/rotated key fails every heartbeat of every lease, so repeating the whole
 // paragraph on each tick (every 10 min, per lease) would bury the first one.
@@ -716,6 +785,24 @@ async function handleLine(line) {
             log(`warning: ${warning}`);
         applyObservation(leases, obs);
         appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
+        // RTSC-962 — attach what the LAST scan found, then start the next one WITHOUT
+        // awaiting it.
+        //
+        // The order matters and it is the same rule RTSC-181 states for the reap: git must
+        // never delay the response the agent is blocked on. Awaiting the scan would put two
+        // `git` invocations per worktree AND a full network round-trip on the critical path
+        // of one tool call in every thirty seconds — hundreds of milliseconds on a large
+        // repo, paid by the agent, forever. So the notice is attached from the previous
+        // scan's result and the fresh scan runs in the background.
+        //
+        // The cost of that is one call of latency on FIRST detection — a few seconds — and
+        // it buys a proxy that is never in the way. A hold lasts an hour; being told about
+        // it one call later changes nothing.
+        //
+        // `scanWorktrees` is started after `applyObservation` so a claim made by this very
+        // call is already in `leases` and its own worktree is not reported as unclaimed.
+        appendUnclaimedNotice(resp);
+        void scanWorktrees().catch((e) => log(`worktree scan: ${String(e?.message ?? e)}`));
     }
     // Relay the response (requests have an id; notifications don't).
     if (resp != null && msg.id !== undefined) {
@@ -726,6 +813,109 @@ async function handleLine(line) {
     if (reapId)
         reapClosedIssue(reapId);
 }
+/**
+ * RTSC-962 — look for unclaimed `rtsc-NN/<slug>` worktrees on this machine and report
+ * them, so the server can record a provisional hold.
+ *
+ * Every decision here is in `lib/worktreeReport.ts` and unit-tested; this function is
+ * only the git I/O and the network call. It is a NO-OP outside a git repo, and it never
+ * throws: a census that fails must not fail — or even alter — the agent's tool call.
+ *
+ * Report-only. It never claims (client-side lease bookkeeping would lock the real worker
+ * out of `checkpoint`/`done`), never blocks, and never rewrites the request.
+ */
+async function scanWorktrees() {
+    if (!MAIN_CHECKOUT)
+        return; // not in a git repo — nothing local to see
+    if (scanning)
+        return; // a scan is already in flight — never pile them up
+    const now = Date.now();
+    if (now - lastWorktreeScan < WORKTREE_SCAN_MS)
+        return;
+    lastWorktreeScan = now;
+    scanning = true;
+    try {
+        await runScan(now);
+    }
+    finally {
+        scanning = false;
+    }
+}
+async function runScan(now) {
+    const list = await git(["worktree", "list", "--porcelain"], MAIN_CHECKOUT);
+    if (list === null)
+        return;
+    const trees = candidateTrees(list);
+    if (trees.length === 0) {
+        activeHolds = new Map();
+        return;
+    }
+    // One `status` + one `log` per candidate. Bounded by the number of agent worktrees on
+    // the machine (a handful), and only for branches that already match the convention —
+    // never a walk of the repo.
+    const state = new Map();
+    for (const t of trees) {
+        const st = await git(["status", "--porcelain"], t.path);
+        if (st === null)
+            continue; // the tree is gone or unreadable — say nothing
+        const log = await git(["log", "-1", "--format=%ct"], t.path);
+        const secs = log === null ? NaN : Number(log.trim());
+        state.set(t.path, {
+            dirty: st.trim().length > 0,
+            ...(Number.isFinite(secs) && secs > 0 ? { lastCommitAt: secs * 1000 } : {}),
+        });
+    }
+    const worktrees = buildReport({ trees, state, held: leases.keys(), now });
+    if (worktrees.length === 0) {
+        activeHolds = new Map();
+        return;
+    }
+    try {
+        const result = toolResult(await postRemote(reportRequest(hbSeq--, worktrees)), "report_worktrees");
+        const holds = holdsFrom(result);
+        // Rebuilt from THIS scan, never merged into the last one: an issue that dropped off
+        // the server's list was claimed, closed, or lapsed, and must stop being announced.
+        const byIssue = new Map(worktrees.map((w) => [w.identifier, w.branch]));
+        activeHolds = new Map(holds.map((id) => [id, byIssue.get(id) ?? id]));
+    }
+    catch (e) {
+        // An older deployment has no such tool, and a network blip is a network blip.
+        // Either way the agent's call is unaffected — that is the whole contract.
+        log(`report_worktrees: ${String(e?.message ?? e)}`);
+    }
+}
+/**
+ * RTSC-962 — attach the ⚑ line to the response the agent is about to read, in its OWN
+ * content block.
+ *
+ * Same mechanics and the same reason as `appendFallbackNotice`: content[0].text must
+ * stay machine-parseable JSON (RTSC-142), and anything unexpected about the shape leaves
+ * the response untouched — a malformed notice must never break the protocol stream it
+ * rides on. Silent on an error response: an agent reading a refusal has a more urgent
+ * problem than an unclaimed worktree.
+ */
+function appendUnclaimedNotice(resp) {
+    // Prunes holds that have gone AND returns only the ones not yet announced. Run
+    // unconditionally (not behind an `activeHolds.size` guard) so the pruning happens even
+    // when the last scan came back empty — otherwise a hold that lapsed and was later seen
+    // again would stay marked as announced and never be mentioned a second time.
+    const fresh = holdsToAnnounce(activeHolds, announcedHolds, leases.keys());
+    if (fresh.length === 0)
+        return;
+    const result = resp?.result;
+    if (result?.isError)
+        return;
+    if (!Array.isArray(result?.content))
+        return;
+    const text = unclaimedNotice(fresh, activeHolds);
+    if (!text)
+        return;
+    result.content.push({ type: "text", text });
+    // Marked only once the line is actually ON the response — an early return above must
+    // not burn the one announcement this hold gets.
+    for (const id of fresh)
+        announcedHolds.add(id);
+}
 async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.49.1",
+  "version": "1.51.0",
   "description": "Retasc CLI — 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": {