@cruxy/cli 1.2.0 → 1.3.0

package/dist/agent/session.js

@@ -1,39 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
-import { resolveTaskModel } from "../routing/index.js";
+import { resolveTaskModel, } from "../routing/index.js";
 import { UsageCollector, accumulateCacheTokens, } from "../usage/index.js";
 import { Budget } from "./budget.js";
+import { estimateTokens, findCut } from "./context.js";
 import { runAgent, } from "./loop.js";
+import { DEFAULT_MODE, modeAutoApproves, modePlans, nextMode, parseMode, } from "./mode.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
- * Estimate the token footprint of a message list with a cheap chars/4 heuristic
- * — no tokenizer dependency. Good enough to decide *when* to compact; exact
- * counts are deferred to a later phase. Counts only textual payload (block
- * structure and role labels are negligible and ignored).
+ * Re-exported from `agent/context.ts`, where the estimate now lives beside the
+ * cut-point search and the budget reading (P6 track 3) — one module for
+ * everything that measures the window, so the seam that acts on the numbers and
+ * the surfaces that explain them cannot drift.
  */
-export function estimateTokens(messages) {
-    let chars = 0;
-    for (const msg of messages) {
-        if (typeof msg.content === "string") {
-            chars += msg.content.length;
-            continue;
-        }
-        for (const block of msg.content) {
-            switch (block.type) {
-                case "text":
-                    chars += block.text.length;
-                    break;
-                case "tool_use":
-                    chars += block.name.length + JSON.stringify(block.input).length;
-                    break;
-                case "tool_result":
-                    chars += block.content.length;
-                    break;
-            }
-        }
-    }
-    return Math.ceil(chars / 4);
-}
+export { estimateTokens } from "./context.js";
 /**
  * Owns the state of one multi-turn conversation: the running message history and
  * the usage accumulated across turns. Each `send` continues from the prior
@@ -52,43 +32,150 @@ export class Session {
     usage = { input_tokens: 0, output_tokens: 0 };
     /** Stable id for this session (C.22), so a run's usage record groups with the
      * other runs of the same interactive session (`cruxy usage --session`). */
-    sessionId = randomUUID();
+    sessionId;
     /** The most recent run's usage record (C.22) — the one-shot path reads it to
      * print the end-of-run summary. */
     lastRun;
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
-    /** Mutable so `/plan` can toggle plan mode mid-session. */
-    planMode;
+    /**
+     * The session's mode (P5 track 3) — the ONE piece of state saying how much a
+     * turn does without asking. Mutable so `/mode` and Shift+Tab can change it
+     * mid-session.
+     *
+     * Plan mode is DERIVED from this, not stored beside it. Before P5 the session
+     * held a `planMode` boolean while auto-approve was a (dead) config key, which
+     * is two sources of truth for one question and exactly the shape of bug the
+     * tier work had just finished removing.
+     */
+    mode;
+    /**
+     * How many messages of the CURRENT history the recorder already holds (P2).
+     *
+     * This is what lets an append-only log track an array that is rewritten in
+     * place. The invariant: a replay of the log so far reproduces exactly the
+     * first `recordedCount` messages of the live history. So an append is
+     * `slice(recordedCount)`, and a compaction updates the watermark to the
+     * post-compaction length rather than re-emitting anything.
+     *
+     * It is only ever advanced at points where the history is COHERENT — a
+     * tool_use and its tool_result are never split across a flush — because the
+     * loop calls the compaction seam at the top of an iteration, after the
+     * previous iteration fully resolved its tool calls.
+     */
+    recordedCount = 0;
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
-        // Plan mode requires a wired runner; without one it stays off (no half-on
-        // state where the plan directive is injected but nothing orchestrates it).
-        this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
+        this.mode = this.resolveMode(args.mode ?? DEFAULT_MODE);
+        // Resume (P2): adopt the replayed state verbatim. The history is already
+        // recorded in the log we are continuing, so the watermark starts at its
+        // full length — otherwise the first flush would append the whole restored
+        // conversation a second time.
+        const restore = args.restore;
+        this.sessionId = restore?.sessionId ?? randomUUID();
+        if (restore) {
+            this.messages = restore.messages;
+            this.usage.input_tokens = restore.usage.input_tokens;
+            this.usage.output_tokens = restore.usage.output_tokens;
+            this.recordedCount = restore.messages.length;
+            this.mode = this.resolveMode(restore.mode);
+        }
+    }
+    /**
+     * Resolve a requested mode to one this session can actually honour.
+     *
+     * A planning mode needs a wired `planRunner`; without one it degrades to the
+     * non-planning mode with the same approval behaviour rather than half-engaging
+     * (plan directive injected, nothing orchestrating it). Auto-approve is
+     * unaffected — it needs nothing wired.
+     *
+     * Unknown strings (a journal from a newer build, a hand-edited log) fall back
+     * to the default. Failing closed matters here specifically: the fallback must
+     * be the mode that asks MORE, never one that asks less.
+     */
+    resolveMode(want) {
+        const mode = parseMode(String(want)) ?? DEFAULT_MODE;
+        if (!modePlans(mode) || this.args.planRunner !== undefined)
+            return mode;
+        return mode === "full-auto" ? "auto-approve" : "manual";
+    }
+    /**
+     * Record everything appended to `current` since the last flush.
+     *
+     * Callers must only pass a history whose first `recordedCount` messages are
+     * unchanged — every call site satisfies this because the only operation that
+     * rewrites the head is compaction, which updates the watermark itself.
+     */
+    flushRecorded(current) {
+        if (!this.args.recorder)
+            return;
+        if (current.length <= this.recordedCount)
+            return;
+        this.args.recorder.append(current.slice(this.recordedCount));
+        this.recordedCount = current.length;
     }
     /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
      * shell-bound custom slash command (C.19) runs through the SAME gated path. */
     get toolContext() {
         return this.args.ctx;
     }
+    /**
+     * The tool catalogue advertised to the model this session — the one
+     * `registerRuntimeTools` built, so it reflects which optional families
+     * (memory, LSP, web, MCP, subagents, jobs) are actually enabled. Exposed
+     * read-only, for `/status` to count.
+     */
+    get toolRegistry() {
+        return this.args.registry;
+    }
     /** The background-job manager (C.28), or undefined when jobs are disabled.
      * The REPL uses it to service paused-job approvals and drive `/jobs`; `cruxy
      * run` uses it to cancel every live job on exit. */
     get jobs() {
         return this.args.jobs;
     }
-    /** Whether plan mode is currently on. */
-    getPlanMode() {
-        return this.planMode;
+    /**
+     * The session's live model choice (P6 track 1), or undefined when tiers do not
+     * apply — a bring-your-own provider has no cruxy tiers to choose between, and
+     * `/model` says so rather than offering a menu that could not take effect.
+     *
+     * Exposed as the object rather than proxied through `getModel`/`setModel`
+     * accessors, because the renderer needs to SUBSCRIBE to it, not just read it:
+     * the model panel and the status line have to react to a change within the
+     * same paint, and a getter pair cannot carry that.
+     */
+    get model() {
+        return this.args.model;
+    }
+    /** The session's current mode. */
+    getMode() {
+        return this.mode;
     }
     /**
-     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
-     * the session factory); without one, plan mode stays off.
+     * Set the mode. Returns the EFFECTIVE mode, which differs from the request
+     * when no plan runner is wired — so a caller reports what happened rather
+     * than what it asked for.
      */
-    setPlanMode(enabled) {
-        this.planMode = enabled && this.args.planRunner !== undefined;
+    setMode(mode) {
+        this.mode = this.resolveMode(mode);
+        // Record the effective value, not the request: the log must say what the
+        // session actually did.
+        this.args.recorder?.mode(this.mode);
+        return this.mode;
+    }
+    /** Advance one step around the mode ring (Shift+Tab). Returns the new mode. */
+    cycleMode() {
+        return this.setMode(nextMode(this.mode));
+    }
+    /** Whether this session proposes a plan before executing (C.31). */
+    getPlanMode() {
+        return modePlans(this.mode);
+    }
+    /** Whether gated actions run without a prompt in this session. */
+    getAutoApprove() {
+        return modeAutoApproves(this.mode);
     }
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
@@ -107,6 +194,9 @@ export class Session {
         for (const tool of this.args.registry.list())
             tool.onTurnStart?.();
         this.messages.push({ role: "user", content: userPrompt });
+        // Record the user's turn before anything can fail (P2): a turn that dies in
+        // the provider still leaves what the user asked for on disk.
+        this.flushRecorded(this.messages);
         // Usage telemetry (C.22): one collector per run. `onReq` is threaded into
         // every real model request this turn drives — the main loop, compaction, and
         // (in plan mode) the propose + execution steps — so usage is captured exactly
@@ -137,7 +227,7 @@ export class Session {
         // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
         // plan, approve/revise, then execute step-by-step. Falls back to the normal
         // single-shot loop when off or unwired, so existing behavior is untouched.
-        const result = this.planMode && this.args.planRunner
+        const result = modePlans(this.mode) && this.args.planRunner
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
@@ -167,6 +257,15 @@ export class Session {
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // Persist what the turn produced (P2). The loop's mid-iteration flushes
+        // (via the compaction seam) already recorded most of it; this catches the
+        // tail after the final iteration. Usage is copied into the session log
+        // rather than referenced, because the usage store keeps only its newest 50
+        // runs while sessions are kept indefinitely.
+        this.flushRecorded(this.messages);
+        if (result.usage.input_tokens > 0 || result.usage.output_tokens > 0) {
+            this.args.recorder?.usage(result.usage.input_tokens, result.usage.output_tokens);
+        }
         // Publish the run's usage record (C.22): stash it for the one-shot summary
         // and hand it to the persistence sink. Building the record never touches the
         // network and never blocks the turn's result.
@@ -191,6 +290,11 @@ export class Session {
     /** Drop the conversation history but keep the session (for `/clear`). */
     clear() {
         this.messages = [];
+        // The log keeps every earlier message — `clear` is an event, not an
+        // erasure. Replay honours it, so a resumed session starts empty exactly as
+        // the live one did, while the transcript of what was said survives.
+        this.args.recorder?.clear();
+        this.recordedCount = 0;
     }
     /**
      * Compact `this.messages` only when it has grown past threshold, adopting the
@@ -212,6 +316,16 @@ export class Session {
      * unchanged — cheap, no model call.
      */
     async compactLoopHistory(messages, onRequestUsage) {
+        // Flush BEFORE compacting (P2). The loop owns this array and only ever
+        // appends to it between calls, so everything since the last flush is a pure
+        // append — and it has to be on disk before a compaction event can refer to
+        // a prefix length, or the recorded `replaced` count would be measured
+        // against a shorter history than the one being compacted.
+        //
+        // The loop calls this at the TOP of each iteration, after the previous
+        // iteration resolved all its tool calls, so the history flushed here is
+        // always coherent: no tool_use is ever recorded without its tool_result.
+        this.flushRecorded(messages);
         const result = await this.compactIfOverThreshold(messages, onRequestUsage);
         return result.messages;
     }
@@ -257,7 +371,12 @@ export class Session {
      * the summary's usage into the session total.
      */
     async runCompaction(messages, onRequestUsage) {
-        const cut = this.findCut(messages);
+        // Self-contained sync (P2): whatever array is about to be rewritten must be
+        // fully recorded first, so the `replaced` count in the compaction event is
+        // measured against the same history a replay will have reconstructed. A
+        // no-op when the caller already flushed, which every caller does.
+        this.flushRecorded(messages);
+        const cut = findCut(messages, this.args.config.context.keepRecentMessages);
         if (cut === null)
             return { messages, compacted: null };
         const prefix = messages.slice(0, cut);
@@ -286,37 +405,20 @@ export class Session {
                 content: `${COMPACTION_MARKER} Summary of the conversation so far:\n\n${synopsis}`,
             },
         ];
+        // Record the rewrite as an EVENT (P2): the log stays append-only, and the
+        // messages that were folded away remain readable earlier in the file even
+        // though the model can no longer see them. The watermark moves to the
+        // post-compaction length so the next append is measured against the new
+        // array, not the old one.
+        if (this.args.recorder) {
+            this.args.recorder.compaction(prefix.length, summaryMessages);
+            this.recordedCount = summaryMessages.length + kept.length;
+        }
         return {
             messages: [...summaryMessages, ...kept],
             compacted: prefix.length,
         };
     }
-    /**
-     * Choose the boundary between the summarized prefix and the kept-recent tail.
-     *
-     * Tool-call integrity is the constraint: a `tool_use` (assistant) and its
-     * matching `tool_result` (the next user message) must never straddle the cut,
-     * or the next provider call breaks. A real user *prompt* (`role:"user"` with
-     * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there. The
-     * synthetic compaction-summary user message is also string content, so a
-     * repeat compaction always finds at least the previous summary as a clean cut.
-     *
-     * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
-     * such prompt: this keeps at least the recent floor and lands clean. Returns
-     * the cut index, or `null` if no safe boundary leaves a non-empty prefix
-     * (e.g. a single long in-progress turn — nothing safe to compact).
-     */
-    findCut(messages) {
-        const { keepRecentMessages } = this.args.config.context;
-        const start = messages.length - keepRecentMessages;
-        for (let i = start; i >= 1; i--) {
-            const msg = messages[i];
-            if (msg.role === "user" && typeof msg.content === "string")
-                return i;
-        }
-        return null;
-    }
     /**
      * Summarize a prefix via a standalone, tool-less provider call over a rendered
      * transcript. Throws on a stream error or empty output so callers fail open.
@@ -331,14 +433,22 @@ export class Session {
             ? resolveTaskModel(this.args.router, "summarize")
             : null;
         // Per-request usage capture for telemetry (C.22), same honesty pivot as the
-        // main loop: unknown unless a usage event actually arrives.
+        // main loop: unknown unless a usage event actually arrives. The served tier
+        // is held across the stream for the same reason it is in the loop — it
+        // arrives on the opening frame, and is reported after the close.
         let sawUsage = false;
+        let servedTier;
+        let routingMode;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
             ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
+                case "routing":
+                    servedTier = ev.routing.tier;
+                    routingMode = ev.routing.mode;
+                    break;
                 case "text_delta":
                     text += ev.text;
                     break;
@@ -354,9 +464,12 @@ export class Session {
                     break;
             }
         }
-        // Attribute this compaction request to the `summarize` tier honestly.
+        // Attribute this compaction request to the tier that served it — the
+        // gateway's answer over the `summarize` tier this run asked for, same
+        // precedence and same reasoning as the main loop.
         onRequestUsage?.({
-            tier: routed?.tier,
+            tier: servedTier ?? routed?.tier,
+            ...(routingMode !== undefined ? { routingMode } : {}),
             usage: sawUsage ? { ...usage } : undefined,
         });
         if (!text.trim())

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). */