@retasc/cli 1.50.0 → 1.51.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ 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

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.50.0",
+  "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": {