pi-warden 0.40.2 → 0.47.0

package/dist/guard.js

@@ -1,8 +1,9 @@
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ask, choice, noul, score } from "pi-typesafe";
 import { redact } from "./redact.js";
+import { SPINE_GOAL_LIMIT, SPINE_HISTORY_LIMIT, SPINE_HISTORY_TURNS } from "./shape.js";
 import { globToRegExp } from "./rules.js";
 import { resolveRulesFile } from "./rules-file.js";
 import { COMMAND_TOOLS, commandOf } from "./tools.js";
@@ -79,6 +80,26 @@ function headOf(segment) {
     const head = tokens[index];
     return head ? head.replace(/^.*\//, "") : undefined;
 }
+/** Tools whose first word names what runs: `git log` and `git status` print very different amounts. */
+const SUBCOMMAND_HEADS = new Set(["git", "npm", "pnpm", "yarn", "bun", "cargo", "go", "docker", "kubectl"]);
+/**
+ * The command family the large-output steer is remembered by: the head of the first segment that is not a `cd`, plus the
+ * subcommand for tools that have one (`git log`, `npm test`, `npm run build`). Undefined when no head can be read.
+ */
+export function commandFamily(command) {
+    const segment = splitShell(command).find(part => { const head = headOf(part); return head !== undefined && head !== "cd" && head !== "pushd"; });
+    const head = segment ? headOf(segment) : undefined;
+    if (!segment || !head)
+        return undefined;
+    if (!SUBCOMMAND_HEADS.has(head))
+        return head;
+    const tokens = segment.trim().split(/\s+/);
+    const rest = tokens.slice(tokens.findIndex(token => token.replace(/^.*\//, "") === head) + 1).filter(token => !token.startsWith("-"));
+    const word = (token) => token !== undefined && /^[A-Za-z][\w:.-]*$/.test(token);
+    if (!word(rest[0]))
+        return head;
+    return rest[0] === "run" && word(rest[1]) ? `${head} run ${rest[1]}` : `${head} ${rest[0]}`;
+}
 /**
  * Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything.
  * A double-quoted string that substitutes a command (`"$(...)"`, backticks) executes it, so that string stays visible.
@@ -177,7 +198,7 @@ export function stripDataText(command) {
  * rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are
  * risky. A quote or parenthesis before `rm` is allowed so a quoted or substituted command is read; data quotes were blanked before this runs.
  */
-function classifyRm(segment, cwd) {
+function classifyRm(segment, cwd, scratch) {
     const match = /(?:^|[\s"'(])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
@@ -196,6 +217,10 @@ function classifyRm(segment, cwd) {
             return cwd ? !isInside(clean, cwd) : true;
         return clean.split(/[\\/]/).includes("..");
     });
+    const budget = scratchBudget();
+    if (dangerousTarget && scratch?.size && targets.length && targets.every(target => isSessionScratch(target, scratch, budget))) {
+        return { id: "rm-session-scratch", severity: "risky", label: "recursive rm of session scratch: every target is under the temp directory and was created in this session" };
+    }
     if (dangerousTarget)
         return { id: "rm-recursive-dangerous-target", severity: "destructive", label: "recursive rm on an absolute, home, variable, or parent path" };
     if (force)
@@ -206,6 +231,273 @@ function isInside(target, cwd) {
     const rel = relative(resolve(cwd), resolve(target));
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
+// ---------------------------------------------------------------------------
+// Session scratch: paths the agent created under the OS temp directory in this session. A recursive rm whose every
+// target is such a path, after symlinks are resolved, is risky rather than destructive. Everything here fails closed:
+// a path that cannot be resolved, or that uses shell expansion, is not scratch.
+/**
+ * Whether the exemption applies on this platform. It rests on birth time being a real creation time: macOS and Windows
+ * report one; Linux without `statx` reports ctime, which `mv` updates, so moved-in content would pass the tree walk.
+ * Elsewhere nothing is recorded and a recursive rm is classified as if no scratch existed.
+ */
+export function scratchPlatform(platform = process.platform) {
+    return platform === "darwin" || platform === "win32";
+}
+/** The identity of a path itself (a symlink is not followed); undefined when it does not exist. */
+export function scratchIdentity(path) {
+    try {
+        const stats = lstatSync(path);
+        return { dev: stats.dev, ino: stats.ino, birthtimeMs: stats.birthtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+function sameIdentity(a, b) {
+    return a !== undefined && a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+}
+/** Drops records whose path is gone or now names a different file, so a later file at the same path is not scratch. */
+export function pruneScratch(records) {
+    for (const [path, identity] of records)
+        if (!sameIdentity(scratchIdentity(path), identity))
+            records.delete(path);
+}
+/** Real paths of the temp roots that exist: `os.tmpdir()`, `$TMPDIR`, `/tmp`, `/private/tmp`. */
+export function tempRoots() {
+    const roots = new Set();
+    for (const root of [tmpdir(), process.env.TMPDIR, "/tmp", "/private/tmp"]) {
+        if (!root || !isAbsolute(root))
+            continue;
+        try {
+            roots.add(realpathSync(root));
+        }
+        catch { /* absent on this system */ }
+    }
+    return [...roots];
+}
+/**
+ * The real path of an absolute path: the realpath of its deepest existing ancestor plus the missing rest. Undefined when
+ * a component exists but cannot be resolved (a dangling symlink, a loop, no permission).
+ */
+export function realTarget(path) {
+    const rest = [];
+    let head = resolve(path);
+    for (;;) {
+        try {
+            return join(realpathSync(head), ...rest.reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return undefined;
+            try {
+                lstatSync(head);
+                return undefined;
+            }
+            catch { /* missing: resolve the parent */ }
+            const parent = dirname(head);
+            if (parent === head)
+                return undefined;
+            rest.push(basename(head));
+            head = parent;
+        }
+    }
+}
+/** The temp root a real path lies strictly under; a temp root itself has none. */
+export function tempRootOf(real, roots = tempRoots()) {
+    return roots.find(root => real !== root && real.startsWith(root.endsWith(sep) ? root : root + sep));
+}
+/** A privilege-raising command word anywhere in a command. */
+const PRIVILEGED = /(?:^|[\s;&|("'`])(?:sudo|doas|su|pkexec|run0)(?=\s|$)/m;
+/** A literal absolute path: no quotes left inside, no glob, brace, tilde, variable, escape, or substitution. */
+const LITERAL_PATH = /^\/[^*?[\]{}$`~\\"'\s]*$/;
+/**
+ * 10,000 entries covers a generated test tree of a few thousand directories with room to spare, and 200 ms keeps the
+ * synchronous walk in the tool-call hook short. A tree that needs more is not checked, so it keeps the hold.
+ */
+const scratchBudget = () => ({ entries: 10_000, deadline: Date.now() + 200 });
+/**
+ * True when every entry of the tree at `path`, the root included, has a birth time at or after `born`. Symlinks are
+ * checked as links and never followed. False when the root is missing, an entry has no birth time or cannot be read,
+ * or the walk runs past its budget: content moved in from elsewhere keeps its older birth time and must not pass.
+ */
+export function bornAfter(path, born, budget = scratchBudget()) {
+    if (!(born > 0))
+        return false;
+    const stack = [path];
+    while (stack.length) {
+        if (--budget.entries < 0 || Date.now() > budget.deadline)
+            return false;
+        const current = stack.pop();
+        try {
+            const stats = lstatSync(current);
+            if (!(stats.birthtimeMs > 0) || stats.birthtimeMs < born)
+                return false;
+            if (stats.isDirectory())
+                for (const name of readdirSync(current))
+                    stack.push(join(current, name));
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+function isSessionScratch(target, scratch, budget) {
+    const clean = target.replace(/^["']|["']$/g, "");
+    if (!LITERAL_PATH.test(clean) || clean.split("/").includes(".."))
+        return false;
+    const real = realTarget(clean);
+    const root = real === undefined ? undefined : tempRootOf(real);
+    if (!real || !root)
+        return false;
+    for (let path = real; path !== root && path.startsWith(root); path = dirname(path)) {
+        const recorded = scratch.get(path);
+        if (recorded)
+            return sameIdentity(scratchIdentity(path), recorded) && bornAfter(real, recorded.birthtimeMs, budget);
+    }
+    return false;
+}
+/** `mkdir` targets in a command that are literal absolute paths; flags and relative operands are skipped. */
+function mkdirTargets(command) {
+    const targets = [];
+    for (const segment of splitShell(stripDataText(command).text)) {
+        if (headOf(segment) !== "mkdir")
+            continue;
+        const tokens = segment.trim().split(/\s+/);
+        for (const token of tokens.slice(tokens.findIndex(token => token.replace(/^.*\//, "") === "mkdir") + 1)) {
+            const clean = token.replace(/^["']|["']$/g, "");
+            if (LITERAL_PATH.test(clean) && !clean.split("/").includes(".."))
+                targets.push(clean);
+        }
+    }
+    return targets;
+}
+/**
+ * Real paths under a temp root that this call may create and that do not exist yet: `mkdir` targets of a shell command,
+ * or a written file. Each path and its missing ancestors below the temp root are listed. Taken before the call runs, so
+ * a directory that already existed is never recorded as created.
+ */
+export function scratchCandidates(tool, input, cwd, platform = process.platform) {
+    if (!scratchPlatform(platform))
+        return [];
+    const command = tool === "bash" ? commandOf(tool, input)?.command : undefined;
+    const paths = command ? mkdirTargets(command) : tool === "write" && typeof input.path === "string" && !input.path.startsWith("~") ? [resolve(cwd, input.path)] : [];
+    const roots = tempRoots();
+    const missing = new Set();
+    for (const path of paths) {
+        const real = realTarget(path);
+        const root = real === undefined ? undefined : tempRootOf(real, roots);
+        if (!real || !root)
+            continue;
+        for (let current = real; current !== root && !existsSync(current); current = dirname(current))
+            missing.add(current);
+    }
+    return [...missing];
+}
+/** At most this many temp paths are read from one tool result. */
+const SCRATCH_OUTPUT_LIMIT = 20;
+/** Absolute paths in text that start with a temp root, as spelled or as resolved. */
+function tempPathsIn(text, roots) {
+    const prefixes = new Set(roots);
+    for (const root of [tmpdir(), process.env.TMPDIR, "/tmp", "/private/tmp"])
+        if (root && isAbsolute(root))
+            prefixes.add(root.replace(/\/+$/, ""));
+    const alternatives = [...prefixes].map(prefix => prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const pattern = new RegExp(`(?:^|[\\s"'=:(\\[])((?:${alternatives})/[^\\s"'\`:,;()[\\]{}<>*?$\\\\]+)`, "gm");
+    const found = new Set();
+    for (const match of text.matchAll(pattern)) {
+        found.add(match[1].replace(/[./]+$/, ""));
+        if (found.size >= SCRATCH_OUTPUT_LIMIT)
+            break;
+    }
+    return [...found];
+}
+/**
+ * Real paths the call created, read after it ran, each with its identity. A candidate from `scratchCandidates` counts
+ * when it now exists as itself (not through a symlink). For a shell command, absolute temp paths printed in its output
+ * also count, bounded: the first 20 such paths only, each must exist under a temp root as a real directory or file, and
+ * its birth time must fall in a later millisecond than `started` (`Date.now()` when the call began). Where the file
+ * system reports no birth time, a printed path counts only from a command that does nothing but run `mktemp` and print
+ * what it made (`mktempOnly`). `birthtime` reads a file's birth time in milliseconds, 0 when the file system has none.
+ * Nothing is recorded where `scratchPlatform` is false.
+ */
+export function createdScratch(tool, input, output, started, candidates, birthtime = (stats) => stats.birthtimeMs, platform = process.platform) {
+    if (!scratchPlatform(platform))
+        return new Map();
+    const found = [];
+    for (const path of candidates) {
+        try {
+            if (realpathSync(path) === path)
+                found.push(path);
+        }
+        catch { /* not created */ }
+    }
+    const command = tool === "bash" ? commandOf(tool, input)?.command : undefined;
+    if (command)
+        found.push(...printedScratch(command, output, started, birthtime));
+    const created = new Map();
+    for (const path of found) {
+        const identity = scratchIdentity(path);
+        if (identity)
+            created.set(path, identity);
+    }
+    return created;
+}
+/** Arguments of a `mktemp` that creates something: literal words only, and no `-u`/`--dry-run`. */
+const MKTEMP_ARGS = String.raw `((?:\s+[^\s$\`<>()"']+)*)`;
+const MKTEMP_ALONE = new RegExp(String.raw `^mktemp${MKTEMP_ARGS}$`);
+const MKTEMP_ASSIGN = new RegExp(String.raw `^([A-Za-z_]\w*)=("?)\$\(\s*mktemp${MKTEMP_ARGS}\s*\)\2$`);
+const ECHO_VARS = /^echo((?:\s+"?\$\{?[A-Za-z_]\w*\}?"?)+)$/;
+/**
+ * How many paths a command that only makes temp files may print: each segment is a bare `mktemp`, an assignment
+ * `name=$(mktemp …)`, or an `echo` of names assigned that way. 0 for any other command.
+ */
+export function mktempOnly(command) {
+    const assigned = new Set();
+    let made = 0;
+    for (const segment of splitShell(command)) {
+        const alone = MKTEMP_ALONE.exec(segment);
+        const assign = alone ? undefined : MKTEMP_ASSIGN.exec(segment);
+        const args = alone?.[1] ?? assign?.[3];
+        if (args !== undefined) {
+            if (/(?:^|\s)(?:-[a-zA-Z]*u[a-zA-Z]*|--dry-run)(?=\s|$)/.test(args))
+                return 0;
+            if (assign)
+                assigned.add(assign[1]);
+            made++;
+            continue;
+        }
+        const echo = ECHO_VARS.exec(segment);
+        if (!echo || ![...echo[1].matchAll(/\$\{?([A-Za-z_]\w*)/g)].every(name => assigned.has(name[1])))
+            return 0;
+    }
+    return made;
+}
+function printedScratch(command, output, started, birthtime) {
+    const created = [];
+    const made = mktempOnly(command);
+    const lines = output.split("\n").map(line => line.trim()).filter(Boolean);
+    const roots = tempRoots();
+    for (const path of tempPathsIn(output, roots)) {
+        if (path.split("/").includes(".."))
+            continue;
+        try {
+            const real = realpathSync(path);
+            if (!tempRootOf(real, roots))
+                continue;
+            const stats = statSync(real);
+            if (!stats.isDirectory() && !stats.isFile())
+                continue;
+            const birth = birthtime(stats);
+            const born = birth > 0 ? Math.floor(birth) > started : made > 0 && lines.length <= made && lines.includes(path);
+            if (born)
+                created.push(real);
+        }
+        catch { /* gone or unreadable */ }
+    }
+    return created;
+}
 /** Every id exemptRules can legitimately name: the built-in shell rules, the rm-classifier's derived ids, and the
  * sensitive-path id. Unknown ids (a typo, or a rule that never existed) are inert; this list lets the surface be
  * reported once instead of discovered when the rule the user meant to silence keeps firing. */
@@ -214,6 +506,7 @@ export const EXEMPTABLE_IDS = [
     "rm-recursive",
     "rm-rf",
     "rm-recursive-dangerous-target",
+    "rm-session-scratch",
     "sensitive-path",
 ];
 /** Built-in pattern IDs whose hits become evidence (not level-setters) in evidence mode.
@@ -269,8 +562,10 @@ export function matchPatterns(tool, input, cwd, options) {
         for (const rule of SHELL_RULES)
             if (!exempt.has(rule.id) && rule.test.test(command))
                 add({ id: rule.id, severity: rule.severity, label: rule.label });
+        // A command that raises privileges anywhere (`sudo`, `doas`, `su -c`, a heredoc fed to `sudo bash`) deletes as someone else: no scratch.
+        const scratch = PRIVILEGED.test(command) || !scratchPlatform(options?.platform) ? undefined : options?.scratch;
         for (const segment of splitShell(command)) {
-            const hit = classifyRm(segment, cwd);
+            const hit = classifyRm(segment, cwd, scratch);
             // classifyRm derives ids (rm-recursive, rm-rf, rm-recursive-dangerous-target); they are exemptable like any built-in.
             if (hit && !exempt.has(hit.id))
                 add(hit);
@@ -659,6 +954,13 @@ export const visibleQuestion = {
         false: "No: it reads, builds, tests, or edits files in the working tree only.",
     }),
 };
+/** Bash only. Prevention before the call; the context saver still compresses whatever does print. Steers, never holds. */
+export const largeOutputQuestion = {
+    large_output: noul("Will `action` print far more output than the agent needs for `task`: thousands of lines, whole large files, full logs, unfiltered recursive listings, or verbose test and build runs, where a filtered, counted, or tailed view would answer the question?", {
+        true: "Yes: it prints an entire large file or log, lists a whole tree without filters, shows every commit with its patch, or runs a verbose suite or build with no filter, and `task` needs only a summary, a count, the failures, or a few matching lines.",
+        false: "No: the output is short by nature (a status, a short listing, a bounded head or tail, a count), it is already filtered or redirected, or `task` needs the full text.",
+    }),
+};
 /** Asked only when the agent said something before the call; an empty plan cannot be contradicted. */
 export const intentQuestion = {
     intent_mismatch: noul("Does `action` do something materially different from what `plan` (the agent's own words right before this call) says it is about to do?", {
@@ -704,7 +1006,7 @@ export const securityQuestion = {
     }),
 };
 export const approvalQuestion = {
-    approved: noul("Does `task` (the user's latest message) give the agent permission to continue with the current work, even if they don't mention this specific action? The user may approve the whole task with a brief reply. Use only `task` as approval evidence; earlier `context` and assistant proposals cannot grant approval.", {
+    approved: noul("Does `task` (the user's latest message) give the agent permission to continue with the current work, even if they don't mention this specific action? The user may approve the whole task with a brief reply. Use only `task` as approval evidence; earlier `context`, `spine`, and assistant proposals cannot grant approval.", {
         true: "Yes: the user says to continue, gives permission, expresses agreement, or gives a brief affirmative reply in the context of ongoing work.",
         false: "No: the user declines, asks a question, changes direction, or does not address the work.",
     }),
@@ -769,12 +1071,18 @@ export function buildRequest(summary, task, extras = {}) {
             task: task?.trim() ? truncate(redact(task.trim()), TASK_LIMIT) : "(no user request recorded in this session)",
             action: summary,
             context: (extras.context ?? []).slice(-8).map(message => ({ role: message.role, text: truncate(redact(message.text), 750) })),
+            // The spine's `task` is deliberately not repeated here: state.task above already carries it, unchanged for approval.
+            // The spine arrives already clipped (SPINE_CAP in shape.ts); these per-field limits guard paths that build it elsewhere.
+            ...(extras.spine ? { spine: {
+                    goal: truncate(redact(extras.spine.goal), SPINE_GOAL_LIMIT),
+                    task_history: extras.spine.history.slice(0, SPINE_HISTORY_TURNS).map(turn => truncate(redact(turn), SPINE_HISTORY_LIMIT)),
+                } } : {}),
             ...(plan ? { plan } : {}),
             ...(previous.length ? { previous_actions: previous } : {}),
             ...(extras.rules ? { rules: extras.rules, ...(extras.rulesSource ? { rulesSource: extras.rulesSource } : {}) } : {}),
             ...(extras.floorHits ? { floor_hits: extras.floorHits } : {}),
         },
-        questions: { ...shouldProceedQuestion, ...questions, ...(summary.command !== undefined ? visibleQuestion : {}), ...(plan ? intentQuestion : {}), ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}), ...(extras.security && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary) ? securityQuestion : {}), ...(previous.length ? regretQuestions(previous) : {}), ...violationQuestions, ...(extras.questions ?? {}) },
+        questions: { ...shouldProceedQuestion, ...questions, ...(summary.command !== undefined ? visibleQuestion : {}), ...(plan ? intentQuestion : {}), ...(extras.largeOutput && summary.tool === "bash" ? largeOutputQuestion : {}), ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}), ...(extras.security && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary) ? securityQuestion : {}), ...(previous.length ? regretQuestions(previous) : {}), ...violationQuestions, ...(extras.questions ?? {}) },
     };
 }
 const percent = (value) => value.toFixed(2);
@@ -792,7 +1100,7 @@ export async function evaluateAction(action, options) {
     }
     const plan = describePlan(action.plan);
     const withPlan = (verdict) => (plan ? { ...verdict, plan } : verdict);
-    const patterns = matchPatterns(action.tool, action.input, action.cwd, { commandRules: config.commandRules, commandDenyRules: config.commandDenyRules, exemptRules: config.exemptRules, pathRules: config.pathRules });
+    const patterns = matchPatterns(action.tool, action.input, action.cwd, { commandRules: config.commandRules, commandDenyRules: config.commandDenyRules, exemptRules: config.exemptRules, pathRules: config.pathRules, scratch: options.scratch });
     // Violation pipeline: authorize per-violation, remove authorized from level computation and Jev questions.
     const allViolations = patternHitsToViolations(patterns, action.tool, action.input);
     const allAuthorizations = allViolations.map(v => authorize(action.task ?? "", v));
@@ -881,7 +1189,7 @@ export async function evaluateAction(action, options) {
     // count, so the content sent here is the content the guard judges with.
     const resolved = options.rules?.enabled === false ? null : resolveRulesFile(action.cwd, options.rules);
     const floorHits = builtInHits.length ? builtInHits.join("; ") : "none";
-    const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context, previousActions: options.previousActions, plan, questions: options.questions, rules: resolved?.content, rulesSource: resolved?.source, violations: remainingViolations, floorHits });
+    const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context, previousActions: options.previousActions, plan, questions: options.questions, rules: resolved?.content, rulesSource: resolved?.source, violations: remainingViolations, floorHits, spine: action.spine, largeOutput: options.largeOutput?.enabled ?? false });
     const result = await ask(judge, request, { timeoutMs: config.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });
     if (!result.ok) {
         if (!config.failOpen) {
@@ -918,6 +1226,8 @@ export async function evaluateAction(action, options) {
         judgment.intentMismatch = answers.intent_mismatch.noul;
     if (summary.command !== undefined && typeof answers.visible?.noul === "number")
         judgment.visible = answers.visible.noul;
+    if (options.largeOutput?.enabled && action.tool === "bash" && typeof answers.large_output?.noul === "number")
+        judgment.largeOutput = answers.large_output.noul;
     if (typeof answers.regretted?.noul === "number") {
         judgment.regretted = answers.regretted.noul;
         if (typeof answers.regret_target?.choice === "string")
@@ -1037,6 +1347,12 @@ export async function evaluateAction(action, options) {
         verdict.offTaskSteer = true;
     if (offTaskTraceOnly)
         verdict.offTaskTraceOnly = true;
+    // Large output steers and never changes the level: the saver compresses what prints, this asks the agent to print less.
+    if (judgment.largeOutput !== undefined && judgment.largeOutput >= options.largeOutput.threshold && view) {
+        const family = commandFamily(view.command);
+        if (family)
+            verdict.largeOutputFamily = family;
+    }
     if (shouldProceedSteer)
         verdict.shouldProceedSteer = true;
     if (shouldProceedTraceOnlyReasonIndex !== undefined) {
@@ -1133,6 +1449,24 @@ export function offTaskSteer(verdict) {
     const score = verdict.judgment?.offTask;
     return `pi-warden: this ${verdict.summary.tool} call looks unrelated to the user's request${score === undefined ? "" : ` (off-task ${percent(score)})`}. It ran. If it serves the request, say how in at most one short sentence; otherwise return to what the user asked for, or ask before widening the work. Do not restate session state or re-answer notices you have already addressed.`;
 }
+/** What the agent reads the first time a command family is judged noisy: the family and one concrete way to print less. */
+export function largeOutputSteer(verdict) {
+    const family = verdict.largeOutputFamily ?? verdict.summary.tool;
+    const score = verdict.judgment?.largeOutput;
+    const log = `/tmp/warden-${family.replace(/[^A-Za-z0-9]+/g, "-")}.log`;
+    return [
+        `pi-warden: \`${family}\` commands may print far more than you need${score === undefined ? "" : ` (large-output ${percent(score)})`}. This one runs unchanged.`,
+        `Next time, redirect and show the tail: \`${family} … > ${log} 2>&1; tail -40 ${log}\`.`,
+    ].join("\n");
+}
+/** The large-output steer for this verdict, once per command family per session; `steered` is the session's memory. */
+export function largeOutputNotice(verdict, steered) {
+    const family = verdict.largeOutputFamily;
+    if (!family || steered.has(family))
+        return undefined;
+    steered.add(family);
+    return largeOutputSteer(verdict);
+}
 /** Offline stand-in for the approval question when TypeSafe is not available. */
 export function textApproves(task) {
     return /\b(?:yes|yep|yeah|go ahead|do it|proceed|approved?|confirm(?:ed)?|ok(?:ay)?|sure|please do|run it)\b/i.test(task ?? "") && !/\b(?:no|don't|do not|stop|wait|instead|not)\b/i.test(task ?? "");
@@ -1166,6 +1500,7 @@ const ACTION_VERBS = {
     "rm-recursive": ["delete", "remove", "clean", "tidy", "purge"],
     "rm-rf": ["delete", "remove", "clean", "tidy", "purge"],
     "rm-recursive-dangerous-target": ["delete", "remove", "clean", "tidy", "purge"],
+    "rm-session-scratch": ["delete", "remove", "clean", "tidy", "purge"],
     "find-delete": ["delete", "remove", "clean", "tidy", "purge"],
     "git-rm": ["delete", "remove", "clean", "tidy", "purge"],
     "publish": ["publish"],
@@ -1265,7 +1600,7 @@ export function isAuthEligible(severity) {
     // Pattern-detected risky/destructive hits are auth-eligible (user can explicitly authorize)
     return true;
 }
-const RM_FAMILY_IDS = new Set(["rm", "rm-recursive", "rm-rf", "rm-recursive-dangerous-target", "find-delete"]);
+const RM_FAMILY_IDS = new Set(["rm", "rm-recursive", "rm-rf", "rm-recursive-dangerous-target", "rm-session-scratch", "find-delete"]);
 const RM_COMMAND_RE = /(?:^|[\s"'(])rm\s+(.*)$/i;
 /** Extract file targets from every rm segment in a command. */
 function detectRmTargets(command) {

package/dist/holds.d.ts

@@ -130,6 +130,8 @@ export declare function textRegrets(prompt: string | undefined): boolean;
 export declare function outcomeNote(record: CallRecord): string;
 /** One line for /warden status. */
 export declare function formatHolds(snapshot: HoldSnapshot, logPath?: string): string;
+/** The session id as a file name part: no separators or dots, so it cannot leave the directory it is joined to. */
+export declare function sessionFileId(sessionId: string): string;
 /** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
 export declare function holdLogPath(sessionId: string, at?: Date): string;
 /** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */

package/dist/holds.js

@@ -204,11 +204,14 @@ export function formatHolds(snapshot, logPath) {
     parts.push(`${snapshot.allowed} allowed (${snapshot.regretted} regretted by you, ${snapshot.accepted} accepted)`);
     return `Holds: ${parts.join("; ")}.${logPath ? ` Log: ${logPath}.` : ""}`;
 }
+/** The session id as a file name part: no separators or dots, so it cannot leave the directory it is joined to. */
+export function sessionFileId(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || String(process.pid);
+}
 /** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
 export function holdLogPath(sessionId, at = new Date()) {
     const day = at.toISOString().slice(0, 10);
-    const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || String(process.pid);
-    return join(dirname(userConfigPath()), "holds", `${day}-${safe}.jsonl`);
+    return join(dirname(userConfigPath()), "holds", `${day}-${sessionFileId(sessionId)}.jsonl`);
 }
 /** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */
 export class HoldLog {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
+export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, largeOutputSteer, largeOutputNotice, largeOutputQuestion, commandFamily, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
 export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, PreviousAction, ScannedCommand, ScopeLabel, Severity, Verdict, Violation, ViolationSource, ViolationScope, Authorization, EscalatedViolation, ViolationJudgmentAnswer } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
@@ -29,7 +29,7 @@ export type { CallOutcome, CallRecord, CallScores, HoldSnapshot, OutcomeVia } fr
 export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, setNestedValue, getNestedValue, parseConfigValue, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, OffTaskThreshold, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, RulesConfig, ContextConfig, RunawayConfig, NotifyConfig, SubagentConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export type { ActionGuardConfig, OffTaskThreshold, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, RulesConfig, ContextConfig, LargeOutputConfig, RunawayConfig, NotifyConfig, SubagentConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export type { CommandView } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, SENTENCE_TEMPLATES, pickSentenceTemplate, TOKEN_NAMES } from "./widget.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
+export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, largeOutputSteer, largeOutputNotice, largeOutputQuestion, commandFamily, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";

package/dist/judge-cooldown.d.ts

@@ -0,0 +1,44 @@
+/** A failed judge request, as a category safe to name (never an exception body). */
+export type JudgeFailureKind = "timeout" | "network" | "auth" | "configuration" | "other";
+export interface JudgeCooldownSettings {
+    /** Consecutive transient failures that start the cooldown. */
+    failuresBeforeCooldown: number;
+    /** How long the judge is left alone once the cooldown starts. */
+    cooldownMs: number;
+}
+/** Classify a judge error into a safe category (spec §6: never exception bodies). */
+export declare function classifyJudgeError(err: unknown): JudgeFailureKind;
+/**
+ * What a failure says about the backend, or `undefined` when it says nothing.
+ *
+ * `budget` already stops judgments for the session on its own. `validation` is thrown locally for one malformed
+ * request (too many questions, input over the byte limit) and says nothing about the backend. `aborted` is ambiguous: pi-warden's own per-request
+ * deadline reaches the SDK as an abort, so a hung backend surfaces as `aborted`, not `timeout`. The signal's reason
+ * tells the two apart; only a user's cancel is left out.
+ */
+export declare function cooldownFailureKind(err: unknown, signal?: AbortSignal): JudgeFailureKind | undefined;
+export type CooldownEvent = {
+    type: "started";
+    kind: JudgeFailureKind;
+    ms: number;
+} | {
+    type: "recovered";
+};
+/**
+ * Session-scoped pause on a failing judge, so a dead backend costs one notice instead of one timeout per action.
+ * Nothing is persisted; a new session starts with the judge trusted again.
+ */
+export declare class JudgeCooldown {
+    private readonly now;
+    private failures;
+    private until;
+    /** A window has started and no judgment has succeeded since, so the user was told and not yet told it recovered. */
+    private cooled;
+    constructor(now?: () => number);
+    /** True while judgments are paused. */
+    active(): boolean;
+    failure(kind: JudgeFailureKind, settings: JudgeCooldownSettings): CooldownEvent | undefined;
+    success(): CooldownEvent | undefined;
+    reset(): void;
+    private open;
+}