pi-warden 0.60.0 → 0.71.0

package/dist/guard.d.ts

@@ -156,6 +156,10 @@ export interface Verdict {
     plan?: string;
     /** True when Jev finds the call at odds with the agent's stated plan and the call can change something; the agent is told. */
     intentMismatch?: boolean;
+    /** The intent mismatch is recorded in the trace but the agent is not told (`action.intentTraceOnly`). */
+    intentTraceOnly?: boolean;
+    /** Index of the trace-only intent-mismatch reason; any prepend must adjust this index. */
+    intentTraceOnlyReasonIndex?: number;
     /** True when Jev finds the call unrelated to the request on a call that can change something. Still steered in the reason log, but the steer message is suppressed until AUC improves above 0.51. */
     offTaskSteer?: boolean;
     /** True when should_proceed is below the hold threshold; the agent is told to pause and ask. */

package/dist/guard.js

@@ -184,6 +184,99 @@ function isDataSegment(segment) {
         return /\s--(?:body|title|notes)\b/.test(segment) || /\s-[bt]\s/.test(segment);
     return DATA_HEADS.has(head);
 }
+const GH_MESSAGE_FLAGS = new Set(["--body", "-b", "--title", "-t", "--notes"]);
+const GH_MESSAGE_OBJECTS = new Set(["pr", "issue", "release"]);
+const GH_MESSAGE_VERBS = new Set(["create", "edit", "comment"]);
+const GIT_FLAG_SUBCOMMANDS = new Set(["commit", "tag"]);
+/** Whether `flag`, read after `words` of one simple command, takes a message as its value. */
+function isMessageFlag(words, flag) {
+    let index = 0;
+    while (index < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index]) || WRAPPERS.has(words[index])))
+        index++;
+    const head = words[index]?.replace(/^.*\//, "");
+    const rest = words.slice(index + 1);
+    if (head === "gh")
+        return GH_MESSAGE_OBJECTS.has(rest[0] ?? "") && GH_MESSAGE_VERBS.has(rest[1] ?? "") && GH_MESSAGE_FLAGS.has(flag);
+    if (head !== "git")
+        return false;
+    // `git -c alias.x=!cmd` runs a shell command, so a config override keeps the whole command in scope.
+    if (rest.some(word => word === "-c" || word.startsWith("--config")))
+        return false;
+    let sub = 0;
+    while (sub < rest.length && rest[sub].startsWith("-"))
+        sub += rest[sub] === "-C" ? 2 : 1;
+    return GIT_FLAG_SUBCOMMANDS.has(rest[sub] ?? "") && sub < rest.length && (flag === "--message" || /^-[a-zA-Z]*m$/.test(flag));
+}
+/**
+ * Blanks the quoted values of message flags (`gh pr create --body`, `git commit -m`, and their `=` forms) across the
+ * whole command. It reads quotes before separators, so a body that holds `;`, `&&`, or new lines stays one value;
+ * `splitShell` alone would cut it into segments that look like commands. A value with `$(`, backticks, or an unclosed
+ * quote is kept, because the shell runs or re-reads it.
+ */
+function blankMessageFlags(command) {
+    let out = "";
+    let words = [];
+    let word = "";
+    let pending = false;
+    const flush = () => {
+        if (!word)
+            return;
+        pending = isMessageFlag(words, word);
+        words.push(word);
+        word = "";
+    };
+    for (let index = 0; index < command.length;) {
+        const char = command[index];
+        if (/[\n;&|]/.test(char)) {
+            flush();
+            words = [];
+            pending = false;
+            out += char;
+            index++;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            flush();
+            out += char;
+            index++;
+            continue;
+        }
+        if (char === "\\") {
+            word += command.slice(index, index + 2);
+            out += command.slice(index, index + 2);
+            index += 2;
+            continue;
+        }
+        const ansi = char === "$" && command[index + 1] === "'";
+        if (char !== "'" && char !== "\"" && !ansi) {
+            word += char;
+            out += char;
+            index++;
+            continue;
+        }
+        const open = ansi ? index + 1 : index;
+        const quote = command[open];
+        let end = open + 1;
+        while (end < command.length && command[end] !== quote)
+            end += quote !== "'" || ansi ? (command[end] === "\\" ? 2 : 1) : 1;
+        if (end >= command.length)
+            return out + command.slice(index);
+        const raw = command.slice(index, end + 1);
+        const inner = command.slice(open + 1, end);
+        const flagValue = (word === "" && pending) || (word.endsWith("=") && isMessageFlag(words, word.slice(0, -1)));
+        if (flagValue && !SUBSTITUTION.test(inner)) {
+            out += `${quote}[text]${quote}`;
+            word += `${quote}[text]${quote}`;
+        }
+        else {
+            out += raw;
+            word += raw;
+        }
+        pending = false;
+        index = end + 1;
+    }
+    return out;
+}
 /**
  * Removes heredoc bodies that are not fed to a shell and quoted arguments of data commands. Interpreter heredocs
  * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
@@ -222,7 +315,8 @@ export function stripDataText(command) {
             out.push(lines[close]);
         index = close;
     }
-    const joined = out.join("\n");
+    const scanned = out.join("\n");
+    const joined = blankMessageFlags(scanned);
     const segments = splitShell(joined);
     // A shell sink anywhere may run text written earlier in the same command (`cat <<EOF > run.sh` then `bash run.sh`), so nothing is treated as data.
     if (segments.some(segment => { const head = headOf(segment); return head !== undefined && SHELL_SINKS.has(head); }))
@@ -230,6 +324,8 @@ export function stripDataText(command) {
     if (/\b(?:ba|z|da|k)?sh\s+-[a-zA-Z]*c\b/.test(joined))
         return { text: command, stripped: false };
     let text = joined;
+    if (joined !== scanned)
+        stripped = true;
     for (const segment of segments) {
         if (!isDataSegment(segment) || !/["']/.test(segment))
             continue;
@@ -243,13 +339,13 @@ 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.
+ * risky. A quote, parenthesis, or backtick before `rm` is allowed so a quoted or substituted command is read; data quotes were blanked before this runs.
  */
 function classifyRm(segment, cwd, scratch) {
-    const match = /(?:^|[\s"'(])rm\s+(.*)$/.exec(segment);
+    const match = /(?:^|[\s"'(`])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
-    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["')]+$/, ""));
+    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["')`]+$/, ""));
     const flags = tokens.filter(token => token.startsWith("-"));
     const targets = tokens.filter(token => !token.startsWith("-"));
     const recursive = flags.some(flag => flag === "--recursive" || (/^-[a-zA-Z]+$/.test(flag) && /[rR]/.test(flag)));
@@ -414,6 +510,15 @@ export function tempRootOf(real, roots = tempRoots()) {
 }
 /** A privilege-raising command word anywhere in a command. */
 const PRIVILEGED = /(?:^|[\s;&|("'`])(?:sudo|doas|su|pkexec|run0)(?=\s|$)/m;
+/**
+ * Command words that can put existing data under a temp path before a later rm deletes it: a move, a link (`rm -rf
+ * link/` follows it), a copy or extract that can carry links (`cp -R`, `tar -x`, `git clone`), a sync that removes its
+ * source, a mount. The birth-time walk runs before the command, so it cannot see what the command itself moves in. Any
+ * `cp` or `tar` counts, whatever its flags. Read on `unquoted` text, so `\mv`, `"ln"`, and `l''n` count too.
+ */
+const MOVES_IN = /(?:^|[\s;&|(`/])(?:(?:g|bsd)?(?:mv|ln|cp|tar)|rsync|mount|hdiutil|bindfs|git(?=\s)[^;&|\n]*\sclone)(?=[\s;&|)`]|$)/m;
+/** A command with its quotes and backslashes removed, so a quoted or escaped command word reads as the word it runs. */
+const unquoted = (command) => command.replace(/\$(?=['"])|['"\\]/g, "");
 /** A literal absolute path: no quotes left inside, no glob, brace, tilde, variable, escape, or substitution. */
 const LITERAL_PATH = /^\/[^*?[\]{}$`~\\"'\s]*$/;
 /**
@@ -1123,8 +1228,10 @@ export function matchPatterns(tool, input, cwd, options) {
                 add({ id: rule.id, severity: rule.severity, label: rule.label });
         applySqlTargets(raw, hits, exempt);
         applyGitState(raw, hits, cwd);
-        // 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;
+        // A command that raises privileges anywhere (`sudo`, `doas`, `su -c`, a heredoc fed to `sudo bash`) deletes as someone else,
+        // and one that moves, links, copies, or extracts data can fill a path after the birth-time walk: no scratch.
+        const movesIn = MOVES_IN.test(unquoted(raw)) || MOVES_IN.test(unquoted(command));
+        const scratch = PRIVILEGED.test(command) || movesIn || !scratchPlatform(options?.platform) ? undefined : options?.scratch;
         for (const segment of splitShell(command)) {
             const hit = classifyRm(segment, cwd, scratch);
             // classifyRm derives ids (rm-recursive, rm-rf, rm-recursive-dangerous-target); they are exemptable like any built-in.
@@ -1568,7 +1675,7 @@ export function describeAction(tool, input, cwd) {
         summary.command = redact(truncate(view.command, COMMAND_LIMIT));
         // Jev sees the full text; this names the part of it that is written or printed rather than executed.
         if (stripDataText(view.command).stripped)
-            summary.dataText = "heredoc bodies and quoted arguments of echo/printf/grep/git commit in this command are text that is written, printed, searched, or recorded, not executed";
+            summary.dataText = "heredoc bodies and quoted arguments of echo/printf/grep, git commit messages, and gh message flags in this command are text that is written, printed, searched, or recorded, not executed";
         const written = tool === "bash" ? mergeWrites(shellWrites(view.command, { home: homedir() }).writes) : [];
         if (written.length) {
             summary.writes = written.map(write => `${write.append ? "appends to" : "writes"} ${displayPath(write.path, cwd).path}`);
@@ -2044,11 +2151,21 @@ export async function evaluateAction(action, options) {
     // object to on recorded sessions, a plan-drifting file edit far less so.
     const visibleDrift = judgment.intentMismatch !== undefined && (judgment.visible ?? 0) >= VISIBLE_THRESHOLD && judgment.intentMismatch >= config.visibleMismatch;
     const mismatch = judgment.intentMismatch !== undefined && canChange && (judgment.intentMismatch >= config.intentMismatch || visibleDrift);
+    // The steer reaches the agent after the call ran (275 of 275 recorded steers), and a strict course change followed 8% of
+    // them. A call with no visible effect keeps the finding in the trace only; a visible one still tells the agent. Visible
+    // is either rule: the code's (commit, push, merge, tag, reset, pull request, release, publish) or the judge's `visible`
+    // score at 0.8, which also covers an install, a launched program, or a message sent from a script.
+    const visibleEffect = (view?.shell === true && isVisibleCommand(view.command)) || (judgment.visible ?? 0) >= VISIBLE_THRESHOLD;
+    const intentTraceOnly = mismatch && (config.intentTraceOnly === "all" || (config.intentTraceOnly === "invisible" && !visibleEffect));
+    let intentTraceOnlyReasonIndex;
     if (mismatch) {
         level = higher(level, "warn");
+        if (intentTraceOnly)
+            intentTraceOnlyReasonIndex = reasons.length;
+        const traceOnly = intentTraceOnly ? `; trace-only${config.intentTraceOnly === "invisible" ? ", no visible effect" : ""}` : "";
         reasons.push(visibleDrift && judgment.intentMismatch < config.intentMismatch
-            ? `intent mismatch ${percent(judgment.intentMismatch)} on a visible action (${percent(judgment.visible)}; a commit, push, merge, publish, or launch the plan did not describe)`
-            : `intent mismatch ${percent(judgment.intentMismatch)} (the call differs from the agent's stated plan)`);
+            ? `intent mismatch ${percent(judgment.intentMismatch)} on a visible action (${percent(judgment.visible)}; a commit, push, merge, publish, or launch the plan did not describe${traceOnly})`
+            : `intent mismatch ${percent(judgment.intentMismatch)} (the call differs from the agent's stated plan${traceOnly})`);
     }
     // Poor calibration makes this diagnostic-only unless the user opts into steers.
     let shouldProceedSteer = false;
@@ -2066,6 +2183,10 @@ export async function evaluateAction(action, options) {
     const verdict = withPlan({ level, source: "typesafe", summary, patterns, reasons, judgment });
     if (mismatch)
         verdict.intentMismatch = true;
+    if (intentTraceOnlyReasonIndex !== undefined) {
+        verdict.intentTraceOnly = true;
+        verdict.intentTraceOnlyReasonIndex = intentTraceOnlyReasonIndex;
+    }
     if (offTaskSteer)
         verdict.offTaskSteer = true;
     if (offTaskTraceOnly)
@@ -2150,6 +2271,8 @@ export async function evaluateAction(action, options) {
             verdict.offTaskTraceOnlyReasonIndex++;
         if (verdict.shouldProceedTraceOnlyReasonIndex !== undefined)
             verdict.shouldProceedTraceOnlyReasonIndex++;
+        if (verdict.intentTraceOnlyReasonIndex !== undefined)
+            verdict.intentTraceOnlyReasonIndex++;
     }
     return verdict;
 }

package/dist/index.d.ts

@@ -6,7 +6,9 @@ export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.j
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
 export type { ProseSymptom, ProseVerdict, ProseOptions } from "./prose.js";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
-export type { Attempt, StuckJudgment, StuckVerdict, StuckOptions } from "./stuck.js";
+export type { Attempt, AttemptChange, StuckJudgment, StuckVerdict, StuckOptions, StuckRequestOptions, StuckRequestState } from "./stuck.js";
+export { parseFailure, failureSignature, normaliseFailureText, editPairs, lineDelta, editDiff, buildStuckEvidence, EVIDENCE_LIMIT } from "./evidence.js";
+export type { ParsedFailure, EditDiff, EvidenceRun, EvidenceEdit, EvidenceDigest, StuckEvidence } from "./evidence.js";
 export { classifyToolResult, recordOutcome, recordUi, isUiFile, isVisualCheck, emptyEvidence, freshChecks, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions } from "./done.js";
 export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice, outputKey, duplicateNote } from "./output.js";
@@ -36,8 +38,14 @@ export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, run
 export type { WidgetConfig, WidgetPlacement, WidgetBarMode, Tokens } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";
-export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, formatRuleSetDetails, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
 export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef, RulesTier, RulesSourceConfig } from "./rules.js";
+export { checkRules, formatRulesCheck, formatRuleCheck, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
+export type { RuleCheck, RuleCheckView, RuleJudgeability, RulesCheckOptions, RulesCheckRequest, RulesCheckResult, RulesCheckSource } from "./rules-lint.js";
+export { rulesLogPath, readRulesLog, trimRecords, RuleClearTracker, RulesLog, RULES_LOG_MAX_RECORDS } from "./rules-log.js";
+export type { RuleRecord, RuleObservation, RulesLogOptions } from "./rules-log.js";
+export { buildRulesReport, formatRulesReport, compareRows, REPORT_DEFAULT_DAYS, NEVER_FIRES_MIN, FIRES_RATE_MAX, UNDECIDED_LOW, UNDECIDED_HIGH } from "./rules-report.js";
+export type { RuleFlag, RuleReportRow, RulesReport } from "./rules-report.js";
 export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
 export type { ResolvedRulesFile } from "./rules-file.js";
 export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";

package/dist/index.js

@@ -3,6 +3,7 @@ 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";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
+export { parseFailure, failureSignature, normaliseFailureText, editPairs, lineDelta, editDiff, buildStuckEvidence, EVIDENCE_LIMIT } from "./evidence.js";
 export { classifyToolResult, recordOutcome, recordUi, isUiFile, isVisualCheck, emptyEvidence, freshChecks, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice, outputKey, duplicateNote } from "./output.js";
 export { formatExcerpt, formatQuestion } from "./excerpt.js";
@@ -18,7 +19,10 @@ export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProj
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, SENTENCE_TEMPLATES, pickSentenceTemplate, TOKEN_NAMES } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
-export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, formatRuleSetDetails, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { checkRules, formatRulesCheck, formatRuleCheck, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
+export { rulesLogPath, readRulesLog, trimRecords, RuleClearTracker, RulesLog, RULES_LOG_MAX_RECORDS } from "./rules-log.js";
+export { buildRulesReport, formatRulesReport, compareRows, REPORT_DEFAULT_DAYS, NEVER_FIRES_MIN, FIRES_RATE_MAX, UNDECIDED_LOW, UNDECIDED_HIGH } from "./rules-report.js";
 export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
 export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";
 export { initSchema, recordHold, recordOutcome as recordHoldOutcome, querySmartHistory, calculateSmartConfidence, shouldSkipHold, analyzeThresholds, analyzePatterns, generateRecommendations, analyzeSteerEffectivenessReport } from "./learning.js";

package/dist/loops.d.ts

@@ -0,0 +1,64 @@
+export declare const LOOP_CHARS = 160;
+/** Open loops shown in the appendix, the reminder, and the resume message. */
+export declare const LOOPS_SHOWN = 8;
+export declare const LOOPS_CHARS = 600;
+export type LoopAction = "add" | "done" | "drop" | "list";
+export declare const LOOP_ACTIONS: readonly LoopAction[];
+export interface Loop {
+    id: number;
+    /** Redacted, at most LOOP_CHARS characters. */
+    text: string;
+    /** The condition that makes it due, such as "after CI passes"; redacted. */
+    when?: string;
+    status: "open" | "done" | "dropped";
+    /** Why a dropped loop was dropped; redacted. */
+    reason?: string;
+    at: number;
+    closedAt?: number;
+}
+export interface LoopStore {
+    next: number;
+    loops: Loop[];
+}
+export declare function emptyLoopStore(): LoopStore;
+/**
+ * One file per session, in a folder per project: the working directory's hash keeps another project's session with the
+ * same id apart, and the id keeps another session of this project apart.
+ */
+export declare function loopsPath(cwd: string, session: string): string;
+/** A missing file is an empty store; an unreadable or malformed one throws, so a write never replaces loops it could not read. */
+export declare function readLoops(path: string): Promise<LoopStore>;
+/** Written whole to a temporary file and renamed, so a crash never leaves half a file. */
+export declare function writeLoops(path: string, store: LoopStore): Promise<void>;
+/** One change to the store: the reply for the agent, and the new store when it changed. */
+export type LoopChange = (store: LoopStore) => {
+    reply: string;
+    store?: LoopStore;
+};
+/**
+ * Reads, applies, and writes one change under the file's queue, so two `warden_loops` calls in one process run in turn
+ * and cannot lose each other's update.
+ */
+export declare function updateLoops(path: string, change: LoopChange): Promise<string>;
+export declare const openLoops: (store: LoopStore) => Loop[];
+/**
+ * The open loops, oldest first, at most LOOPS_SHOWN lines and LOOPS_CHARS characters; whole lines only, with a count of
+ * the ones left out. Empty when none is open.
+ */
+export declare function formatOpenLoops(loops: readonly Loop[]): string;
+/** The open list as it stands: a reminder already sent for the same list is not sent again. */
+export declare function loopsFingerprint(loops: readonly Loop[]): string;
+export interface LoopInput {
+    action?: unknown;
+    text?: unknown;
+    when?: unknown;
+    id?: unknown;
+    reason?: unknown;
+}
+/** Applies one `warden_loops` call. `store` is undefined when nothing changes. */
+export declare function applyLoopAction(store: LoopStore, input: LoopInput, now: number): {
+    reply: string;
+    store?: LoopStore;
+};
+/** `/warden loops`: every loop of the session, open first, with how each closed. */
+export declare function formatLoopsForUser(store: LoopStore): string;

package/dist/loops.js

@@ -0,0 +1,147 @@
+/**
+ * Open loops: things the agent promised to do later in this session ("after CI passes, bump the version"). The agent
+ * adds and closes them with the `warden_loops` tool; warden keeps them in one small file per session under its data
+ * folder, so they survive compaction and resume, and shows the open ones in the compaction appendix, in one reminder at
+ * the end of a run, and in one message on resume. Code only, no Jev request. A loop never reaches another session or
+ * another project: the file is keyed by both.
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { serialize, writeFileAtomic } from "./atomic.js";
+import { userConfigPath } from "./config.js";
+import { redact } from "./redact.js";
+export const LOOP_CHARS = 160;
+/** Open loops shown in the appendix, the reminder, and the resume message. */
+export const LOOPS_SHOWN = 8;
+export const LOOPS_CHARS = 600;
+/** A session with this many open loops is tracking tasks, not promises; one more is refused until some close. */
+const MAX_OPEN = 30;
+export const LOOP_ACTIONS = ["add", "done", "drop", "list"];
+export function emptyLoopStore() {
+    return { next: 1, loops: [] };
+}
+/**
+ * One file per session, in a folder per project: the working directory's hash keeps another project's session with the
+ * same id apart, and the id keeps another session of this project apart.
+ */
+export function loopsPath(cwd, session) {
+    const project = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+    return join(dirname(userConfigPath()), "loops", project, `${session.replace(/[^\w.-]/g, "_")}.json`);
+}
+const isLoop = (value) => {
+    const loop = value;
+    return typeof loop === "object" && loop !== null && typeof loop.id === "number" && typeof loop.text === "string" && typeof loop.at === "number"
+        && (loop.status === "open" || loop.status === "done" || loop.status === "dropped");
+};
+/** A missing file is an empty store; an unreadable or malformed one throws, so a write never replaces loops it could not read. */
+export async function readLoops(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyLoopStore();
+        throw error;
+    }
+    const raw = JSON.parse(text);
+    if (typeof raw !== "object" || raw === null || !Array.isArray(raw.loops))
+        throw new Error("the loops file has no loops list");
+    const loops = raw.loops.filter(isLoop);
+    const next = typeof raw.next === "number" ? raw.next : Math.max(0, ...loops.map(loop => loop.id)) + 1;
+    return { next, loops };
+}
+/** Written whole to a temporary file and renamed, so a crash never leaves half a file. */
+export async function writeLoops(path, store) {
+    await writeFileAtomic(path, `${JSON.stringify(store, null, 2)}\n`);
+}
+/**
+ * Reads, applies, and writes one change under the file's queue, so two `warden_loops` calls in one process run in turn
+ * and cannot lose each other's update.
+ */
+export async function updateLoops(path, change) {
+    return serialize(path, async () => {
+        const result = change(await readLoops(path));
+        if (result.store)
+            await writeLoops(path, result.store);
+        return result.reply;
+    });
+}
+export const openLoops = (store) => store.loops.filter(loop => loop.status === "open");
+const oneLine = (text) => redact(text.replace(/\s+/g, " ").trim());
+const loopLine = (loop) => `- #${loop.id} ${loop.text}${loop.when ? ` (when: ${loop.when})` : ""}`;
+/**
+ * The open loops, oldest first, at most LOOPS_SHOWN lines and LOOPS_CHARS characters; whole lines only, with a count of
+ * the ones left out. Empty when none is open.
+ */
+export function formatOpenLoops(loops) {
+    const open = loops.filter(loop => loop.status === "open");
+    const lines = [];
+    let length = 0;
+    for (const loop of open.slice(0, LOOPS_SHOWN)) {
+        const line = loopLine(loop);
+        // Room for the count line of the ones left out.
+        if (length + line.length + 1 > LOOPS_CHARS - 40)
+            break;
+        lines.push(line);
+        length += line.length + 1;
+    }
+    if (lines.length < open.length)
+        lines.push(`- … and ${open.length - lines.length} more (warden_loops list)`);
+    return lines.join("\n");
+}
+/** The open list as it stands: a reminder already sent for the same list is not sent again. */
+export function loopsFingerprint(loops) {
+    return loops.filter(loop => loop.status === "open").map(loop => `${loop.id}:${loop.text}:${loop.when ?? ""}`).join("\n");
+}
+/** Applies one `warden_loops` call. `store` is undefined when nothing changes. */
+export function applyLoopAction(store, input, now) {
+    const action = typeof input.action === "string" ? input.action : "";
+    if (action === "list") {
+        const open = openLoops(store);
+        const closed = store.loops.length - open.length;
+        return { reply: open.length ? `Open loops:\n${formatOpenLoops(open)}${closed ? `\n(${closed} closed)` : ""}` : `No open loops${closed ? ` (${closed} closed)` : ""}.` };
+    }
+    if (action === "add") {
+        const text = typeof input.text === "string" ? oneLine(input.text) : "";
+        const when = typeof input.when === "string" ? oneLine(input.when) : "";
+        if (!text)
+            return { reply: "not added: give the loop's text" };
+        if (text.length > LOOP_CHARS || when.length > LOOP_CHARS)
+            return { reply: `not added: the text and the condition are at most ${LOOP_CHARS} characters each` };
+        if (openLoops(store).length >= MAX_OPEN)
+            return { reply: `not added: ${MAX_OPEN} loops are open; close the finished ones with done or drop first` };
+        const loop = { id: store.next, text, ...(when ? { when } : {}), status: "open", at: now };
+        return { reply: `added #${loop.id}: ${text}${when ? ` (when: ${when})` : ""}`, store: { next: store.next + 1, loops: [...store.loops, loop] } };
+    }
+    if (action === "done" || action === "drop") {
+        const id = typeof input.id === "number" ? input.id : typeof input.id === "string" ? Number(input.id.replace(/^#/, "")) : NaN;
+        const loop = store.loops.find(entry => entry.id === id);
+        if (!loop)
+            return { reply: `no loop #${Number.isFinite(id) ? id : "?"} in this session` };
+        if (loop.status !== "open")
+            return { reply: `#${loop.id} is already ${loop.status}` };
+        const reason = typeof input.reason === "string" ? oneLine(input.reason).slice(0, LOOP_CHARS) : "";
+        if (action === "drop" && !reason)
+            return { reply: `not dropped: say why #${loop.id} is no longer needed` };
+        const closed = { ...loop, status: action === "done" ? "done" : "dropped", ...(reason && action === "drop" ? { reason } : {}), closedAt: now };
+        return {
+            reply: `${action === "done" ? "done" : "dropped"} #${loop.id}: ${loop.text}`,
+            store: { ...store, loops: store.loops.map(entry => entry.id === loop.id ? closed : entry) },
+        };
+    }
+    return { reply: `unknown action; use one of ${LOOP_ACTIONS.join(", ")}` };
+}
+/** `/warden loops`: every loop of the session, open first, with how each closed. */
+export function formatLoopsForUser(store) {
+    if (!store.loops.length)
+        return "No loops in this session. The agent adds one with warden_loops when it promises to do something later.";
+    const open = openLoops(store);
+    const closed = store.loops.filter(loop => loop.status !== "open");
+    return [
+        open.length ? `Open loops (${open.length}):` : "No open loops.",
+        ...open.map(loopLine),
+        ...(closed.length ? [`Closed (${closed.length}):`, ...closed.map(loop => `${loopLine(loop)}: ${loop.status}${loop.reason ? `, ${loop.reason}` : ""}`)] : []),
+    ].join("\n");
+}