@retasc/cli 1.2.4 → 1.3.0

package/dist/api.js

@@ -1,6 +1,7 @@
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { loadConfig } from "./config.js";
+import { refreshSession, deviceLogin } from "./auth.js";
 // Typed-ish references to the public management functions in convex/manage.ts.
 // The CLI is a standalone package, so we reference functions by name rather than
 // importing the parent's generated api.
@@ -26,18 +27,65 @@ function client() {
         c.setAuth(cfg.token);
     return c;
 }
+// Does this error mean "the access token is missing/expired", i.e. a refresh
+// might fix it? The access-token JWT lives ~1h, so any long-lived login trips
+// this. Two shapes surface: our server functions throw `UNAUTHENTICATED …`
+// (requireUser), and the Convex platform rejects a stale JWT with "Could not
+// verify OIDC token"/"Unauthenticated". Match either, case-insensitively.
+export function isAuthError(e) {
+    const msg = String(e?.message ?? e);
+    return /unauthenticated|could not verify oidc|oidc token/i.test(msg);
+}
+/**
+ * Run an authed management call, transparently recovering from an expired
+ * access token. The two-token design (short access JWT + long refresh token) is
+ * the point: the CLI silently rides the refresh token across the hourly access
+ * boundary instead of forcing `retasc login` every hour (RTSC-165).
+ *
+ * On an auth error we try ONE recovery, then retry the call ONCE:
+ *   1. If there is no stored token at all, the user was never signed in — this
+ *      isn't an expiry, so rethrow the clean "sign in first" error rather than
+ *      launching a surprise device flow under a misleading "session expired".
+ *   2. `refreshSession()` — swap the refresh token for a fresh access token.
+ *   3. If that fails (refresh token expired/invalid), fall back to a full
+ *      `deviceLogin()` — but only when stdout is a TTY, since the device flow
+ *      prints a code to stdout for a human to authorize; in a captured/piped
+ *      context we surface a clear "run `retasc login`" error instead of hanging
+ *      or spilling the prompt into someone's `$(retasc …)` capture.
+ * A second auth failure after recovery is real (rethrown) — we never loop.
+ */
+async function withAuth(call) {
+    try {
+        return await call();
+    }
+    catch (e) {
+        if (!isAuthError(e))
+            throw e;
+        // No session to recover — never signed in. Surface the original error.
+        if (!loadConfig().token)
+            throw e;
+        if (await refreshSession())
+            return await call();
+        if (!process.stdout.isTTY) {
+            throw new Error("Session expired and could not refresh. Run `retasc login`.");
+        }
+        console.error("Session expired — re-authenticating with GitHub…");
+        await deviceLogin();
+        return await call();
+    }
+}
 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),
-    listKeys: (args) => client().query(fns.listKeys, args),
-    mintKey: (args) => client().action(fns.mintKey, args),
-    rotateKey: (args) => client().action(fns.rotateKey, args),
-    revokeKey: (args) => client().mutation(fns.revokeKey, args),
-    createInvite: (args) => client().action(fns.createInvite, args),
-    acceptInvite: (args) => client().mutation(fns.acceptInvite, args),
-    listInvites: (args) => client().query(fns.listInvites, args),
-    revokeInvite: (args) => client().mutation(fns.revokeInvite, args),
+    me: () => withAuth(() => client().query(fns.me, {})),
+    listProjects: (args) => withAuth(() => client().query(fns.listProjects, args)),
+    createOrg: (args) => withAuth(() => client().mutation(fns.createOrg, args)),
+    createProject: (args) => withAuth(() => client().mutation(fns.createProject, args)),
+    renameProjectPrefix: (args) => withAuth(() => client().mutation(fns.renameProjectPrefix, args)),
+    listKeys: (args) => withAuth(() => client().query(fns.listKeys, 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)),
+    createInvite: (args) => withAuth(() => client().action(fns.createInvite, args)),
+    acceptInvite: (args) => withAuth(() => client().mutation(fns.acceptInvite, args)),
+    listInvites: (args) => withAuth(() => client().query(fns.listInvites, args)),
+    revokeInvite: (args) => withAuth(() => client().mutation(fns.revokeInvite, args)),
 };

package/dist/auth.js

@@ -76,3 +76,39 @@ export async function deviceLogin() {
     }
     patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
 }
+/**
+ * Silently mint a fresh access token from the stored refresh token and persist
+ * the rotated pair to ~/.retasc/config.json.
+ *
+ * Convex Auth access tokens (the JWT in `token`) live only ~1h; the refresh
+ * token is long-lived (session default ~30d) and exists precisely to swap for a
+ * new access token without re-running the device flow. Calling `auth:signIn`
+ * with `{ refreshToken }` (no provider/params) is Convex Auth's refresh grant —
+ * it returns `{ tokens: { token, refreshToken } }` with BOTH rotated (refresh
+ * tokens are single-use; the old one is invalidated), so we must write the new
+ * pair back immediately and never reuse the old refresh token.
+ *
+ * Returns true on success (config now holds a fresh session), false if there is
+ * no refresh token or the grant is rejected (expired/invalid/reused) — the
+ * caller then falls back to a full `deviceLogin()`. Never throws and never
+ * prints token values.
+ */
+export async function refreshSession() {
+    const cfg = loadConfig();
+    if (!cfg.refreshToken)
+        return false;
+    try {
+        const convex = new ConvexHttpClient(cfg.deploymentUrl);
+        const res = await convex.action(signIn, { refreshToken: cfg.refreshToken });
+        const tokens = res?.tokens;
+        if (!tokens?.token)
+            return false;
+        patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
+        return true;
+    }
+    catch {
+        // Expired/invalid/reused refresh token, or a transient backend error. Treat
+        // as "cannot refresh" — the caller re-authenticates via the device flow.
+        return false;
+    }
+}

package/dist/index.js

@@ -434,7 +434,11 @@ program
     .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));
+    .option("--only <RTSC-NN>", "Scope the sweep to a single issue's branch (used by the MCP auto-reap)")
+    .action((opts) => 
+// Normalize --only to the canonical uppercase id so it matches the branch ids
+// scan() derives (rtsc-181/… → RTSC-181), same as `done` does for --id.
+tidyAction({ ...opts, only: opts.only ? String(opts.only).toUpperCase() : undefined }).catch(fail));
 program
     .command("done")
     .description("Mark the current issue (rtsc-NN/ branch, or --id) done and tear down its worktree+branch.")

package/dist/lib/watchdog.js

@@ -38,15 +38,59 @@ export function applyObservation(leases, o) {
     }
     // Releases / terminal status drop the lease — the issue is named in the REQUEST.
     const id = typeof o.args?.identifier === "string" ? o.args.identifier : undefined;
-    if (id) {
-        if (o.toolName === "release_issue")
-            leases.delete(id);
-        if (o.toolName === "save_issue") {
-            const status = o.args?.status;
-            if (status === "done" || status === "canceled")
-                leases.delete(id);
-        }
-    }
+    if (id && o.toolName === "release_issue")
+        leases.delete(id);
+    const closeId = terminalCloseId(o);
+    if (closeId)
+        leases.delete(closeId);
+}
+/**
+ * The issue id to reap if this observation is a terminal close (done|canceled) via
+ * `save_issue`, else undefined. This is the SAME rule applyObservation uses to drop
+ * the lease — factored out so "which calls end an issue" lives in one place and the
+ * proxy's auto-reap (RTSC-181) can't drift from the lease bookkeeping. The caller
+ * decides whether it actually held the lease and whether the call succeeded
+ * (`isToolError`) before acting — this only classifies the request shape.
+ */
+export function terminalCloseId(o) {
+    if (o.toolName !== "save_issue")
+        return undefined;
+    const id = typeof o.args?.identifier === "string" ? o.args.identifier : undefined;
+    if (!id)
+        return undefined;
+    const status = o.args?.status;
+    return status === "done" || status === "canceled" ? id : undefined;
+}
+/**
+ * Did a tools/call result come back as an MCP error envelope (`{ isError: true }`)?
+ * Used to gate side effects — the proxy must never reap a branch off a `save_issue`
+ * that actually FAILED server-side. Distinct from isClaimLost (which matches a
+ * specific error string); this is the generic "did the tool error at all" check.
+ */
+export function isToolError(result) {
+    return (!!result && typeof result === "object" && result.isError === true);
+}
+/**
+ * The full RTSC-181 reap gate as ONE pure decision: given an observed tool call and
+ * the leases this session holds, return the issue id to reap — or undefined. Reap ONLY
+ * when ALL hold:
+ *   1. it's a terminal close (save_issue done|canceled),
+ *   2. of an issue THIS session actually claimed (in `leases` — never someone else's),
+ *   3. and the call genuinely succeeded — a truthy payload that is not an error
+ *      envelope. A transport-level failure yields an undefined result (no envelope to
+ *      catch); requiring a truthy payload means we never reap off a failed close.
+ * This is the security-critical check — keeping it pure makes every branch testable
+ * (the proxy just spawns on a non-undefined return).
+ */
+export function shouldReapOnClose(o, leases) {
+    const id = terminalCloseId(o);
+    if (!id)
+        return undefined;
+    if (!leases.has(id))
+        return undefined;
+    if (!o.result || isToolError(o.result))
+        return undefined;
+    return id;
 }
 /** A JSON-RPC `heartbeat` tool call for one lease (the proxy's timer sends these). */
 export function heartbeatRequest(rpcId, issueId, claimToken) {

package/dist/proxy.js

@@ -7,7 +7,10 @@
 // no watchdog. Self-enforcing: no proxy → no Retasc tools → can't orphan a lease.
 import { createInterface } from "node:readline";
 import { hostname } from "node:os";
-import { applyObservation, heartbeatRequest, isClaimLost, } from "./lib/watchdog.js";
+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 { resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
 import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
@@ -30,6 +33,87 @@ let sessionKeyFallback = false;
 function log(msg) {
     process.stderr.write(`[retasc-watchdog] ${msg}\n`);
 }
+// RTSC-181: closing an issue over MCP (save_issue status:done) marks it done on the
+// control plane but the server never touches git — so the branch/worktree orphans.
+// The proxy is the local hands: when it sees a session's own claim close terminally,
+// it reaps that issue's branch out-of-band via the CLI's existing `tidy --prune`,
+// which reuses every safety guard (skips dirty/unmerged/current-branch). Resolved
+// once at startup; null if we're not in a git repo (nothing to reap).
+const MAIN_CHECKOUT = resolveMainCheckout();
+// The compiled CLI entrypoint (dist/index.js) — resolved relative to this module so
+// it's correct however the proxy was launched (not process.argv, which a wrapper
+// could rewrite). Reaps re-invoke it as `retasc tidy`.
+const CLI_ENTRY = fileURLToPath(new URL("./index.js", import.meta.url));
+// Issues whose reap child is in flight — so a duplicate/retried close doesn't spawn
+// two concurrent teardowns racing on the same branch.
+const reaping = new Set();
+// Reaps are SERIALIZED through this chain: concurrent `tidy` children mutating the
+// same main checkout contend on `.git` locks (index.lock, ref locks) — a wave-close
+// (next_batch → N × save_issue done) would otherwise fire N parallel worktree/branch
+// deletes and hit "cannot lock ref" errors + partial teardown. One at a time avoids it.
+let reapChain = Promise.resolve();
+const REAP_TIMEOUT_MS = 60_000; // a stuck git (e.g. a credential prompt) must not wedge the queue
+/** The main checkout root (worktree/branch ops always target it), or null if not in
+ *  a git repo. `--git-common-dir` resolves to the MAIN `.git` even from a worktree. */
+function resolveMainCheckout() {
+    const r = spawnSync("git", ["rev-parse", "--git-common-dir"], { encoding: "utf8" });
+    if (r.status !== 0)
+        return null;
+    const commonDir = (r.stdout ?? "").trim();
+    return commonDir ? dirname(resolve(commonDir)) : null;
+}
+/**
+ * Reap a terminally-closed issue's branch/worktree, out-of-band (RTSC-181). Enqueues
+ * a `retasc tidy --prune --only <id>` run (serialized — see `reapChain`) as a SEPARATE
+ * process rooted at the main checkout so (a) blocking git never stalls the proxy's
+ * stdio loop, and (b) cwd is the main checkout, not the agent's worktree — so `tidy`'s
+ * "you're inside its worktree" guard doesn't skip the very tree we mean to remove.
+ * `tidy` still enforces every safety check: an unmerged (or dirty) branch is left as an
+ * orphan, never force-deleted — so only a clean, merged worktree is ever removed.
+ */
+function reapClosedIssue(issueId) {
+    if (!MAIN_CHECKOUT)
+        return; // not in a git repo — nothing local to reap
+    if (reaping.has(issueId))
+        return; // a teardown for this issue is already queued/running
+    reaping.add(issueId);
+    // Chain after any in-flight reap so git ops on the shared checkout never overlap.
+    reapChain = reapChain.then(() => runReap(issueId));
+}
+/** Run one `tidy --prune --only` child to completion (resolve on exit/error/timeout).
+ *  Never rejects — a failed reap is best-effort cleanup, logged, never fatal. */
+function runReap(issueId) {
+    return new Promise((resolve) => {
+        log(`${issueId} closed → reaping its branch/worktree…`);
+        const child = spawn(process.execPath, [CLI_ENTRY, "tidy", "--prune", "--only", issueId], {
+            cwd: MAIN_CHECKOUT,
+            env: process.env,
+            // stdout is ignored (tidy reports on stderr); stderr inherits so its reap log
+            // lands in the same MCP stderr stream as the rest of the watchdog's output.
+            stdio: ["ignore", "ignore", "inherit"],
+        });
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reaping.delete(issueId);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            log(`reap of ${issueId} timed out — killing it`);
+            child.kill("SIGKILL"); // 'exit' still fires → finish() runs
+        }, REAP_TIMEOUT_MS);
+        timer.unref?.();
+        child.on("error", (e) => {
+            log(`reap of ${issueId} couldn't start: ${String(e?.message ?? e)}`);
+            finish();
+        });
+        child.on("exit", finish);
+        child.unref?.(); // a pending reap must not keep the proxy alive
+    });
+}
 async function postRemote(body) {
     const res = await fetch(MCP_URL, {
         method: "POST",
@@ -120,18 +204,25 @@ async function handleLine(line) {
     // Watch tools/call traffic for claims/releases (request args + result), and
     // flag the workspace-key fallback on whoami so the AGENT sees the degraded
     // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.
+    let reapId;
     if (msg.method === "tools/call" && resp) {
-        applyObservation(leases, {
-            toolName: msg.params?.name,
-            args: msg.params?.arguments,
-            result: toolResult(resp, msg.params?.name),
-        });
+        const result = toolResult(resp, msg.params?.name);
+        const obs = { toolName: msg.params?.name, args: msg.params?.arguments, result };
+        // Decide the reap BEFORE applyObservation drops the lease (the gate checks lease
+        // ownership). Pure decision — see shouldReapOnClose. We act on it AFTER relaying
+        // the response, below (RTSC-181).
+        reapId = shouldReapOnClose(obs, leases);
+        applyObservation(leases, obs);
         appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
     }
     // Relay the response (requests have an id; notifications don't).
     if (resp != null && msg.id !== undefined) {
         process.stdout.write(JSON.stringify(resp) + "\n");
     }
+    // Reap only after the tool result is on the wire — spawns its own process, so git
+    // never delays the response the agent is blocked on (RTSC-181).
+    if (reapId)
+        reapClosedIssue(reapId);
 }
 async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.2.4",
+  "version": "1.3.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": {
@@ -46,7 +46,7 @@
     "convex": "^1.41.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.1.0",
     "typescript": "^5.6.0"
   }
 }