@retasc/cli 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.22.0 (2026-08-12)
+
+- **RTSC-646** — the watchdog now says when it is **not** renewing a lease. Its lease set is
+  in-memory and built only from claim traffic this proxy saw, so a claim made in another
+  terminal, over direct HTTP MCP, or by a previous proxy before a harness restart was renewed
+  by nobody — silently, until the reclaimer took the issue away mid-build. Touching such a
+  lease now prints a warning naming the issue and what to do about it (`release_issue` is
+  exempt: it ends a lease rather than needing one). A heartbeat rejected as `UNAUTHORIZED` is
+  also called out loudly, once: that means the session's **credential** died, not the lease,
+  so every claim stops renewing at the same moment and each lapses at its own expiry. The
+  proxy keeps tracking and keeps trying, because re-minting the key inside the TTL recovers
+  all of them. The `mcp install --watchdog` text no longer stops at "no per-claim
+  heartbeats" — it names both bounds: the proxy must be running, and it only renews claims
+  it saw this session make.
+
+## 1.21.1 (2026-08-10)
+
+- **RTSC-643** — `retasc gate install` keys the gate to **this folder's** project, not the
+  machine-wide default. It used to read `defaultProjectPrefix` (stamped by whichever project
+  you last ran `retasc init` for), so in a bound folder it could install a commit gate keyed
+  to a different project — rejecting every valid commit — while reporting success. It now asks
+  the folder's own binding first (`whoami` over the workspace key, or the keystore's cached
+  prefix offline; a subdirectory run checks the git toplevel too), prints where the prefix
+  came from, warns when the global default disagrees, and only uses the global default when
+  the folder is genuinely unbound. Bound-but-unresolvable fails loudly instead of guessing.
+
 ## 1.21.0 (2026-08-07)
 
 - **RTSC-527** — the re-import warning dates the last import in **your** timezone. The day

package/dist/commands/gate.js

@@ -1,6 +1,81 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { resolveMcpConn, readMcpJson, workspacePrefix } from "../lib/claim.js";
+import { claudeLocalRetascEntry } from "../lib/binding.js";
+import { getBinding } from "../lib/keystore.js";
+/** The keystore's stored prefix for the workspace marker at `dir`, if any —
+ *  the offline fallback when the server can't be asked. Entry selection matches
+ *  resolveConn: env workspace id first, then claude-local, then the folder
+ *  marker. The cache answers ONLY for the key the live path would have asked
+ *  (`b.key === conn.key`) — an env-selected key from a different org must not
+ *  inherit this folder's cached prefix. */
+function storedPrefix(dir, conn, env = process.env) {
+    const entry = claudeLocalRetascEntry(dir) ?? readMcpJson(dir)?.mcpServers?.retasc;
+    const wsId = env.RETASC_WORKSPACE || entry?.env?.RETASC_WORKSPACE;
+    const b = wsId ? getBinding(String(wsId)) : undefined;
+    if (!b || b.key !== conn.key)
+        return undefined;
+    return typeof b.prefix === "string" && b.prefix ? b.prefix : undefined;
+}
+/** Server/keystore-derived text is validated BEFORE it's printed or trusted
+ *  (same rule as whoami's control-char strip) — a malformed value is treated
+ *  as unresolved, never echoed to the terminal. */
+function validPrefix(p) {
+    if (typeof p !== "string")
+        return undefined;
+    const up = p.toUpperCase();
+    return PREFIX_RE.test(up) ? up : undefined;
+}
+/** whoami must never hang gate install — same 10s bound as resolveBinding
+ *  (binding.ts), which bare global fetch does not carry. */
+const fetchWithTimeout = (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(10_000) });
+/**
+ * Resolve the prefix the gate is keyed to, folder-first (RTSC-643). The global
+ * `defaultProjectPrefix` is written only by `retasc init` — it's "whatever
+ * project you last init-ed", which in a bound folder can be a DIFFERENT
+ * workspace's prefix. So the folder's own binding is authoritative (whoami over
+ * the workspace's key, or the keystore's cached prefix offline), and the global
+ * default is consulted only when the folder is unbound. A bound folder whose
+ * prefix can't be resolved fails loudly rather than guessing: a gate keyed to
+ * the wrong project rejects every valid commit and ships to CI.
+ */
+export async function resolveGatePrefix(opts) {
+    // `!== undefined` so `--prefix ""` (an unset shell var) still reaches
+    // installGate's validator and fails loudly instead of silently resolving.
+    if (opts.flag !== undefined)
+        return { prefix: opts.flag.toUpperCase(), source: "--prefix" };
+    const cfgDefault = opts.defaultPrefix?.toUpperCase();
+    // The gate is written at the git toplevel, so when the cwd (a subdirectory)
+    // carries no binding, look at the toplevel too — otherwise a subdir run would
+    // silently fall back to the global default behind a false "isn't bound".
+    const dirs = opts.dir
+        ? [opts.dir]
+        : Array.from(new Set([process.cwd(), repoRoot()].filter((d) => !!d)));
+    let conn;
+    let boundDir = dirs[0];
+    for (const d of dirs) {
+        const c = resolveMcpConn({ env: opts.env, mcpJson: readMcpJson(d), dir: d });
+        if (c.key) {
+            conn = c;
+            boundDir = d;
+            break;
+        }
+    }
+    if (conn) {
+        const live = validPrefix(await workspacePrefix(conn, opts.fetchImpl ?? fetchWithTimeout));
+        const prefix = live ?? validPrefix(storedPrefix(boundDir, conn, opts.env));
+        if (prefix) {
+            const source = live ? "workspace binding" : "workspace binding (cached)";
+            const shadowed = cfgDefault && cfgDefault !== prefix ? cfgDefault : undefined;
+            return shadowed ? { prefix, source, shadowedDefault: shadowed } : { prefix, source };
+        }
+        throw new Error("this folder is bound, but its project prefix couldn't be resolved (server didn't answer, no cached prefix) — pass --prefix <PREFIX>.");
+    }
+    if (cfgDefault)
+        return { prefix: cfgDefault, source: "global config" };
+    throw new Error("no project prefix — pass --prefix <PREFIX>, or bind this folder (`retasc bind`) / run `retasc init` so it's resolved from your project.");
+}
 // Mirror the server's project-prefix rule (convex/manage.ts PREFIX_RE): 2–10
 // chars, A–Z/0–9, letter-first. The prefix is interpolated into a generated
 // bash hook and a YAML grep, so validating here keeps a stray value from

package/dist/commands/mcp.js

@@ -186,7 +186,12 @@ export function installMcp(opts) {
         }
         console.log("\nWatchdog MCP config (Codex / OpenCode / any stdio MCP client):\n");
         console.log(mcpProxyConfigBlock(opts.url, opts.key, resolved.launcher));
-        console.log("\nThe watchdog keeps your claims alive automatically — no per-claim heartbeats. If it ever isn't running you just fall back to the normal lease timeout (safe).");
+        // RTSC-646: the old text stopped at "no per-claim heartbeats", which reads as
+        // "a claim never lapses while I'm working". It renews the claims THIS proxy saw
+        // you make, for as long as it is running — so name both bounds here, or the
+        // first surprise is the reclaimer taking an issue mid-build.
+        console.log("\nThe watchdog keeps claims alive automatically — it renews every claim it saw this session make, about every 10 minutes, so your agent needs no per-claim heartbeats. Long builds and test runs do NOT free a claim by themselves.");
+        console.log("Two things it does not cover, both safe (they fall back to the normal 30-minute lease timeout): if the proxy stops, renewal stops; and a claim made elsewhere — another terminal, direct HTTP MCP, or a previous proxy before a restart — is renewed by nobody. Heartbeat or checkpoint those yourself.");
         return;
     }
     const res = tryClaudeCli(opts.url, opts.key, scope);

package/dist/index.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { VERSION } from "./version.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
-import { installGate } from "./commands/gate.js";
+import { installGate, resolveGatePrefix } from "./commands/gate.js";
 import { claimAction } from "./commands/claim.js";
 import { bindAction, setupFromToken } from "./commands/bind.js";
 import { joinAction } from "./commands/join.js";
@@ -491,16 +491,27 @@ const gate = program.command("gate").description("Wire the commit↔issue tracea
 gate
     .command("install")
     .description("Install a prefix-correct commit-msg hook + check-commit-message Action into this repo.")
-    .option("--prefix <PREFIX>", "Project prefix to enforce (default: your configured project)")
+    .option("--prefix <PREFIX>", "Project prefix to enforce (default: this folder's bound project)")
     .option("--no-hook", "Skip the local commit-msg hook (CI Action only)")
     .option("--no-action", "Skip the GitHub Action (local hook only)")
-    .action((opts) => {
+    .action(async (opts) => {
     try {
-        const prefix = (opts.prefix ?? loadConfig().defaultProjectPrefix)?.toUpperCase();
-        if (!prefix) {
-            return fail("no project prefix — pass --prefix <PREFIX>, or run `retasc init`/`login` so it's resolved from your project.");
+        // RTSC-643: folder-first — the binding is the authoritative identity; the
+        // global default (stamped by the last `retasc init`) applies only when the
+        // folder is unbound.
+        const r = await resolveGatePrefix({
+            flag: opts.prefix,
+            defaultPrefix: loadConfig().defaultProjectPrefix,
+        });
+        if (r.source !== "--prefix")
+            console.log(`Prefix ${r.prefix} — from ${r.source}.`);
+        if (r.source === "global config") {
+            console.log("  (This folder isn't bound — `retasc bind` makes the prefix folder-scoped.)");
+        }
+        if (r.shadowedDefault) {
+            console.log(`  ⚠ Ignoring global default prefix ${r.shadowedDefault} — this folder's binding wins.`);
         }
-        installGate({ prefix, layers: { hook: opts.hook, action: opts.action } });
+        installGate({ prefix: r.prefix, layers: { hook: opts.hook, action: opts.action } });
     }
     catch (e) {
         fail(e);

package/dist/lib/watchdog.js

@@ -111,32 +111,93 @@ export function heartbeatRequest(rpcId, issueId, claimToken) {
     };
 }
 /**
- * A heartbeat CLAIM_LOST means the lease is gone — stop tracking it.
+ * Does a tool result carry SERVER ERROR signal `code`? The shared matcher behind
+ * isClaimLost / isUnauthorized.
  *
- * The server throws `Error("CLAIM_LOST: …")` (convex/lib/claims.ts), and http.ts
- * surfaces that as an MCP tool ERROR: `{ isError: true, content:[{text:"CLAIM_LOST: …"}] }`.
- * Match ONLY that signal (or a top-level `error`/`code` field, for a future
- * structured shape) — NEVER `JSON.stringify` the whole result and regex it, or a
- * benign payload field that merely CONTAINS "CLAIM_LOST" (an issue title, a
- * checkpoint note quoting an error, a comment body) would silently drop a live
- * lease and let the reclaimer hand our work to someone else (RTSC-150).
+ * The server throws `Error("CLAIM_LOST: …")` / `Error("UNAUTHORIZED: …")`
+ * (convex/lib/claims.ts, convex/lib/auth.ts), and http.ts surfaces that as an MCP
+ * tool ERROR: `{ isError: true, content:[{text:"CLAIM_LOST: …"}] }`. Match ONLY that
+ * signal (or a top-level `error`/`code` field, for a future structured shape) —
+ * NEVER `JSON.stringify` the whole result and regex it, or a benign payload field
+ * that merely CONTAINS the code (an issue title, a checkpoint note quoting an error,
+ * a comment body) would silently drop a live lease and let the reclaimer hand our
+ * work to someone else (RTSC-150).
  */
-export function isClaimLost(result) {
+function hasErrorCode(result, code) {
     if (!result || typeof result !== "object")
         return false;
     const r = result;
+    // Substring match, NOT `new RegExp(code)`: the codes are fixed literals, so a
+    // regex buys nothing and turns any future caller-supplied code into a regex
+    // injection / ReDoS shape. `.includes` is the same match with none of that.
+    const carries = (s) => s.includes(code);
     // A structured error signal on a top-level field (belt-and-suspenders; also the
     // shape the older unit test asserts). Bounded to top-level scalars, not nested.
-    if (r.code === "CLAIM_LOST")
+    if (r.code === code)
         return true;
-    if (typeof r.error === "string" && /CLAIM_LOST/.test(r.error))
+    if (typeof r.error === "string" && carries(r.error))
         return true;
     // The live shape: only an MCP error envelope, and only its text blocks — success
-    // payloads (isError absent/false) are never treated as a lost claim.
+    // payloads (isError absent/false) are never treated as an error.
     if (r.isError !== true || !Array.isArray(r.content))
         return false;
     return r.content.some((c) => c !== null &&
         typeof c === "object" &&
         typeof c.text === "string" &&
-        /CLAIM_LOST/.test(c.text));
+        carries(c.text));
+}
+/** A heartbeat CLAIM_LOST means the lease is gone — stop tracking it. */
+export function isClaimLost(result) {
+    return hasErrorCode(result, "CLAIM_LOST");
+}
+/**
+ * A heartbeat UNAUTHORIZED means the CREDENTIAL died, not the lease (RTSC-646).
+ * `resolveAuth` throws it when the key was revoked or rotated, its parent key was
+ * revoked, or the member was suspended/retired — so EVERY lease in this session
+ * stops renewing at once and each one lapses at its own expiry.
+ *
+ * Deliberately NOT treated like CLAIM_LOST: the claims are still ours and still
+ * live server-side, so dropping them from the map would hide exactly the leases
+ * the human needs to hear about. We keep tracking, keep trying (a re-mint can fix
+ * it inside the TTL), and say so loudly.
+ */
+export function isUnauthorized(result) {
+    return hasErrorCode(result, "UNAUTHORIZED");
+}
+/**
+ * The renewal-visibility warning (RTSC-646): this session is touching a lease the
+ * watchdog is NOT renewing, so it runs on the bare 30-minute TTL.
+ *
+ * The lease map is in-memory and built ONLY from claim traffic this process saw, so
+ * a claim made in another terminal, over direct HTTP MCP, or by a previous proxy
+ * before a harness restart is renewed by nobody — and today that is silent until
+ * the reclaimer takes the issue away mid-work. Two observable tells, both meaning
+ * "we hold it, we aren't renewing it":
+ *   1. a request carrying a `claimToken` for an issue we don't track (the agent is
+ *      hand-heartbeating/checkpointing a lease we never saw claimed), and
+ *   2. a `check_claim` answering `youHold: true` for an issue we don't track.
+ * Returns the warning text, or undefined when there's nothing to say. Pure so the
+ * decision is testable without a proxy; the caller does the printing.
+ */
+export function untrackedLeaseWarning(o, leases) {
+    const id = typeof o.args?.identifier === "string" ? o.args.identifier : undefined;
+    if (!id || leases.has(id))
+        return undefined;
+    // `release_issue` also carries a claimToken, but it ENDS the lease. Warning
+    // "nothing is renewing it, heartbeat it yourself" about a claim the agent is
+    // deliberately handing back is advice for the opposite of what it just did.
+    if (o.toolName === "release_issue")
+        return undefined;
+    const holds = typeof o.args?.claimToken === "string" ||
+        (!!o.result &&
+            typeof o.result === "object" &&
+            o.result.youHold === true);
+    if (!holds)
+        return undefined;
+    return (`lease for ${id} is NOT tracked by this proxy — nothing is renewing it, so it ` +
+        `runs on the bare 30-minute TTL and the reclaimer will take it mid-work. ` +
+        `This happens when the claim was made in another terminal, over direct HTTP MCP, ` +
+        `or by a previous proxy before a restart. Heartbeat or checkpoint it yourself ` +
+        `(checkpoint is better — it renews AND leaves the handoff note), or release it ` +
+        `and re-claim through this session.`);
 }

package/dist/proxy.js

@@ -10,7 +10,7 @@ import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyObservation, heartbeatRequest, isClaimLost, shouldReapOnClose, } from "./lib/watchdog.js";
+import { applyObservation, heartbeatRequest, isClaimLost, isUnauthorized, shouldReapOnClose, untrackedLeaseWarning, } from "./lib/watchdog.js";
 import { resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
 import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
@@ -23,6 +23,10 @@ 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
+// 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.
+let authWarned = false;
 // Per-session key (RTSC-50): starts as the workspace key; on startup we mint a
 // session key and switch to it so this session is distinguishable from others.
 let activeKey = KEY;
@@ -212,6 +216,12 @@ async function handleLine(line) {
         // ownership). Pure decision — see shouldReapOnClose. We act on it AFTER relaying
         // the response, below (RTSC-181).
         reapId = shouldReapOnClose(obs, leases);
+        // RTSC-646: warn BEFORE applyObservation, while the map still reflects what we
+        // were renewing when the call was made — after it, a fresh claim would look
+        // tracked and a deliberate release would look untracked.
+        const warning = untrackedLeaseWarning(obs, leases);
+        if (warning)
+            log(`warning: ${warning}`);
         applyObservation(leases, obs);
         appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
     }
@@ -227,11 +237,35 @@ async function handleLine(line) {
 async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {
         try {
-            const resp = await postRemote(heartbeatRequest(hbSeq--, issueId, token));
-            if (isClaimLost(toolResult(resp, "heartbeat"))) {
+            const result = toolResult(await postRemote(heartbeatRequest(hbSeq--, issueId, token)), "heartbeat");
+            if (isClaimLost(result)) {
                 leases.delete(issueId);
                 log(`lease for ${issueId} is gone — stopped tracking`);
             }
+            else if (isUnauthorized(result)) {
+                // RTSC-646: the credential died, not the lease. Every claim in this session
+                // stops renewing at once and lapses at its own expiry, which reads exactly
+                // like "the watchdog is working" until the reclaimer takes the work away.
+                // Keep tracking and keep trying — re-minting the key inside the TTL recovers
+                // every lease — but say the cause out loud, once.
+                if (!authWarned) {
+                    authWarned = true;
+                    log(`warning: heartbeat for ${issueId} was rejected as UNAUTHORIZED — this session's key ` +
+                        `no longer authenticates (revoked or rotated key, revoked parent key, or a suspended/` +
+                        `retired member). NO lease in this session is being renewed now; each one lapses at ` +
+                        `its own expiry and the reclaimer hands the work to another agent. Restore the ` +
+                        `credential and restart this session, or finish and release your claims by hand.`);
+                }
+                else {
+                    log(`heartbeat for ${issueId} still UNAUTHORIZED — lease not renewed`);
+                }
+            }
+            else {
+                // A renewal that worked proves the credential works, so arm the full
+                // warning again: a key re-minted mid-session and then revoked a second
+                // time deserves the same loud explanation as the first time.
+                authWarned = false;
+            }
         }
         catch (e) {
             log(`heartbeat for ${issueId} failed: ${String(e?.message ?? e)}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@retasc/cli",
-  "version": "1.21.0",
-  "description": "Retasc CLI \u2014 the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
+  "version": "1.22.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": {
     "retasc": "dist/index.js"