@cruxy/cli 1.2.1 → 1.3.0

package/dist/approval/classify.js

@@ -4,6 +4,10 @@ import path from "node:path";
  * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
  * (most-restrictive) so a future/unknown action can never slip through as
  * read-only or low-risk.
+ *
+ * The same pass sets `irreversible` — the separate, stricter axis that bounds
+ * auto-approve. See {@link ApprovalRequest.irreversible} for why the tier cannot
+ * do that job, and the `── reversibility` section below for the rules.
  */
 export function classify(action, cwd) {
     const root = path.resolve(cwd);
@@ -32,9 +36,182 @@ export function classify(action, cwd) {
                 summary: `perform an unrecognized action (${describeKind(action)})`,
                 targets: [],
                 cwd: root,
+                irreversible: "this action kind is unrecognized, so nothing can bound what it changes",
             };
     }
 }
+// ── reversibility (P5 track 3) ────────────────────────────────────────────────
+/**
+ * What the checkpoint actually captures, because every rule below is derived
+ * from it rather than from intuition about which verbs sound scary:
+ *
+ *   • `capture.ts` enumerates with `git ls-files --cached --others
+ *     --exclude-standard` — tracked + untracked-non-ignored files **under one
+ *     root**. So: nothing outside a declared root, and nothing gitignored
+ *     (`node_modules/`, build output, `.env`).
+ *   • `git-store.ts` states it outright: "no ref is ever created or moved, and
+ *     HEAD / the index / the stash are never written." `.git/` is never
+ *     enumerated at all. So: **no git history, refs, branches, or stash.**
+ *   • Nothing off-disk. A checkpoint cannot un-send a push, un-publish a
+ *     package, or un-call an HTTP endpoint.
+ *
+ * Everything a checkpoint DOES cover, it covers completely: `withCheckpointGate`
+ * snapshots the whole root before the first mutation of a run, so arbitrary
+ * in-root file damage — including `rm -rf` of the workspace — is restorable.
+ * That is why the rules key on *escape* (out of the root, into `.git`, onto the
+ * network) rather than on how destructive an in-root command looks.
+ *
+ * ── Residual risk, stated plainly ──
+ * No static analysis can prove a shell command's effects. {@link ESCAPES_ROOT}
+ * is a denylist, and denylists lose: `node deploy.js` or an unlisted CLI can
+ * still reach the network. It is a belt. The braces are the two rules that fail
+ * *closed* — an unprovable command (any shell metacharacter) and any argument
+ * resolving outside the root are both irreversible without consulting any list
+ * — plus the pre-command checkpoint, which bounds the on-disk half absolutely.
+ * Auto-approve is a deliberate, per-session, visibly-announced choice; this is
+ * the ceiling on that choice, not a sandbox.
+ */
+/**
+ * `git` subcommands that only read. Everything else `git` does is irreversible
+ * by construction — it writes refs, HEAD, the index, or the stash, none of which
+ * the checkpoint captures. An allowlist, not a denylist, so `push --force`,
+ * `reset --hard`, `rebase`, `filter-branch`, `branch -D`, `tag -d`, and every
+ * future ref-mutating subcommand are caught without being enumerated.
+ */
+const GIT_READ_ONLY = new Set([
+    "blame",
+    "cat-file",
+    "describe",
+    "diff",
+    "for-each-ref",
+    "grep",
+    "log",
+    "ls-files",
+    "rev-list",
+    "rev-parse",
+    "shortlog",
+    "show",
+    "status",
+]);
+/**
+ * Package-manager subcommands whose effects stay in the checkpointed tree.
+ * `run`/`test` execute project scripts — arbitrary code, but code whose on-disk
+ * damage the pre-command checkpoint restores. `install` is NOT here: it writes
+ * `node_modules/`, which is gitignored and therefore never captured, and reaches
+ * a registry. `publish`, `link`, `login`, `config` escape outright.
+ */
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+const PACKAGE_MANAGER_LOCAL = new Set(["run", "test"]);
+/**
+ * Programs whose primary purpose is to reach something the checkpoint cannot
+ * restore — the network, another host, a registry, cloud state, or the machine
+ * itself. Not exhaustive by construction (see the residual-risk note above);
+ * these are the ones an agent loop actually reaches for.
+ */
+const ESCAPES_ROOT = new Map([
+    ["curl", "it sends network requests, which no checkpoint can recall"],
+    ["wget", "it sends network requests, which no checkpoint can recall"],
+    ["ssh", "it runs commands on another host, outside any checkpoint"],
+    ["scp", "it copies to another host, outside any checkpoint"],
+    ["sftp", "it transfers to another host, outside any checkpoint"],
+    ["rsync", "it can write outside the workspace and to other hosts"],
+    ["gh", "it acts on GitHub under your identity; remote state is not captured"],
+    [
+        "glab",
+        "it acts on GitLab under your identity; remote state is not captured",
+    ],
+    ["docker", "it changes container and image state outside the workspace"],
+    ["kubectl", "it changes live cluster state, which is not captured"],
+    ["helm", "it changes live cluster state, which is not captured"],
+    ["terraform", "it changes real infrastructure, which is not captured"],
+    ["ansible", "it changes remote hosts, which are not captured"],
+    ["aws", "it changes cloud account state, which is not captured"],
+    ["gcloud", "it changes cloud account state, which is not captured"],
+    ["az", "it changes cloud account state, which is not captured"],
+    ["sudo", "it runs with elevated privileges, outside every guarantee here"],
+    ["doas", "it runs with elevated privileges, outside every guarantee here"],
+    ["su", "it runs as another user, outside every guarantee here"],
+    ["systemctl", "it changes system service state, which is not captured"],
+    ["launchctl", "it changes system service state, which is not captured"],
+    ["shutdown", "it halts the machine"],
+    ["reboot", "it restarts the machine"],
+    ["dd", "it writes raw devices, which no checkpoint can restore"],
+    ["mkfs", "it formats a filesystem, which no checkpoint can restore"],
+    ["diskutil", "it changes disk state, which no checkpoint can restore"],
+]);
+/**
+ * Why the checkpoint cannot restore `command`, or `null` when it can.
+ *
+ * Three gates, in order of how hard they fail closed. The first two need no
+ * list to be correct; the third is the belt described above.
+ */
+function shellIrreversibility(command, root) {
+    const tokens = commandTokens(command);
+    if (tokens === null) {
+        // Deny-by-default, and the same proof `commandTokens` already gates session
+        // grants on: with a pipe, redirect, substitution, glob, or `~`, we cannot
+        // say what runs, so we cannot say what it touches.
+        return "the command uses shell features we cannot analyze, so its effects cannot be bounded";
+    }
+    const program = path.basename(tokens[0]);
+    const args = tokens.slice(1);
+    // The first argument that is not an option — the subcommand, for the
+    // multiplexers below.
+    const subcommand = args.find((a) => !a.startsWith("-"));
+    if (program === "git" && !(subcommand && GIT_READ_ONLY.has(subcommand))) {
+        return "git writes refs, HEAD, the index, or the stash — none of which the checkpoint captures";
+    }
+    if (PACKAGE_MANAGERS.has(program) &&
+        !(subcommand && PACKAGE_MANAGER_LOCAL.has(subcommand))) {
+        return `\`${program}${subcommand ? ` ${subcommand}` : ""}\` reaches a registry or gitignored install state, which the checkpoint does not capture`;
+    }
+    const escapes = ESCAPES_ROOT.get(program);
+    if (escapes)
+        return `\`${program}\` is not checkpointable — ${escapes}`;
+    const outside = args.find((a) => escapesRoot(a, root));
+    if (outside) {
+        return `\`${outside}\` resolves outside the workspace root, which the checkpoint does not capture`;
+    }
+    return null;
+}
+/**
+ * Whether a command argument names a path the checkpoint would not cover.
+ *
+ * Handles `--flag=<path>` as well as a bare path, because the flag form is how
+ * an out-of-root target most often sneaks past a naive check. Absolute paths and
+ * anything containing `..` are resolved against the root and tested; a plain
+ * relative token cannot escape, so it is left alone. (`~` and `*` never reach
+ * here — {@link commandTokens} already rejects the whole command for those.)
+ */
+function escapesRoot(arg, root) {
+    const eq = arg.indexOf("=");
+    const candidate = eq === -1 ? arg : arg.slice(eq + 1);
+    if (candidate === "")
+        return false;
+    const looksLikePath = candidate.startsWith("/") || candidate.split("/").includes("..");
+    if (!looksLikePath)
+        return false;
+    return !isInside(root, path.resolve(root, candidate));
+}
+/**
+ * Why the checkpoint cannot restore a file action, or `null` when it can.
+ *
+ * A delete is not special here — `patchHasDelete` raises the *tier* because a
+ * delete deserves a louder prompt, but a deleted file inside the root is
+ * restored from the snapshot exactly like an edited one. What matters is
+ * containment, and that every target is known: an action carrying no resolved
+ * target cannot be shown to be covered, so it is not.
+ */
+function fileIrreversibility(targets, root) {
+    if (targets.length === 0) {
+        return "the action names no resolvable target, so the checkpoint cannot be shown to cover it";
+    }
+    const outside = targets.find((t) => !isInside(root, t));
+    if (outside) {
+        return `\`${outside}\` is outside the workspace root, which the checkpoint does not capture`;
+    }
+    return null;
+}
 // ── shell ─────────────────────────────────────────────────────────────────────
 // Any shell control/expansion character means we cannot prove the command is a
 // single simple invocation. Covers && || ; | ` $ ( ) { } * ? ~ ! # ' " \ < > and
@@ -71,6 +248,7 @@ function shellRequest(action, root) {
         summary: `run: ${command}`,
         targets: [],
         cwd: root,
+        irreversible: shellIrreversibility(command, root),
     };
 }
 // ── test (run the project's test suite, C.13) ──────────────────────────────────
@@ -92,6 +270,16 @@ function testRequest(action, root) {
         summary: `run tests: ${command}`,
         targets: [],
         cwd: root,
+        // A test command comes from the project's own package.json and runs after
+        // the pre-command checkpoint, so its on-disk effects are restorable — this
+        // is the one destructive-tier action auto-approve is meant to cover, and
+        // what keeps `full-auto` able to verify the code it just wrote. It is still
+        // held to the SAME shell rules: a test script that force-pushes or curls is
+        // no more restorable for being called "test". An empty command names
+        // nothing to reason about.
+        irreversible: command === ""
+            ? "the test action names no command, so its effects cannot be bounded"
+            : shellIrreversibility(command, root),
     };
 }
 // ── vcs (open pull request) ─────────────────────────────────────────────────────
@@ -110,6 +298,7 @@ function vcsRequest(action, root) {
         summary: `open PR: ${title}`,
         targets: [],
         cwd: root,
+        irreversible: "opening a PR commits and pushes under your identity; the checkpoint captures working-tree files, never commits, refs, or anything already on the remote",
     };
 }
 // ── rollback (restore checkpoint) ──────────────────────────────────────────────
@@ -137,6 +326,7 @@ function rollbackRequest(action, root) {
                 `(${fileCount} file${fileCount === 1 ? "" : "s"})`,
             targets: [],
             cwd: root,
+            irreversible: ROLLBACK_IRREVERSIBLE,
         };
     }
     const preview = action.preview?.type === "rollback" ? action.preview : undefined;
@@ -152,8 +342,17 @@ function rollbackRequest(action, root) {
             ? preview.files.map((f) => path.resolve(root, f.path))
             : [],
         cwd: root,
+        irreversible: ROLLBACK_IRREVERSIBLE,
     };
 }
+/**
+ * A rollback is the one action the checkpoint system cannot protect you from:
+ * `withCheckpointGate` takes no snapshot for `kind: "rollback"`, so restoring a
+ * checkpoint discards whatever the tree currently holds with nothing to undo it
+ * with. It is never auto-approved — the mode whose safety net IS the checkpoint
+ * must not be able to silently spend it.
+ */
+const ROLLBACK_IRREVERSIBLE = "a rollback overwrites the working tree and is not itself checkpointed, so the current state would be unrecoverable";
 // ── mcp (call an external MCP server's tool, C.27) ──────────────────────────────
 /**
  * An MCP tool call. Always `destructive` — the tool is arbitrary code in a
@@ -176,6 +375,10 @@ function mcpRequest(action, root) {
         summary: `call MCP tool ${tool || "(unknown)"} on server ${server || "(unknown)"}`,
         targets: [],
         cwd: root,
+        // Same reasoning as the tier: the server cannot vouch for itself. A
+        // `readOnlyHint` is a claim by the thing being gated, and the checkpoint
+        // cannot reach whatever it did anyway.
+        irreversible: "an MCP tool runs unsandboxed in an external server, so its effects are outside the checkpoint entirely",
     };
 }
 // ── file (write / edit / patch) ────────────────────────────────────────────────
@@ -188,6 +391,7 @@ function fileRequest(action, tier, root) {
         summary: fileSummary(action, targets, root),
         targets,
         cwd: root,
+        irreversible: fileIrreversibility(targets, root),
     };
 }
 /** Absolute target paths for a file action (write/edit: one; patch: many). */

package/dist/approval/policy.js

@@ -75,20 +75,58 @@ export function scopeCovers(scope, request) {
 export class InteractivePolicy {
     allowlist;
     io;
-    constructor(allowlist, io) {
+    autoApprove;
+    constructor(allowlist, io, 
+    /**
+     * Whether the session is in an auto-approving mode (P5 track 3).
+     *
+     * A THUNK, not a boolean: the mode is runtime state the user can change at
+     * any point, including between two actions of the same turn. Reading it
+     * once at construction would let a session that has been switched back to
+     * `manual` keep auto-approving for the rest of its life — a stale copy of
+     * exactly the fact this must never be wrong about.
+     *
+     * Omitted → never auto-approves, which is every non-interactive caller.
+     */
+    autoApprove = () => false) {
         this.allowlist = allowlist;
         this.io = io;
+        this.autoApprove = autoApprove;
     }
     async decide(request) {
+        // A grant the allowlist answers shows the user nothing (P3) — left
+        // unflagged so a caller can render the change instead.
         if (this.allowlist.allows(request))
             return { allow: true };
+        // Auto-approve: allowed without a prompt, and deliberately NOT flagged as
+        // `prompted` — so `previewSilentApprovals` renders the diff. An unattended
+        // mode that showed nothing would let a session's whole body of work land
+        // invisibly, which is a different failure from the one it is meant to save
+        // the user: skipping the QUESTION is the point, skipping the RECORD is not.
+        //
+        // THE CEILING (P5 track 3). Auto-approve suppresses the prompt for
+        // reversible actions ONLY. An action the run's checkpoint cannot restore —
+        // a delete outside the workspace, a force-push, a history rewrite, an MCP
+        // call, a rollback, anything unprovable — falls through to the prompt even
+        // here, and even unattended.
+        //
+        // This is the line the product position rests on. "Only change what was
+        // asked, no silent deletions" is not a claim a mode may switch off:
+        // suppressing prompts is a convenience, and suppressing the last gate before
+        // irreversible damage is a different thing wearing the same word. Note the
+        // gate is `request.irreversible`, NOT `request.tier` — the tier is an
+        // unprovability signal (every shell command is `destructive`, `ls`
+        // included), so gating on it would make the mode either useless or
+        // dishonest. See `ApprovalRequest.irreversible`.
+        if (this.autoApprove() && !request.irreversible)
+            return { allow: true };
         const choice = await promptForApproval(request, this.io);
         switch (choice.kind) {
             case "once":
-                return { allow: true };
+                return { allow: true, prompted: true };
             case "session":
                 this.allowlist.grant(request);
-                return { allow: true };
+                return { allow: true, prompted: true };
             case "reject":
                 return choice.reason
                     ? {

package/dist/approval/prompt.js

@@ -10,29 +10,39 @@ import { themeForColor } from "../theme/index.js";
  * is a reject.
  */
 export async function promptForApproval(request, io) {
-    io.write(render(request, io.color, io.columns ?? resolveColumns()));
-    const key = (await io.readKey()).toLowerCase();
-    io.write("\n");
-    switch (key) {
-        case "y":
-            return { kind: "once" };
-        case "a":
-            return { kind: "session" };
-        case "n": {
-            io.write("  reason (optional, sent to the agent): ");
-            const reason = (await io.readLine()).trim();
-            return reason ? { kind: "reject", reason } : { kind: "reject" };
-        }
-        case "t": {
-            io.write("  what should the agent do instead? ");
-            const instruction = (await io.readLine()).trim();
-            return instruction
-                ? { kind: "instruct", instruction }
-                : { kind: "reject" };
+    // The terminal is about to belong to this prompt: yield the live region
+    // BEFORE the question lands, or it would be painted into a region the next
+    // repaint erases (U.2/U.4). `finally` gives it back on every path, including
+    // the default-deny ones.
+    io.beginPrompt?.();
+    try {
+        io.write(render(request, io.color, io.columns ?? resolveColumns()));
+        const key = (await io.readKey()).toLowerCase();
+        io.write("\n");
+        switch (key) {
+            case "y":
+                return { kind: "once" };
+            case "a":
+                return { kind: "session" };
+            case "n": {
+                io.write("  reason (optional, sent to the agent): ");
+                const reason = (await io.readLine()).trim();
+                return reason ? { kind: "reject", reason } : { kind: "reject" };
+            }
+            case "t": {
+                io.write("  what should the agent do instead? ");
+                const instruction = (await io.readLine()).trim();
+                return instruction
+                    ? { kind: "instruct", instruction }
+                    : { kind: "reject" };
+            }
+            default:
+                // n/a key, empty, EOF, Ctrl-C → default-deny.
+                return { kind: "reject" };
         }
-        default:
-            // n/a key, empty, EOF, Ctrl-C → default-deny.
-            return { kind: "reject" };
+    }
+    finally {
+        io.endPrompt?.();
     }
 }
 /** Render the full prompt block: header, detail (diff or command+cwd), choices. */
@@ -48,10 +58,27 @@ export function render(request, color, columns = resolveColumns()) {
     const label = tierLabel(request.tier, t);
     const lines = [];
     lines.push(...header(request.summary, mark, label, t, columns));
+    lines.push(...whyAsking(request.irreversible, t, columns));
     lines.push(detail(request, t, columns));
     lines.push(choices(request.scope, t));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
+/**
+ * The one-clause reason the checkpoint cannot restore this action, when there is
+ * one. Rendered for every mode, not just the auto ones — the prompt has no way
+ * to know the session's mode, and a user in `manual` benefits from the same
+ * sentence.
+ *
+ * It earns its line in auto-approve, where an unexplained prompt is actively
+ * misleading: the user asked not to be asked, so the only useful thing to say is
+ * why this one is different. Reflowed, never truncated — a half-sentence about
+ * irreversibility is worse than none.
+ */
+function whyAsking(irreversible, t, width) {
+    if (!irreversible)
+        return [];
+    return reflow(`no undo: ${irreversible}`, Math.max(1, width - 2)).map((l) => t.muted(`  ${l}`));
+}
 /**
  * The header, width-aware (U.12). Wide: the one inline line `! cruxy wants to
  * <summary> (destructive)`. Narrow: the risk (mark + tier label) stands on its

package/dist/checkpoint/gate.js

@@ -81,6 +81,18 @@ export class CheckpointGate {
         });
         await writeSet(this.primaryRoot, this.set);
     }
+    /**
+     * The current run's id, or undefined before the first {@link beginRun}.
+     *
+     * This is the ONE per-turn id in the CLI, and the session log (P2) borrows it
+     * rather than minting a second: `cruxy rollback <id>` reverts a turn's
+     * mutations and the session log records that turn's messages, so if the two
+     * used different ids the undo unit would mean two different things depending
+     * on which surface you asked. Exposed read-only — only `beginRun` sets it.
+     */
+    currentRunId() {
+        return this.runId ?? undefined;
+    }
     /** Root names that got a per-root service this process (inspection/tests). */
     get touchedRoots() {
         return [...this.services.keys()];