@retasc/cli 1.36.0 → 1.37.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.37.0 (2026-08-26)
+
+- **RTSC-749** — `retasc triage` reads and approves work filed from outside your org. Work
+  that arrives through a GitHub or GitLab connector is written by whoever can file on that
+  repo, and since RTSC-746 no agent can pick it up until a person has read it and approved
+  it. This is that decision from the terminal: `retasc triage` lists what is waiting,
+  `retasc triage RTSC-42` prints the full body and then asks.
+  It is deliberately hard to automate, because the CLI runs where coding agents run: there
+  is no `--approve` flag, the command refuses to run without an interactive terminal, and
+  confirming means retyping the issue id rather than pressing y. Saying no is as cheap as
+  saying yes (type `reject`) — the safe answer must never be the expensive one. The Dash
+  stays the recommended surface: an agent that can drive a real PTY on your machine could
+  drive this command too, and only logging the CLI out takes that away.
+
+## 1.36.1 (2026-08-25)
+
+- **RTSC-645** — `retasc gate install` no longer throws away your edits. It rewrites the
+  commit-msg hook and the Action on every run, so a gate you had customized (say, one that
+  also checks the branch number) used to vanish behind a green "✓ Updated" with nothing
+  saying so. Generated files now carry a hash of their own contents, so a later run can tell
+  "still exactly what we wrote" from "someone changed this". A changed file is copied to
+  `.bak` first, keeping its permissions, and the run tells you where the copy went; a second
+  round of edits goes to `.bak.2` rather than overwriting the first. Untouched files are
+  replaced silently as before, including when you re-key the gate to a different prefix, so
+  the common path gained no prompts and no flags.
+
 ## 1.36.0 (2026-08-25)
 
 - **RTSC-520** — the CLI now says when it is out of date. There was no version check

package/dist/api.js

@@ -44,6 +44,14 @@ const fns = {
     // imported from X before?" once the progress row is gone.
     latestImport: makeFunctionReference("import:latestImport"),
     importHistory: makeFunctionReference("import:importHistory"),
+    // RTSC-749 — the triage door. These are the ONLY CLI calls that must never be
+    // reachable with an agent key: they are `convex/triage.ts`, which authenticates through
+    // Convex Auth and rejects API keys outright (RTSC-746). The CLI reaches them over the
+    // human's device-flow SESSION, like billing and invites — never over the workspace MCP
+    // key the issue commands use.
+    listQuarantined: makeFunctionReference("triage:listQuarantined"),
+    approveExternal: makeFunctionReference("triage:approveExternal"),
+    rejectExternal: makeFunctionReference("triage:rejectExternal"),
     claimableGhosts: makeFunctionReference("ghosts:claimableGhosts"),
     claimGhost: makeFunctionReference("ghosts:claimGhost"),
     dismissGhostPrompt: makeFunctionReference("ghosts:dismissGhostPrompt"),
@@ -217,6 +225,10 @@ export const api = {
     listImportTargets: (args) => withAuth(() => client().action(fns.listImportTargets, args)),
     listImportStatuses: (args) => withAuth(() => client().action(fns.listImportStatuses, args)),
     listReviewCandidates: (args) => withAuth(() => client().query(fns.listReviewCandidates, args)),
+    // RTSC-749 — see `fns` above for why these ride the user session, not the MCP key.
+    listQuarantined: (args) => withAuth(() => client().query(fns.listQuarantined, args)),
+    approveExternal: (args) => withAuth(() => client().mutation(fns.approveExternal, args)),
+    rejectExternal: (args) => withAuth(() => client().mutation(fns.rejectExternal, args)),
     runImport: (args) => withAuth(() => client().action(fns.runImport, args)),
     latestImport: (args) => withAuth(() => client().query(fns.latestImport, args)),
     importHistory: (args) => withAuth(() => client().query(fns.importHistory, args)),

package/dist/commands/gate.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, writeFileSync, existsSync, chmodSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, copyFileSync, statSync, existsSync, chmodSync, } from "node:fs";
+import { join, dirname, relative } from "node:path";
 import { resolveMcpConn, readMcpJson, workspacePrefix } from "../lib/claim.js";
 import { claudeLocalRetascEntry } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
@@ -163,6 +164,135 @@ function writeFile(path, body, mode) {
         }
     }
 }
+// RTSC-645: never discard someone's edits silently. Both files are rewritten on
+// every run, so a hand-customized gate (e.g. one that also matches the branch
+// number) used to vanish behind a green "✓ Updated". We stamp what we generate
+// with a hash of its own body, so a later run can tell "still exactly what we
+// wrote" from "someone changed this" without keeping any state outside the file.
+//
+// Hashing the body against its OWN stamp — rather than re-rendering the current
+// template and diffing — is what keeps this stable across CLI versions: changing
+// template text would otherwise make every pristine file on every machine look
+// edited and warn on upgrade.
+const STAMP_PREFIX = "# retasc-gate: sha256=";
+const STAMP_RE = /^# retasc-gate: sha256=([0-9a-f]{64})$/;
+/** Compare and hash on normalized text: a CRLF checkout (Git for Windows'
+ *  autocrlf default) or a stray BOM must not make our own untouched file look
+ *  edited on every single run. */
+function normalizeText(s) {
+    return s.replace(/^/, "").replace(/\r\n/g, "\n");
+}
+function bodyHash(body) {
+    return createHash("sha256").update(normalizeText(body), "utf8").digest("hex");
+}
+/** Append the stamp as the final line — after the shebang and after any YAML, so
+ *  placement never depends on the file's syntax. Both layers take `#` comments. */
+export function withStamp(body) {
+    return `${body}${STAMP_PREFIX}${bodyHash(body)}\n`;
+}
+/** Split a stamped file back into (body, recorded hash), or null when the last
+ *  line isn't one of our stamps. */
+function splitStamp(raw) {
+    const trimmed = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    const cut = trimmed.lastIndexOf("\n");
+    const last = cut === -1 ? trimmed : trimmed.slice(cut + 1);
+    const m = last.match(STAMP_RE);
+    if (!m)
+        return null;
+    return { body: cut === -1 ? "" : trimmed.slice(0, cut + 1), hash: m[1] };
+}
+/** Classify what's on disk. Anything we can't positively prove we generated —
+ *  no stamp, a broken stamp, an unreadable file — counts as `modified`, because
+ *  the cost of a needless backup is a stray file and the cost of the wrong call
+ *  is someone's work. */
+export function classifyGateFile(path) {
+    if (!existsSync(path))
+        return "absent";
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return "modified";
+    }
+    // Normalize BEFORE splitting: on a CRLF checkout the stamp line ends in \r and
+    // would never match, so our own untouched file would look edited on every run
+    // and pile up a fresh .bak each time.
+    const s = splitStamp(normalizeText(raw));
+    if (!s)
+        return "modified";
+    return s.hash === bodyHash(s.body) ? "pristine" : "modified";
+}
+/** Pick where this backup goes. `<path>.bak` when it's free, or already holds
+ *  exactly these bytes (a repeated run of the same edit shouldn't pile up
+ *  copies); otherwise the first free `<path>.bak.2`, `.bak.3`, ... Overwriting a
+ *  backup that holds DIFFERENT bytes would lose the only copy of an earlier
+ *  edit — someone who edits, installs, edits again and installs again — which is
+ *  the exact data loss this change exists to stop. */
+function nextBackupPath(path) {
+    const first = `${path}.bak`;
+    if (!existsSync(first))
+        return first;
+    // Unreadable source (it classified as `modified` precisely because we couldn't
+    // read it): we can't compare, so take a fresh slot rather than crash or clobber.
+    let current = null;
+    try {
+        current = readFileSync(path);
+    }
+    catch {
+        current = null;
+    }
+    try {
+        if (current && readFileSync(first).equals(current))
+            return first;
+    }
+    catch {
+        /* unreadable backup: fall through and take a fresh slot rather than clobber it */
+    }
+    for (let n = 2; n < 100; n++) {
+        const candidate = `${path}.bak.${n}`;
+        if (!existsSync(candidate))
+            return candidate;
+        try {
+            if (current && readFileSync(candidate).equals(current))
+                return candidate;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    throw new Error(`refusing to overwrite an existing backup: ${first} through ${path}.bak.99 are all taken — clear the ones you don't need and re-run`);
+}
+/** Copy to the slot `nextBackupPath` picked, preserving the mode so a restored
+ *  hook is still executable (a `mv` of a 0644 backup would silently stop
+ *  running). */
+function backupFile(path) {
+    const bak = nextBackupPath(path);
+    copyFileSync(path, bak);
+    try {
+        chmodSync(bak, statSync(path).mode & 0o777);
+    }
+    catch {
+        /* best effort (e.g. Windows) */
+    }
+    return bak;
+}
+/**
+ * Write one gate layer, backing up first when the file on disk isn't ours.
+ * Returns the line to print, so both layers report identically.
+ */
+function writeLayer(root, path, body, mode) {
+    const state = classifyGateFile(path);
+    const rel = relative(root, path);
+    const lines = [];
+    if (state === "modified") {
+        const bak = backupFile(path);
+        lines.push(`⚠ ${rel} had local edits — saved to ${relative(root, bak)} before replacing it.`);
+    }
+    writeFile(path, withStamp(body), mode);
+    lines.push(`✓ ${state === "absent" ? "Wrote" : "Updated"} ${rel}`);
+    return lines;
+}
 /**
  * Install the commit↔issue gate into the current repo, parameterized by `prefix`.
  * Writes the requested layers (hook and/or Action) and enables the hook path.
@@ -179,13 +309,14 @@ export function installGate(opts) {
     if (!hook && !action) {
         throw new Error("nothing to install — drop --no-hook/--no-action or pick at least one layer");
     }
+    let backedUp = false;
     if (hook) {
         const hookPath = join(root, ".githooks", "commit-msg");
-        const existed = existsSync(hookPath);
-        writeFile(hookPath, hookTemplate(opts.prefix), 0o755);
-        const enabled = setHooksPath(root);
-        console.log(`✓ ${existed ? "Updated" : "Wrote"} commit-msg hook (.githooks/commit-msg).`);
-        if (enabled) {
+        backedUp = classifyGateFile(hookPath) === "modified" || backedUp;
+        for (const line of writeLayer(root, hookPath, hookTemplate(opts.prefix), 0o755)) {
+            console.log(line);
+        }
+        if (setHooksPath(root)) {
             console.log("  Enabled: git config core.hooksPath .githooks");
         }
         else {
@@ -194,9 +325,10 @@ export function installGate(opts) {
     }
     if (action) {
         const actionPath = join(root, ".github", "workflows", "check-commit-message.yml");
-        const existed = existsSync(actionPath);
-        writeFile(actionPath, actionTemplate(opts.prefix));
-        console.log(`✓ ${existed ? "Updated" : "Wrote"} GitHub Action (.github/workflows/check-commit-message.yml).`);
+        backedUp = classifyGateFile(actionPath) === "modified" || backedUp;
+        for (const line of writeLayer(root, actionPath, actionTemplate(opts.prefix))) {
+            console.log(line);
+        }
     }
     console.log("");
     console.log(`Gate is keyed to prefix "${opts.prefix}" — commits/PRs need ${opts.prefix}-NN or [no-issue].`);
@@ -206,5 +338,8 @@ export function installGate(opts) {
     if (hook) {
         console.log("The hook is local fast-feedback only: opt-in per clone (git won't auto-install it) and bypassable with --no-verify.");
     }
+    if (backedUp) {
+        console.log("\nA file you had customized was replaced by the standard one. Diff the .bak against it before committing, and re-apply anything you want to keep.");
+    }
     console.log("\nCommit the written files so the gate ships with the repo.");
 }

package/dist/commands/triage.js

@@ -0,0 +1,171 @@
+import { createInterface } from "node:readline/promises";
+import { api } from "../api.js";
+// ---------------------------------------------------------------------------
+// RTSC-749 — `retasc triage`. Epic RTSC-751.
+//
+// The second human signing surface for the quarantine gate (RTSC-746): external intake is
+// undispatchable until a member reads it and signs it, and plenty of people live in a
+// terminal rather than in the Dash.
+//
+// THE HARD PART, and why this file is careful. The Dash is a browser a human is sitting
+// in. The CLI is a binary on a machine where a CODING AGENT CAN SHELL OUT. If approval
+// were scriptable, an agent that just read a hostile body could approve the next one, and
+// the gate it is standing in front of would protect nothing.
+//
+// The server-side invariant does most of the work: `convex/triage.ts` authenticates
+// through Convex Auth and rejects agent API keys outright, so an agent holding only a
+// workspace MCP key cannot sign, full stop. What remains is an agent shelling out on a
+// machine where a human is already logged into the CLI. These are the client-side
+// defences against that, and they RAISE THE BAR rather than close the hole:
+//
+//   • Refuse a non-interactive stdin/stdout. A harnessed `exec` has no PTY.
+//   • No approve flag. There is no `--approve`, no `--yes`, no `--force` — so there is no
+//     one-liner to smuggle into a command, and no "just add --yes" for anyone to suggest.
+//   • Render the body, then require the identifier RETYPED. Not a y/N: a typed value an
+//     agent would have to have read the screen to produce.
+//   • Echo the content hash of the body just printed, so the server refuses if the text
+//     moved under the reader.
+//
+// RESIDUAL RISK, stated rather than hidden: an agent puppeting a real PTY on a machine
+// with a logged-in CLI defeats the TTY check, and the server cannot tell that apart from
+// a human. The mitigation is revocation (`retasc logout`), and the Dash remains the
+// recommended surface. This is said in the command's own help text too — a defence
+// somebody believes is stronger than it is has already done its damage.
+// ---------------------------------------------------------------------------
+/**
+ * Is a real person at this terminal?
+ *
+ * BOTH streams, deliberately. `stdin` alone is the usual check and it is not enough here:
+ * a harness that pipes output while leaving stdin attached would still be driving a
+ * command whose entire safety story is "a human is reading the screen".
+ */
+function interactive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** The SHA-256 the server binds a signature to. Must match `externalContentHash` in
+ *  convex/lib/quarantine.ts EXACTLY, including the length prefixes — a drift here means
+ *  every terminal approval fails with CONTENT_CHANGED on text nobody edited. */
+async function contentHash(title, body) {
+    const canonical = `${title.length}:${title}${body.length}:${body}`;
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Resolve the org the same way `retasc billing` does: explicit, or the only one. */
+async function resolveOrg(orgId) {
+    const me = await api.me();
+    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 org = me.orgs.find((o) => o.id === orgId);
+    return { orgId: orgId, label: org ? `${org.name}${org.slug ? ` (${org.slug})` : ""}` : String(orgId) };
+}
+/** `retasc triage` — what is waiting. A LIST ONLY: nothing here approves. */
+export async function triageListAction(opts) {
+    const { orgId, label } = await resolveOrg(opts.orgId);
+    const res = await api.listQuarantined({ orgId });
+    const items = res.items ?? [];
+    if (opts.json) {
+        console.log(JSON.stringify({ orgId, items, hasMore: res.hasMore }, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log(`Nothing waiting in ${label}.`);
+        return;
+    }
+    console.log(`${items.length} ${items.length === 1 ? "issue" : "issues"} filed from outside ${label}, ` +
+        `waiting for you to read and approve ${items.length === 1 ? "it" : "them"}:\n`);
+    for (const i of items) {
+        const who = i.externalAuthor ?? "an unidentified account";
+        console.log(`  ${i.identifier}  ${i.title}`);
+        console.log(`    by ${who}${i.sourceUrl ? ` · ${i.sourceUrl}` : ""}`);
+    }
+    if (res.hasMore)
+        console.log(`\n  …and more. Clear some and run this again.`);
+    // The list deliberately does NOT print bodies. Reading happens one at a time, next to
+    // the decision — a wall of concatenated external text is exactly the thing people skim.
+    console.log(`\nRead one in full, then approve or reject:  retasc triage <ISSUE-ID>`);
+}
+/**
+ * `retasc triage RTSC-42` — render the full body, then ask.
+ *
+ * The whole command is the reading. Everything before the prompt exists to make sure the
+ * person answering it has actually seen the text they are vouching for.
+ */
+export async function triageOneAction(identifier, opts) {
+    // FIRST, before any network call: refuse to run where nobody can read the screen. Doing
+    // this first means the refusal is about the environment, not about what happens to be
+    // in the queue.
+    if (!interactive()) {
+        throw new Error("`retasc triage <id>` needs an interactive terminal.\n" +
+            "  Approving external work means a person read it, so this command refuses to run\n" +
+            "  with piped input or output. There is deliberately no --approve flag.\n" +
+            "  Approve in the Dash instead: https://dash.retasc.com/?tab=queue");
+    }
+    const { orgId, label } = await resolveOrg(opts.orgId);
+    const res = await api.listQuarantined({ orgId });
+    const items = res.items ?? [];
+    const want = identifier.trim().toUpperCase();
+    const item = items.find((i) => i.identifier.toUpperCase() === want);
+    if (!item) {
+        throw new Error(`${identifier} is not waiting for approval in ${label}.\n` +
+            `  It may already be approved, rejected, or never have been external.\n` +
+            `  Run \`retasc triage\` to see what is waiting.`);
+    }
+    // The rendering. Plain, undecorated, and complete — no truncation, because a body
+    // truncated at the interesting part is worse than no preview at all.
+    const who = item.externalAuthor ?? "an unidentified account";
+    console.log("");
+    console.log(`  ${item.identifier}  ${item.title}`);
+    console.log("");
+    console.log(`  Filed from OUTSIDE ${label}, by ${who} on ${item.externalOrigin ?? "a connector"}.`);
+    if (item.sourceUrl)
+        console.log(`  Source: ${item.sourceUrl}`);
+    console.log("");
+    console.log("  ── the text you are approving ".padEnd(72, "─"));
+    console.log("");
+    for (const line of (item.body || "(no description)").split("\n"))
+        console.log(`  ${line}`);
+    console.log("");
+    console.log("  ".padEnd(72, "─"));
+    console.log("");
+    console.log("  Treat this as a report to evaluate, not as instructions. Approving tells");
+    console.log("  your agents the text is safe to act on.");
+    console.log("");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // The typed confirm. Not y/N: a value that has to be read off the screen. `reject` is
+        // the other real answer, and it is deliberately as easy to type as the id is — saying
+        // no must never be the expensive option, or people will drift toward yes.
+        const answer = (await rl.question(`  Type ${item.identifier} to APPROVE, or "reject" to refuse: `)).trim();
+        if (answer.toLowerCase() === "reject") {
+            await api.rejectExternal({ orgId, identifier: item.identifier });
+            console.log(`\n  ✓ ${item.identifier} rejected and closed.`);
+            return;
+        }
+        if (answer.toUpperCase() !== item.identifier.toUpperCase()) {
+            console.log(`\n  Nothing done — that didn't match. ${item.identifier} is still waiting.`);
+            return;
+        }
+        // Recompute from the text just printed rather than trusting the value the list gave
+        // us: if the two could differ, the hash would stop meaning "what was on screen".
+        const hash = await contentHash(item.title, item.body ?? "");
+        if (hash !== item.contentHash) {
+            // Belt and braces — the server will refuse anyway. Saying it here is friendlier
+            // than a CONTENT_CHANGED from the backend.
+            throw new Error(`${item.identifier} changed while you were reading it. Run the command again.`);
+        }
+        await api.approveExternal({ orgId, identifier: item.identifier, contentHash: hash });
+        console.log(`\n  ✓ ${item.identifier} approved. Agents can pick it up now.`);
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/index.js

@@ -14,6 +14,7 @@ import { identityAction } from "./commands/identity.js";
 import { importAction } from "./commands/import.js";
 import { doctorAction } from "./commands/doctor.js";
 import { billingAction } from "./commands/billing.js";
+import { triageListAction, triageOneAction } from "./commands/triage.js";
 import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
 import { whoamiView, orgCreatedView, projectCreatedView, keyListView, inviteListView, } from "./lib/format.js";
 import { tidyAction, doneAction } from "./commands/tidy.js";
@@ -253,6 +254,27 @@ program
     requireLogin();
     await billingAction({ orgId: opts.orgId, json: opts.json }).catch(fail);
 });
+// RTSC-749 — the terminal half of the quarantine gate (RTSC-746). Sits beside `billing`
+// rather than under `issue`: the `issue` commands go over the workspace MCP key, and this
+// one must go over the HUMAN's session — an agent key cannot sign, by design.
+program
+    .command("triage")
+    .argument("[issue]", "The issue to read and decide on. Omit to list what is waiting.")
+    .description("Read and approve work filed from OUTSIDE your org. Agents can't pick these up until " +
+    "a person approves them, and a person means you: this needs an interactive terminal " +
+    "and there is deliberately no --approve flag. The Dash is the recommended surface " +
+    "(an agent that can drive a real PTY on this machine could drive this command too).")
+    .option("--org-id <id>", "Which org (defaults to your only one).")
+    .option("--json", "List as raw JSON. Listing only — deciding is never scriptable.")
+    .action(async (issue, opts) => {
+    requireLogin();
+    if (issue === undefined) {
+        await triageListAction({ orgId: opts.orgId, json: opts.json }).catch(fail);
+    }
+    else {
+        await triageOneAction(issue, { orgId: opts.orgId }).catch(fail);
+    }
+});
 // --- org / project ---------------------------------------------------------
 const org = program.command("org").description("Manage orgs.");
 org

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.36.0",
+  "version": "1.37.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": {