pi-warden 0.64.1 → 0.71.0

package/dist/adaptive.js

@@ -0,0 +1,274 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeFileAtomicSync } from "./atomic.js";
+import { userConfigPath } from "./config.js";
+export const STEER_KINDS = [
+    "intent-mismatch", "off-task", "should-proceed", "warn-headless", "large-output", "slop", "rules", "sensitive-path",
+    "security-write", "stuck", "repeat", "done", "prose", "conscience", "loops", "runaway", "subagent",
+    "hold", "confirm", "deny", "masking", "credential-notice",
+];
+/**
+ * Never trace-only, whatever a model does with them: holds, confirm and deny verdicts, security masking, the credential
+ * notice on masked output, and the done-check. Runaway recovery and subagent wakes start a turn of their own; muting
+ * them would change what the run does, not only what the agent is told.
+ */
+export const NEVER_MUTED = new Set([
+    "hold", "confirm", "deny", "masking", "credential-notice", "done", "runaway", "subagent",
+]);
+/** Where the counts live: next to the user config, in pi-warden's data folder. */
+export function steerStatsPath() {
+    return process.env.PI_WARDEN_STEER_STATS ?? join(dirname(userConfigPath()), "steer-stats.json");
+}
+export const DEFAULT_STEERS = { adaptive: true, minSteers: 30, minFollowed: 0.2, maxDisputed: 0.4, recheckEvery: 30, probeEvery: 5 };
+const zero = () => ({ sent: 0, followed: 0, disputed: 0 });
+const fresh = () => ({ ...zero(), muted: false, asked: 0, probe: zero() });
+/** Kinds whose "followed" can be read from the next calls or text; the rest are judged by disputes alone. */
+const FOLLOW_MEASURED = new Set([
+    "intent-mismatch", "off-task", "should-proceed", "warn-headless", "large-output", "slop", "rules", "security-write",
+    "stuck", "repeat", "done", "conscience", "loops",
+]);
+/** True when the counts put the pair under the follow floor or over the dispute ceiling. */
+export function failing(kind, counts, config) {
+    if (!counts.sent)
+        return false;
+    return (FOLLOW_MEASURED.has(kind) && counts.followed / counts.sent < config.minFollowed) || counts.disputed / counts.sent > config.maxDisputed;
+}
+/** The counts per (model, kind) pair, read once and written after every change. */
+export class SteerStats {
+    path;
+    data;
+    constructor(path = steerStatsPath()) {
+        this.path = path;
+    }
+    load() {
+        if (this.data)
+            return this.data;
+        try {
+            const raw = JSON.parse(readFileSync(this.path, "utf8"));
+            this.data = raw?.version === 1 && typeof raw.models === "object" && raw.models ? raw : { version: 1, models: {} };
+        }
+        catch {
+            this.data = { version: 1, models: {} };
+        }
+        return this.data;
+    }
+    save() {
+        try {
+            writeFileAtomicSync(this.path, `${JSON.stringify(this.data)}\n`);
+        }
+        catch (error) {
+            console.warn("pi-warden: steer stats write failed:", error instanceof Error ? error.message : String(error));
+        }
+    }
+    pair(model, kind) {
+        return this.load().models[model]?.[kind];
+    }
+    ensure(model, kind) {
+        const models = this.load().models;
+        const kinds = models[model] ??= {};
+        return kinds[kind] ??= fresh();
+    }
+    /**
+     * Called before a steer of this kind goes out. A trace-only pair still sends the first of every `probeEvery` steers;
+     * after `recheckEvery` steers the probes decide: rates within the thresholds end trace-only, and the probe counts
+     * become the pair's new counts, so a fresh `minSteers` must pass before it can be muted again.
+     */
+    request(model, kind, config) {
+        if (!config.adaptive || NEVER_MUTED.has(kind))
+            return "send";
+        const pair = this.pair(model, kind);
+        if (!pair?.muted)
+            return "send";
+        const probe = pair.asked % Math.max(1, config.probeEvery) === 0;
+        pair.asked++;
+        if (pair.asked >= config.recheckEvery) {
+            if (pair.probe.sent > 0 && !failing(kind, pair.probe, config))
+                Object.assign(pair, { ...pair.probe, muted: false, asked: 0, probe: zero() });
+            else
+                Object.assign(pair, { asked: 0, probe: zero() });
+        }
+        this.save();
+        return probe ? "probe" : "trace-only";
+    }
+    /**
+     * The outcome of one sent steer. Crossing the thresholds at `minSteers` or later makes the pair trace-only. Kinds in
+     * NEVER_MUTED are counted, for the status, and never muted.
+     */
+    observe(model, kind, outcome, config) {
+        if (!config.adaptive)
+            return;
+        const pair = this.ensure(model, kind);
+        const add = (counts) => {
+            counts.sent++;
+            if (outcome.followed)
+                counts.followed++;
+            if (outcome.disputed)
+                counts.disputed++;
+        };
+        add(pair);
+        if (pair.muted)
+            add(pair.probe);
+        else if (!NEVER_MUTED.has(kind) && pair.sent >= config.minSteers && failing(kind, pair, config))
+            Object.assign(pair, { muted: true, asked: 0, probe: zero() });
+        this.save();
+    }
+    /** Drops the pair's counts; its steers are sent again. True when there was something to reset. */
+    unmute(model, kind) {
+        const kinds = this.load().models[model];
+        if (!kinds?.[kind])
+            return false;
+        delete kinds[kind];
+        if (!Object.keys(kinds).length)
+            delete this.load().models[model];
+        this.save();
+        return true;
+    }
+    /** Every trace-only pair, per model. */
+    muted() {
+        const out = [];
+        for (const [model, kinds] of Object.entries(this.load().models)) {
+            for (const [kind, pair] of Object.entries(kinds)) {
+                if (pair.muted)
+                    out.push({ model, kind, sent: pair.sent, followed: pair.followed, disputed: pair.disputed });
+            }
+        }
+        return out.sort((a, b) => a.model.localeCompare(b.model) || a.kind.localeCompare(b.kind));
+    }
+    /** Models with a pair of this kind, for `/warden unmute` without a model. */
+    modelsWith(kind) {
+        return Object.entries(this.load().models).filter(([, kinds]) => kinds[kind]).map(([model]) => model);
+    }
+}
+const percent = (part, whole) => `${whole ? Math.round((part / whole) * 100) : 0}%`;
+export function formatMuted(pairs, config) {
+    if (!config.adaptive)
+        return "Adaptive steers: off.";
+    if (!pairs.length)
+        return "Adaptive steers: no steer kind is trace-only for any model.";
+    const byModel = new Map();
+    for (const pair of pairs)
+        byModel.set(pair.model, [...(byModel.get(pair.model) ?? []), pair]);
+    const models = [...byModel].map(([model, list]) => `${model}: ${list.map(pair => `${pair.kind} (${pair.sent} steers, ${percent(pair.followed, pair.sent)} followed, ${percent(pair.disputed, pair.sent)} disputed)`).join(", ")}`);
+    return `Adaptive steers, trace-only per model: ${models.join("; ")}. /warden unmute <kind> resets a pair.`;
+}
+/** Agent replies that argue with a note instead of acting on it. The same pattern the field replays used. */
+export const DISPUTE = /false positive|false alarm|no (real )?(credentials|secrets)|not (a |real )?(secret|credential|token)s?|(only|just) (placeholder|fixture|test|dummy|fake)|as (I )?(said|planned|stated)|matches (what I said|the plan)|this is expected|warden (is wrong|misfired|misread)|misfire|spurious|harmless|benign|nothing sensitive|not sensitive|was intended|intended/i;
+const CHECK = /\b(test|tests|vitest|jest|pytest|build|lint|tsc|check|make|cargo|go test|flutter (test|analyze)|npm run|eslint|typecheck)\b/i;
+const UNVERIFIED = /not (yet )?(verified|tested)|unverified|did not run|didn't run/i;
+const REPLAN = /\b(instead|re-?plan(ned|ning)?|ask(ing)? (you|the user|first|before)|should I|do you want)\b/i;
+const commandText = (input) => typeof input.command === "string" ? input.command : typeof input.path === "string" ? input.path : JSON.stringify(input);
+/**
+ * Whether the next assistant messages (at most two) changed course after a steer of this kind, and whether they
+ * disputed it. A port of the heuristic the field replays used; it is a proxy and does not prove the note caused the change.
+ */
+export function steerOutcome(kind, subject, views) {
+    const text = views.map(view => view.text).join("\n");
+    const calls = views.flatMap(view => view.calls);
+    const disputed = DISPUTE.test(text);
+    let followed = false;
+    switch (kind) {
+        case "done":
+            followed = calls.some(call => call.name === "bash" && CHECK.test(commandText(call.input))) || UNVERIFIED.test(text);
+            break;
+        case "rules":
+        case "slop":
+        case "security-write": {
+            const path = subject.path;
+            followed = !!path && calls.some(call => /edit|write/i.test(call.name) ? commandText(call.input).endsWith(path) : call.name === "bash" && commandText(call.input).includes(path));
+            break;
+        }
+        case "stuck":
+        case "repeat": {
+            const next = calls[0];
+            followed = !!next && (!subject.call || next.name !== subject.call.name || commandText(next.input) !== commandText(subject.call.input));
+            break;
+        }
+        case "intent-mismatch":
+        case "off-task":
+        case "should-proceed":
+        case "warn-headless":
+        case "large-output":
+            followed = (!calls.length && /\?\s*$/.test(views[0]?.text ?? "")) || REPLAN.test(text);
+            break;
+        case "conscience": {
+            const target = subject.capability;
+            followed = !!target && calls.some(call => target.kind === "tool" ? call.name === target.id || call.name.endsWith(target.id) : commandText(call.input).includes(`/${target.id}/`));
+            break;
+        }
+        case "loops":
+            followed = calls.some(call => call.name === "warden_loops");
+            break;
+        default:
+            followed = false;
+    }
+    return { followed, disputed };
+}
+/**
+ * Sent steers waiting for the agent's next two messages. A steer queued for the next turn waits past the next user
+ * message; any other steer that meets a user message first is settled on what it saw, or dropped when it saw nothing.
+ */
+export class SteerWatch {
+    pending = [];
+    add(model, kinds, subject = {}, options = {}) {
+        if (!kinds.length)
+            return;
+        this.pending.push({ model, kinds: [...kinds], subject, views: [], waitUser: options.nextTurn === true });
+        if (this.pending.length > 50)
+            this.pending.shift();
+    }
+    /** Feeds one assistant message; returns the steers it settled. */
+    assistant(view) {
+        const settled = [];
+        const keep = [];
+        for (const item of this.pending) {
+            if (item.waitUser) {
+                keep.push(item);
+                continue;
+            }
+            item.views.push(view);
+            const outcomes = item.kinds.map(kind => ({ kind, ...steerOutcome(kind, item.subject, item.views) }));
+            if (item.views.length >= 2 || outcomes.every(outcome => outcome.followed || outcome.disputed)) {
+                for (const outcome of outcomes)
+                    settled.push({ model: item.model, ...outcome });
+            }
+            else
+                keep.push(item);
+        }
+        this.pending = keep;
+        return settled;
+    }
+    /** A user message arrived. */
+    user() {
+        const settled = [];
+        const keep = [];
+        for (const item of this.pending) {
+            if (item.waitUser) {
+                item.waitUser = false;
+                keep.push(item);
+                continue;
+            }
+            if (item.views.length)
+                for (const kind of item.kinds)
+                    settled.push({ model: item.model, kind, ...steerOutcome(kind, item.subject, item.views) });
+        }
+        this.pending = keep;
+        return settled;
+    }
+    clear() { this.pending = []; }
+}
+/** The text and tool calls of an assistant message as Pi stores it. */
+export function assistantView(content) {
+    if (typeof content === "string")
+        return { text: content, calls: [] };
+    if (!Array.isArray(content))
+        return { text: "", calls: [] };
+    const text = [];
+    const calls = [];
+    for (const part of content) {
+        if (part?.type === "text" && typeof part.text === "string")
+            text.push(part.text);
+        else if (part?.type === "toolCall" && typeof part.name === "string")
+            calls.push({ name: part.name, input: (part.arguments && typeof part.arguments === "object" ? part.arguments : {}) });
+    }
+    return { text: text.join("\n"), calls };
+}

package/dist/atomic.d.ts

@@ -0,0 +1,10 @@
+/** Writes `text` to `path` through a temporary file and a rename, so a crash or a reader never sees half a file. */
+export declare function writeFileAtomic(path: string, text: string): Promise<void>;
+/** `writeFileAtomic` for the synchronous stores, which cannot interleave with each other inside one process. */
+export declare function writeFileAtomicSync(path: string, text: string): void;
+/**
+ * Runs `task` after every earlier task for `key`, so the read-modify-write sequences that share a store file run one
+ * after another instead of all reading the same old store and then writing over each other's change. A task's rejection
+ * reaches its own caller and does not stop the queue.
+ */
+export declare function serialize<T>(key: string, task: () => Promise<T> | T): Promise<T>;

package/dist/atomic.js

@@ -0,0 +1,51 @@
+/**
+ * Whole-file writes and per-file queues for pi-warden's small JSON stores. Two operations on one store in one process
+ * share no temporary name and do not interleave: every write goes to a temporary file that belongs to this process and
+ * this write, then a rename puts it in place, and every read-modify-write of one file runs through a queue keyed by that
+ * path. Cross-process locking is out of scope: a second process writing the same store can still lose this process's
+ * update, and nothing here stops it.
+ */
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+let writes = 0;
+/** The temporary file one write lands in: the pid keeps two processes apart, the counter two writes within one process. */
+function temporaryPath(path) {
+    writes += 1;
+    return `${path}.${process.pid}.${writes}.tmp`;
+}
+/** Writes `text` to `path` through a temporary file and a rename, so a crash or a reader never sees half a file. */
+export async function writeFileAtomic(path, text) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = temporaryPath(path);
+    await writeFile(temporary, text, { mode: 0o600 });
+    // The mode applies only when the temporary file is created; force it so a leftover file cannot change the store's permissions.
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+}
+/** `writeFileAtomic` for the synchronous stores, which cannot interleave with each other inside one process. */
+export function writeFileAtomicSync(path, text) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = temporaryPath(path);
+    writeFileSync(temporary, text, { mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+}
+/** The tail of each path's queue: a task starts once the previous task for the same path has settled. */
+const queues = new Map();
+/**
+ * Runs `task` after every earlier task for `key`, so the read-modify-write sequences that share a store file run one
+ * after another instead of all reading the same old store and then writing over each other's change. A task's rejection
+ * reaches its own caller and does not stop the queue.
+ */
+export function serialize(key, task) {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const run = previous.then(task);
+    const settled = run.then(() => undefined, () => undefined);
+    queues.set(key, settled);
+    void settled.then(() => {
+        if (queues.get(key) === settled)
+            queues.delete(key);
+    });
+    return run;
+}

package/dist/config.d.ts

@@ -131,6 +131,8 @@ export interface StuckGuardConfig {
     nudge: boolean;
     /** Steer on the 2nd identical call when nothing changed between and it failed the same way or re-read the same output. Code only. */
     repeatSteer: boolean;
+    /** Send the judge a compact structured `evidence` section: the parsed failure per run, the edit diffs, and a digest. */
+    evidence: boolean;
     /** Maximum characters of the unified line diff in a stuck-loop diff note. */
     diffLimit: number;
     /** Characters of the current output tail shown after the diff in a stuck-loop diff note. */
@@ -190,6 +192,8 @@ export interface RulesConfig {
     enabled: boolean;
     /** P(violation) at or above this names the rule to the agent. */
     threshold: number;
+    /** A score from here up to the rule's cutoff becomes a soft "please double-check" steer; `0` turns the tier off. */
+    softThreshold: number;
     /** Project-relative Markdown rule files, used when the root pi-warden.md is absent. All are sent in one request. */
     files: string[];
     /** With no rules file, README.md, CLAUDE.md, or AGENTS.md (first found) is judged as one document. */
@@ -270,12 +274,43 @@ export interface SubagentConfig {
 export type RecallTool = "auto" | "rg" | "ag" | "ugrep" | "git-grep" | "grep" | "select-string" | "findstr" | "none";
 export declare function isRecallTool(value: unknown): value is RecallTool;
 export type WardenMode = "steer" | "confirm" | "advise";
+export interface WasteConfig {
+    /** Master switch for the call-waste notes and the session tip. */
+    enabled: boolean;
+    /** Append the session tip to the prompt once per session. */
+    tip: boolean;
+    /** Tool calls between two notes from the same detector. */
+    every: number;
+    /** Note on repeated poll calls (`sleep`). */
+    sleep: boolean;
+    /** Note on adjacent range reads of one file. */
+    paging: boolean;
+    /** Note on repeated searches of one file with an overlapping pattern. */
+    search: boolean;
+    /** Note on a filtered check re-run. */
+    recheck: boolean;
+}
 export interface PrefsConfig {
     /** Read this project's earlier session files for preferences the user repeated (`/warden prefs`). Local, code only. */
     enabled: boolean;
     /** At session start, send the standing preferences that pass every injection rule to the agent as one context message. */
     inject: boolean;
 }
+/** Per-model steer adaptation: a steer kind a model rarely follows or often disputes becomes trace-only for it. */
+export interface SteersConfig {
+    /** Make a steer kind trace-only for a model that rarely follows or often disputes it. */
+    adaptive: boolean;
+    /** Steers observed for a (model, kind) pair before it can become trace-only. */
+    minSteers: number;
+    /** Trace-only when the followed share is under this. Kinds with no follow measure are judged by disputes alone. */
+    minFollowed: number;
+    /** Trace-only when the disputed share is over this. */
+    maxDisputed: number;
+    /** A trace-only pair is re-checked after this many further steers. */
+    recheckEvery: number;
+    /** While trace-only, 1 in this many steers is still sent, so the re-check has fresh data. */
+    probeEvery: number;
+}
 export interface LearningConfig {
     /** Enable adaptive thresholds based on learning data. */
     adaptiveThresholds: boolean;
@@ -366,16 +401,20 @@ export interface WardenConfig {
      * steer costs at least one LLM turn, and a closing run that collects six notices collects six restatements of the final
      * status. 0 disables the budget. Critical guards (stuck, done, runaway, subagent wake) always deliver. */
     steerBudget: number;
+    /** Per-model steer adaptation. */
+    steers: SteersConfig;
     /** Learning and adaptation settings. */
     learning: LearningConfig;
     /** Broad-consideration coach: recommends or loads skills and tools before the agent acts. */
     conscience: ConscienceConfig;
     /** Standing preferences: corrections the user repeated in earlier sessions of this project. */
     prefs: PrefsConfig;
+    /** Call-waste notes: advisory sentences attached to the tool result that triggers them. */
+    waste: WasteConfig;
 }
 export declare const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export declare const CONFIG_SCHEMA = 8;
+export declare const CONFIG_SCHEMA = 10;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */

package/dist/config.js

@@ -1,6 +1,7 @@
-import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { writeFileAtomicSync } from "./atomic.js";
 import { resolveBackend } from "./backend.js";
 import { COMMAND_TOOLS } from "./tools.js";
 import { defaultWidgetConfig } from "./widget.js";
@@ -23,7 +24,7 @@ export function isRecallTool(value) {
 }
 export const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export const CONFIG_SCHEMA = 8;
+export const CONFIG_SCHEMA = 10;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -53,11 +54,11 @@ export function defaultConfig() {
             escalationThreshold: 0.85,
             floor: "evidence",
         },
-        stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true, repeatSteer: true, diffLimit: 3000, tailLimit: 1000 },
+        stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true, repeatSteer: true, evidence: true, diffLimit: 3000, tailLimit: 1000 },
         done: { enabled: true, claimsDone: 0.7, nudge: true, uiProof: true, uiFiles: [...DEFAULT_UI_FILES], visualTools: defaultVisualTools() },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7, maskOutput: true },
-        rules: { enabled: true, threshold: 0.7, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
+        rules: { enabled: true, threshold: 0.7, softThreshold: 0, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
         context: { enabled: true, tailMinChars: 12000, confidence: 0.8, duplicateMinChars: 2000, recallTool: "auto", formatConfidence: 0.7, compactAppendix: true, dedupeRuns: true, dedupeMessages: false, largeOutput: { enabled: true, threshold: 0.85 } },
         runaway: { enabled: true, repeats: 4, thinkingRepeats: 10, minChars: 400, recover: true },
         notify: { enabled: false, cooldownMs: 10000, command: [] },
@@ -67,6 +68,7 @@ export function defaultConfig() {
         steerVisible: false,
         notices: false,
         steerBudget: 3,
+        steers: { adaptive: true, minSteers: 30, minFollowed: 0.2, maxDisputed: 0.4, recheckEvery: 30, probeEvery: 5 },
         learning: { adaptiveThresholds: true, patternAnalysis: true, minHoldsForAdaptive: 20, adaptationRate: 0.1, retentionDays: 365 },
         conscience: {
             enabled: false,
@@ -84,6 +86,7 @@ export function defaultConfig() {
             loadThreshold: 1.0,
         },
         prefs: { enabled: true, inject: true },
+        waste: { enabled: true, tip: false, every: 20, sleep: true, paging: true, search: true, recheck: true },
     };
 }
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
@@ -317,6 +320,7 @@ function applyStuck(base, raw) {
         churnThreshold: Math.min(window, positiveInteger(raw.churnThreshold, base.churnThreshold)),
         nudge: boolean(raw.nudge, base.nudge),
         repeatSteer: boolean(raw.repeatSteer, base.repeatSteer),
+        evidence: boolean(raw.evidence, base.evidence),
         diffLimit: positiveInteger(raw.diffLimit, base.diffLimit),
         tailLimit: positiveInteger(raw.tailLimit, base.tailLimit),
     };
@@ -402,6 +406,7 @@ function applyRules(base, raw) {
     return {
         enabled: boolean(raw.enabled, base.enabled),
         threshold: probability(raw.threshold, base.threshold),
+        softThreshold: probability(raw.softThreshold, base.softThreshold),
         files: globList(raw.files, base.files),
         fallback: boolean(raw.fallback, base.fallback),
         maxChars: Math.max(500, positiveInteger(raw.maxChars, base.maxChars)),
@@ -442,6 +447,7 @@ function applyShared(base, raw) {
 }
 function applyGuards(base, raw, timeoutMs, source) {
     return {
+        waste: applyWaste(base.waste, raw.waste),
         rules: applyRules(base.rules, raw.rules),
         runaway: applyRunaway(base.runaway, raw.runaway),
         subagent: applySubagent(base.subagent, raw.subagent),
@@ -491,16 +497,42 @@ export function applyUserOverrides(base, raw) {
         steerVisible: boolean(raw.steerVisible, base.steerVisible),
         notices: boolean(raw.notices, base.notices),
         steerBudget: typeof raw.steerBudget === "number" && Number.isInteger(raw.steerBudget) && raw.steerBudget >= 0 ? raw.steerBudget : base.steerBudget,
+        steers: applySteers(base.steers, raw.steers),
         learning: applyLearning(base.learning, raw.learning),
         conscience: applyConscience(base.conscience, raw.conscience),
         prefs: applyPrefs(base.prefs, raw.prefs),
     };
 }
+function applyWaste(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        tip: boolean(raw.tip, base.tip),
+        every: Math.max(2, positiveInteger(raw.every, base.every)),
+        sleep: boolean(raw.sleep, base.sleep),
+        paging: boolean(raw.paging, base.paging),
+        search: boolean(raw.search, base.search),
+        recheck: boolean(raw.recheck, base.recheck),
+    };
+}
 function applyPrefs(base, raw) {
     if (!isObject(raw))
         return base;
     return { enabled: boolean(raw.enabled, base.enabled), inject: boolean(raw.inject, base.inject) };
 }
+function applySteers(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        adaptive: boolean(raw.adaptive, base.adaptive),
+        minSteers: positiveInteger(raw.minSteers, base.minSteers),
+        minFollowed: probability(raw.minFollowed, base.minFollowed),
+        maxDisputed: probability(raw.maxDisputed, base.maxDisputed),
+        recheckEvery: positiveInteger(raw.recheckEvery, base.recheckEvery),
+        probeEvery: positiveInteger(raw.probeEvery, base.probeEvery),
+    };
+}
 function applyLearning(base, raw) {
     if (!isObject(raw))
         return base;
@@ -557,11 +589,7 @@ export function readUserConfig() {
 }
 export function writeUserConfig(raw) {
     const path = userConfigPath();
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${process.pid}.tmp`;
-    writeFileSync(temporary, `${JSON.stringify(raw, null, 2)}\n`, { mode: 0o600, flag: "w" });
-    chmodSync(temporary, 0o600);
-    renameSync(temporary, path);
+    writeFileAtomicSync(path, `${JSON.stringify(raw, null, 2)}\n`);
     return path;
 }
 /** Persists one top-level user setting without disturbing the rest of the file. */

package/dist/evidence.d.ts

@@ -0,0 +1,93 @@
+import type { Attempt } from "./stuck.js";
+/** Byte cap for the whole `evidence` object; over it, the oldest runs go first, then the oldest edits. */
+export declare const EVIDENCE_LIMIT = 4096;
+/** A failed or check output parsed into failing tests, error lines, a location, a summary and an exit code. */
+export type ParsedFailure = {
+    format: string;
+    failing: string[];
+    failing_more?: number;
+    errors: string[];
+    location?: string;
+    summary?: string;
+    exit?: number;
+};
+/** Parses a failed or check output into failing tests, error lines, a location, a summary and an exit code. */
+export declare function parseFailure(text: string): ParsedFailure;
+/**
+ * Normalises what changes between identical runs: durations, clock times and dates, addresses, long numbers, thread
+ * ids, temp paths, and line:column positions. Other digits stay, so "expected 3" and "expected 4" still differ.
+ */
+export declare function normaliseFailureText(value: string | undefined): string;
+/**
+ * Order-free signature of a failure: which tests failed and with which errors, both normalised. Pass counts are left
+ * out, so a run narrowed by a flag (`-x`, a test filter) still matches the full run that failed the same way.
+ */
+export declare function failureSignature(parsed: ParsedFailure, raw?: string): string;
+/** The edit pairs of an `edit` input, as `[oldText, newText]`: the `edits` array, or one top-level pair. */
+export declare function editPairs(input: Record<string, unknown>): Array<[string, string]>;
+/** Removed and added lines of one edit, as a multiset difference, so unchanged context lines drop out. */
+export declare function lineDelta(oldText: string, newText: string): {
+    removed: string[];
+    added: string[];
+};
+/** What an `edit` or `write` changed: the path, the line counts, and a diff capped at `DIFF_CAP` characters. */
+export type EditDiff = {
+    path: string;
+    added: number;
+    removed: number;
+    removedLines: string[];
+    addedLines: string[];
+    diff: string;
+};
+/**
+ * The change an `edit` or `write` made. Every string is as the agent wrote it: the caller redacts what leaves the
+ * machine. The diff is the whole added and removed text, not a line-by-line patch, because the judge compares one
+ * change against the next.
+ */
+export declare function editDiff(tool: string, input: Record<string, unknown>): EditDiff;
+/** One run in the evidence: a failed call, or a call that ran a test, build or lint command and passed. */
+export type EvidenceRun = {
+    n: number;
+    outcome: "failed" | "ok";
+    parser?: string;
+    failing_tests?: string[];
+    failing_tests_more?: number;
+    errors?: string[];
+    location?: string;
+    summary?: string;
+    output_tail?: string;
+    output_head_tail?: string;
+    /** The run number of the earlier run whose failure matches, after normalising times, temp paths and line numbers. */
+    same_failure_as_run?: number | null;
+    exit_code?: number;
+};
+/** One `edit`/`write` call in the evidence. */
+export type EvidenceEdit = {
+    n: number;
+    path: string;
+    added_lines: number;
+    removed_lines: number;
+    diff: string;
+};
+/** The counts a judge can weigh without reading every run. */
+export type EvidenceDigest = {
+    failed_runs: number;
+    distinct_failures: number;
+    /** Runs whose command repeats an earlier run's command, whatever the outcome. */
+    same_command_runs: number[];
+    latest_failure_seen_before: boolean;
+    edits_between_failed_runs: number;
+    information_calls_between_failed_runs: number;
+};
+export type StuckEvidence = {
+    runs: EvidenceRun[];
+    edits: EvidenceEdit[];
+    digest: EvidenceDigest;
+};
+/**
+ * Builds the evidence for one stuck window: a run per failed call and per passing check command, an edit per
+ * `edit`/`write`, and a digest. The oldest runs are dropped first when the whole object is over `EVIDENCE_LIMIT`
+ * bytes, then the oldest edits; the digest is then recomputed over what is left, and a run that pointed at a dropped
+ * run points at nothing. The floor is one run plus the digest, which is far under the cap.
+ */
+export declare function buildStuckEvidence(attempts: readonly Attempt[], limit?: number): StuckEvidence;