pi-warden 0.40.2 → 0.47.0

package/dist/judge-cooldown.js

@@ -0,0 +1,92 @@
+/** Classify a judge error into a safe category (spec §6: never exception bodies). */
+export function classifyJudgeError(err) {
+    if (err && typeof err === "object" && "code" in err) {
+        const code = err.code;
+        if (code === "timeout")
+            return "timeout";
+        if (code === "http" || code === "connection" || code === "response")
+            return "network";
+        if (code === "configuration" || code === "validation")
+            return "configuration";
+        if (code === "budget" || code === "aborted")
+            return "other";
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/timeout|timed out/i.test(msg))
+        return "timeout";
+    if (/auth|key|credential|401|403/i.test(msg))
+        return "auth";
+    if (/network|fetch|connect|ECONNREFUSED|ENOTFOUND/i.test(msg))
+        return "network";
+    return "other";
+}
+/**
+ * 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 function cooldownFailureKind(err, signal) {
+    const code = err && typeof err === "object" && "code" in err ? err.code : undefined;
+    if (code === "budget" || code === "validation")
+        return undefined;
+    if (code === "aborted")
+        return signal?.reason?.name === "TimeoutError" ? "timeout" : undefined;
+    const status = err && typeof err === "object" && "status" in err ? err.status : undefined;
+    if (status === 401 || status === 403)
+        return "auth";
+    return classifyJudgeError(err);
+}
+/**
+ * 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 class JudgeCooldown {
+    now;
+    failures = 0;
+    until = 0;
+    /** A window has started and no judgment has succeeded since, so the user was told and not yet told it recovered. */
+    cooled = false;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** True while judgments are paused. */
+    active() {
+        return this.now() < this.until;
+    }
+    failure(kind, settings) {
+        // A request that was already in flight when the window opened adds nothing the user has not been told.
+        if (this.active())
+            return undefined;
+        // The probe after a window failed too: the judge is still down, which the open notice already says.
+        if (this.cooled) {
+            this.open(settings);
+            return undefined;
+        }
+        this.failures++;
+        const persistent = kind === "auth" || kind === "configuration";
+        if (!persistent && this.failures < settings.failuresBeforeCooldown)
+            return undefined;
+        this.open(settings);
+        return { type: "started", kind, ms: settings.cooldownMs };
+    }
+    success() {
+        this.failures = 0;
+        if (!this.cooled)
+            return undefined;
+        this.cooled = false;
+        return { type: "recovered" };
+    }
+    reset() {
+        this.failures = 0;
+        this.until = 0;
+        this.cooled = false;
+    }
+    open(settings) {
+        this.failures = 0;
+        this.cooled = true;
+        this.until = this.now() + settings.cooldownMs;
+    }
+}

package/dist/panel.d.ts

@@ -56,11 +56,14 @@ export interface PanelController {
 }
 /**
  * Open the trace as a right-hand sidebar. Pi's public UI API offers floating overlays but no side dock that narrows the
- * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused.
+ * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused. `built()` says
+ * whether the host ever asked for the component: a host without a terminal UI (RPC mode) settles `closed` without asking.
  */
 export declare function openTracePanel(ui: PanelUi, trace: Trace, options?: {
     width?: string | number;
-}): PanelController;
+}): PanelController & {
+    built(): boolean;
+};
 export declare class ConfigPanel implements Component {
     private readonly config;
     private readonly theme;

package/dist/panel.js

@@ -151,12 +151,15 @@ function theme_fg(theme, color, text) {
 }
 /**
  * Open the trace as a right-hand sidebar. Pi's public UI API offers floating overlays but no side dock that narrows the
- * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused.
+ * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused. `built()` says
+ * whether the host ever asked for the component: a host without a terminal UI (RPC mode) settles `closed` without asking.
  */
 export function openTracePanel(ui, trace, options = {}) {
     let close = () => { };
     let unfocus = () => { };
+    let built = false;
     const closed = ui.custom((tui, theme, _keybindings, done) => {
+        built = true;
         close = () => done();
         const panel = new TracePanel(trace, theme, { close, unfocus: () => unfocus() }, () => tui.requestRender());
         const rows = tui.terminal?.rows;
@@ -168,7 +171,7 @@ export function openTracePanel(ui, trace, options = {}) {
         overlayOptions: { anchor: "right-center", width: options.width ?? "40%", minWidth: 44, maxHeight: "100%", nonCapturing: true },
         onHandle: (handle) => { unfocus = () => handle.unfocus(); },
     });
-    return { closed, close: () => close() };
+    return { closed, close: () => close(), built: () => built };
 }
 function flattenConfig(obj, prefix = "") {
     const entries = [];

package/dist/redact.d.ts

@@ -1,8 +1,10 @@
 export declare function redact(text: string): string;
 /**
- * A value shape, not a name: at least 8 characters, not a type word or placeholder, not a reference to somewhere the
- * value lives (`$VAR`, `${...}`, `process.env.X`, `<your key>`, `[redacted]`, `***`), not an all-caps identifier, and
- * with the mixture of character classes that keys have (digits with letters, or both cases with punctuation).
+ * A value shape, not a name: at least 8 characters, not a type word or placeholder (`<redacted>`, `***`, `REDACTED`,
+ * `xxxx`), not a plain number (`19415506`, `19,415,506`), not an identifier or expression in code (`findSecrets(text)`,
+ * `output.secretIds`, a type name), not a reference to somewhere the value lives (`$VAR`, `${...}`, `process.env.X`,
+ * `<your key>`, `[redacted]`), not an all-caps identifier, and with the mixture of character classes that keys have
+ * (digits with letters, or both cases with punctuation).
  */
 export declare function looksLikeSecretValue(value: string): boolean;
 /**

package/dist/redact.js

@@ -51,12 +51,17 @@ const ASSIGNMENTS = [
 /** Words that sit after `secret:` in code and docs. */
 const NOT_VALUES = new Set(["boolean", "string", "number", "object", "any", "unknown", "null", "undefined", "true", "false", "none", "nil", "void", "never", "required", "optional", "redacted", "hidden", "masked", "omitted", "unset", "missing", "empty", "changeme", "example", "placeholder", "password", "secret", "token", "value", "text", "str", "int", "bytes", "yes", "no", "on", "off", "auto", "default", "bearer", "basic", "env", "process", "os", "environ", "config", "settings", "input", "output", "prompt"]);
 /**
- * A value shape, not a name: at least 8 characters, not a type word or placeholder, not a reference to somewhere the
- * value lives (`$VAR`, `${...}`, `process.env.X`, `<your key>`, `[redacted]`, `***`), not an all-caps identifier, and
- * with the mixture of character classes that keys have (digits with letters, or both cases with punctuation).
+ * A value shape, not a name: at least 8 characters, not a type word or placeholder (`<redacted>`, `***`, `REDACTED`,
+ * `xxxx`), not a plain number (`19415506`, `19,415,506`), not an identifier or expression in code (`findSecrets(text)`,
+ * `output.secretIds`, a type name), not a reference to somewhere the value lives (`$VAR`, `${...}`, `process.env.X`,
+ * `<your key>`, `[redacted]`), not an all-caps identifier, and with the mixture of character classes that keys have
+ * (digits with letters, or both cases with punctuation).
  */
 export function looksLikeSecretValue(value) {
-    const text = value.trim().replace(/^[`"'([{<]+|[`"')\]}>.,;]+$/g, "");
+    const raw = value.trim();
+    if (/^<[^<>]*>$/.test(raw))
+        return false; // an angle-bracket placeholder: <redacted>, <...>, <sk-live-token>
+    const text = raw.replace(/^[`"'([{<]+|[`"')\]}>.,;]+$/g, "");
     if (text.length < 8 || text.length > 512)
         return false;
     const lower = text.toLowerCase();
@@ -64,8 +69,16 @@ export function looksLikeSecretValue(value) {
         return false;
     if (/^[$%<\[{*]|^(?:process|os|env|settings|config|secrets?|vault|keychain|import\.meta)\.|^\$?\{|^\*+$|^x+$|^(?:your|my|the|a|an)[-_ ]/i.test(text))
         return false;
+    if (/^\d+(?:[,_]\d+)*$/.test(text))
+        return false; // a plain number, separators allowed: 19415506, 797330_123, 19,415,506
+    if (/^(?:[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+|[a-z]+(?:[A-Z][\w$]*)+|[A-Z][a-z]+(?:[A-Z][\w$]*)*)\s*[(\[]/.test(text))
+        return false; // a call or index expression: a bracket straight after a code identifier or property path (`findSecrets(text)`, `secretValues.filter((id`); a bracket inside mixed characters is a password, not code
+    if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(text))
+        return false; // a property access: output.secretIds
     if (/^[A-Z][A-Z0-9_]{6,}$/.test(text))
         return false; // an environment variable name
+    if (/^[A-Z][a-z]+(?:[A-Z][a-z0-9]*)*$/.test(text) && !/\d{3,}/.test(text))
+        return false; // a class or type name in code
     if (/^[a-z]+(?:[A-Z][a-z0-9]*)+$/.test(text) && !/\d{3,}/.test(text))
         return false; // a camelCase identifier
     if (/^[a-z]+(?:[_-][a-z]+)+$/.test(text))

package/dist/rules.d.ts

@@ -145,6 +145,8 @@ export interface RulesOptions {
     timeoutMs: number;
     signal?: AbortSignal | undefined;
 }
+/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd`. Returns false when git is unavailable or the path cannot be checked. */
+export declare function gitIgnored(projectRel: string, cwd: string): boolean;
 /** Why a write or edit is not judged against the rules: nothing to judge, no rules, or a path the config keeps out. */
 export declare function skipReason(target: RulesTarget | undefined, set: RuleSet | undefined, config: RulesConfig): string | undefined;
 export declare function evaluateRules(tool: string, input: Record<string, unknown>, options: RulesOptions): Promise<RulesVerdict>;

package/dist/rules.js

@@ -1,4 +1,5 @@
 import { readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { ask, choice } from "pi-typesafe";
 import { redact } from "./redact.js";
@@ -372,6 +373,16 @@ export function buildRulesRequest(target, set) {
         applicable,
     };
 }
+/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd`. Returns false when git is unavailable or the path cannot be checked. */
+export function gitIgnored(projectRel, cwd) {
+    try {
+        execFileSync("git", ["check-ignore", "-q", projectRel], { cwd, timeout: 2000, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Why a write or edit is not judged against the rules: nothing to judge, no rules, or a path the config keeps out. */
 export function skipReason(target, set, config) {
     if (!target)
@@ -487,6 +498,18 @@ export class RulesGuard {
     noted = new Set();
     inspect(call, siblings, options) {
         const set = this.store.load(options.cwd, options.config);
+        // A write or edit to a gitignored path is not project code; the rules in pi-warden.md do not apply.
+        // Only check when a rule set exists — no set means no rules file and skipReason already handles that.
+        if (set) {
+            const rawPath = typeof call.input.path === "string" ? call.input.path : undefined;
+            if (rawPath) {
+                const rel = projectPath(rawPath, options.cwd);
+                if (rel && gitIgnored(rel, options.cwd)) {
+                    const verdict = { source: "skipped", tool: call.tool, path: rel, sources: set.sources, asked: 0, aggregate: false, findings: [], skippedReason: "gitignored by the project" };
+                    return Promise.resolve(verdict);
+                }
+            }
+        }
         const judgeCall = (tool, input) => evaluateRules(tool, input, { ...options, set });
         if (options.judge) {
             for (const sibling of siblings) {

package/dist/shape.d.ts

@@ -13,3 +13,49 @@ export interface ShapeResult {
  */
 export declare function completeConfig(loaded: Partial<WardenConfig> | undefined): ShapeResult;
 export declare function shapeWarning(missing: readonly string[], loadedSchema: number | undefined): string;
+/**
+ * The task spine the action guard and the conscience both judge with: the thread's first user turn (`goal`),
+ * the latest user turn (`task`), and up to four earlier user turns (`history`, newest first). A follow-up
+ * like "now the tests" is judged against the goal it belongs to, not on its words alone.
+ */
+export interface TaskSpine {
+    /** The first user turn of the thread, earlier than `task`; the goal the latest turn belongs to. */
+    goal: string;
+    /** The latest user turn, raw and unclipped: the request state already carries it as `task` (redacted, bounded) and approval reads only that field. */
+    task: string;
+    /** Earlier user turns between goal and task, newest first; empty when the goal is the turn just before task. */
+    history: string[];
+}
+/** Whole-spine character budget. `task_history` is clipped first, then `goal`; `task` is never clipped here. */
+export declare const SPINE_CAP = 1200;
+/** Earlier turns the spine keeps, between goal and task. */
+export declare const SPINE_HISTORY_TURNS = 4;
+/** Per-field limits the request paths apply to a spine they receive, whoever built it. */
+export declare const SPINE_GOAL_LIMIT = 1200;
+export declare const SPINE_HISTORY_LIMIT = 750;
+/** The slice of a Pi session entry the spine reads; structural, so shape.ts needs no host types. */
+export interface BranchMessageEntry {
+    type: string;
+    message?: {
+        role: string;
+        content?: string | ReadonlyArray<{
+            type: string;
+            text?: string;
+        }>;
+    } | undefined;
+}
+/** User-turn texts in branch order: text parts joined with newlines, non-text parts skipped, blank turns dropped. */
+export declare function userTurnTexts(entries: readonly (BranchMessageEntry | undefined | null)[] | undefined): string[];
+/**
+ * The task spine over the branch entries: goal, task, and up to four earlier turns, newest first. Pure.
+ * The whole spine fits SPINE_CAP characters — `history` is clipped first (newest turns keep their text,
+ * the oldest give way), then `goal`; `task` is never clipped, because approval is judged from the request's
+ * `task` field and a clipped task would judge a request the user did not write. `goal` and `history` are
+ * redacted here; `task` stays raw because both request paths redact and bound it themselves. `latest`
+ * supplies the latest turn when the branch does not carry it yet (the conscience passes the prompt it is
+ * about to send); when the branch already carries it, that copy is dropped from `history`. No user turn at
+ * all, or the latest turn is the first: no spine, so the budget is not spent on a copy of `task`. Only
+ * `message` entries count, so a compaction entry and its summary never become the goal; Pi's getBranch
+ * still returns the entries a compaction summarized. Scope context only — the spine never authorizes an action.
+ */
+export declare function taskSpine(entries: readonly (BranchMessageEntry | undefined | null)[] | undefined, latest?: string): TaskSpine | undefined;

package/dist/shape.js

@@ -1,5 +1,6 @@
 import { isMode } from "./config.js";
 import { resolveBackend } from "./backend.js";
+import { redact } from "./redact.js";
 import { DEFAULT_TEMPLATES } from "./widget.js";
 /** The config layout this extension build expects; compared with the loaded config module's CONFIG_SCHEMA. */
 export const EXPECTED_SCHEMA = 7;
@@ -36,9 +37,11 @@ export function completeConfig(loaded) {
         slop: section("slop", { ...off, threshold: 1, prose: proseOff() }),
         security: section("security", { ...off, threshold: 1 }),
         rules: section("rules", { ...off, threshold: 1, files: [], fallback: false, maxChars: 500, exclude: [], skip: [], sensitivePaths: {} }),
-        context: section("context", { ...off, tailMinChars: 1, confidence: 1, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1, compactAppendix: true }),
+        context: section("context", { ...off, tailMinChars: 1, confidence: 1, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1, compactAppendix: true, largeOutput: { ...off, threshold: 1 } }),
         runaway: section("runaway", { ...off, repeats: Number.MAX_SAFE_INTEGER, thinkingRepeats: Number.MAX_SAFE_INTEGER, minChars: Number.MAX_SAFE_INTEGER, recover: false }),
         notify: section("notify", { ...off, cooldownMs: 0, command: [] }),
+        // A stale config module leaves the judge trusted: never pausing is today's behaviour, not a new failure mode.
+        judge: section("judge", { failuresBeforeCooldown: Number.MAX_SAFE_INTEGER, cooldownMs: 0 }),
         subagent: section("subagent", { ...off, wake: false, threshold: 1, cooldownMs: 0 }),
         widget: section("widget", { ...off, placement: "aboveEditor", barMode: "live", shortcut: "", panelWidth: "40%", action: "", stuck: "", done: "", prose: "", security: "", context: "", runaway: "", rules: "", subagent: "" }),
         learning: section("learning", { adaptiveThresholds: true, patternAnalysis: true, minHoldsForAdaptive: 20, adaptationRate: 0.1, retentionDays: 365 }),
@@ -64,6 +67,9 @@ export function completeConfig(loaded) {
         missing.push("context.saver");
         config.context = { ...config.context, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1 };
     }
+    // The large-output question was added inside the context section later than the section itself; an older config module leaves it undefined and the question is not asked.
+    if (typeof config.context.largeOutput !== "object" || config.context.largeOutput === null)
+        config.context = { ...config.context, largeOutput: { ...off, threshold: 1 } };
     if (typeof config.widget.panelWidth !== "string" && typeof config.widget.panelWidth !== "number")
         config.widget = { ...config.widget, panelWidth: "40%" };
     // The feedback log flag was added inside the action section later than the section itself; an older config module leaves it undefined and the log stays on.
@@ -107,3 +113,72 @@ export function completeConfig(loaded) {
 export function shapeWarning(missing, loadedSchema) {
     return `warden: config sections ${missing.join(", ")} are missing (config module schema ${loadedSchema ?? "pre-3"}, extension expects ${EXPECTED_SCHEMA}); those guards are off. This happens when pi-warden was updated while Pi was running: restart Pi (a /reload is not enough).`;
 }
+/** Whole-spine character budget. `task_history` is clipped first, then `goal`; `task` is never clipped here. */
+export const SPINE_CAP = 1200;
+/** Earlier turns the spine keeps, between goal and task. */
+export const SPINE_HISTORY_TURNS = 4;
+/** Per-field limits the request paths apply to a spine they receive, whoever built it. */
+export const SPINE_GOAL_LIMIT = 1200;
+export const SPINE_HISTORY_LIMIT = 750;
+/** User-turn texts in branch order: text parts joined with newlines, non-text parts skipped, blank turns dropped. */
+export function userTurnTexts(entries) {
+    const turns = [];
+    for (const entry of entries ?? []) {
+        if (!entry || entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (!message || message.role !== "user")
+            continue;
+        const content = message.content;
+        if (content === undefined)
+            continue;
+        const text = typeof content === "string"
+            ? content
+            : content.filter(part => part.type === "text").map(part => part.text ?? "").join("\n");
+        if (text.trim())
+            turns.push(text.trim());
+    }
+    return turns;
+}
+/**
+ * The task spine over the branch entries: goal, task, and up to four earlier turns, newest first. Pure.
+ * The whole spine fits SPINE_CAP characters — `history` is clipped first (newest turns keep their text,
+ * the oldest give way), then `goal`; `task` is never clipped, because approval is judged from the request's
+ * `task` field and a clipped task would judge a request the user did not write. `goal` and `history` are
+ * redacted here; `task` stays raw because both request paths redact and bound it themselves. `latest`
+ * supplies the latest turn when the branch does not carry it yet (the conscience passes the prompt it is
+ * about to send); when the branch already carries it, that copy is dropped from `history`. No user turn at
+ * all, or the latest turn is the first: no spine, so the budget is not spent on a copy of `task`. Only
+ * `message` entries count, so a compaction entry and its summary never become the goal; Pi's getBranch
+ * still returns the entries a compaction summarized. Scope context only — the spine never authorizes an action.
+ */
+export function taskSpine(entries, latest) {
+    const turns = userTurnTexts(entries);
+    const supplied = latest?.trim();
+    const last = turns.at(-1);
+    const task = supplied || last || "";
+    if (!task)
+        return undefined;
+    const earlier = supplied
+        ? (last === task ? turns.slice(0, -1) : turns)
+        : turns.slice(0, -1);
+    if (!earlier.length)
+        return undefined;
+    let goal = redact(earlier[0]);
+    let history = earlier.slice(1).slice(-SPINE_HISTORY_TURNS).reverse().map(redact);
+    let budget = SPINE_CAP - goal.length - task.length;
+    const kept = [];
+    for (const turn of history) { // newest first: the oldest give way first
+        if (budget <= 0)
+            break;
+        const take = turn.slice(0, Math.max(0, budget));
+        kept.push(take);
+        budget -= take.length;
+    }
+    history = kept;
+    const historyLength = history.reduce((n, turn) => n + turn.length, 0);
+    if (goal.length + task.length + historyLength > SPINE_CAP) {
+        goal = goal.slice(0, Math.max(0, SPINE_CAP - task.length - historyLength));
+    }
+    return { goal, task, history };
+}

package/dist/trace-file.d.ts

@@ -0,0 +1,50 @@
+import type { JudgmentsOffReason } from "./backend.js";
+import type { TraceEvent } from "./trace.js";
+/**
+ * Trace file for hosts that run Pi without the terminal UI. The widget and the sidebar never reach an RPC host, so with
+ * `PI_WARDEN_TRACE_DIR` set the trace is also appended to `<dir>/<session>.jsonl`, one JSON object per line:
+ *
+ * - `{"v":1,"kind":"session","sessionId","cwd","wardenVersion","mode","judgments","at"}` when the file is opened for a
+ *   session; `judgments` is `"on"` or `"off:<reason>"`, reason one of `no_consent`, `no_key`, `key_rejected`, `budget`;
+ * - `{"v":1,"kind":"judgments","judgments","at"}` when a guard finds the judgment state changed from the last line;
+ * - `{"v":1,"kind":"entry","id","at","guard","line","details","tokens"?}` for every trace entry, as the trace stores it;
+ * - `{"v":1,"kind":"amend","id","line","at"}` for an outcome line added to an entry still in the trace.
+ *
+ * The file keeps every entry; the in-memory limit does not apply. A write error is reported once and ends the file for
+ * the session; it never reaches a guard or a tool call.
+ */
+export declare const TRACE_DIR_ENV = "PI_WARDEN_TRACE_DIR";
+/** The trace directory, or undefined when the feature is off. A relative path is not resolved against a cwd that moves. */
+export declare function traceDir(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function traceFilePath(dir: string, sessionId: string): string;
+export interface TraceFileSession {
+    sessionId: string;
+    cwd: string;
+    mode: string;
+    /** Whether Jev judgments can run as the session opens. */
+    judgments: JudgmentsState;
+}
+/** The trace file's judgment state: `"on"`, or `"off:<reason>"`. */
+export type JudgmentsState = "on" | `off:${JudgmentsOffReason}`;
+export declare function judgmentsState(reason: JudgmentsOffReason | undefined): JudgmentsState;
+/** Appends the session's trace events in trace order, one write at a time. */
+export declare class TraceFile {
+    readonly path: string;
+    private readonly onFailure;
+    private queue;
+    private base;
+    private sequence;
+    private readonly ids;
+    private stopped;
+    private judgmentsNow;
+    constructor(path: string, dir: string, session: TraceFileSession, onFailure: (message: string) => void);
+    /** Trace listener. The record is built now, so a later amend does not show up in the entry line. */
+    readonly listener: (event: TraceEvent) => void;
+    /** Adds a `judgments` line when the state differs from the last one written. */
+    judgments(state: JudgmentsState): void;
+    /** Resolves when every event so far is on disk or the file has stopped. */
+    flush(): Promise<void>;
+    private append;
+    private guarded;
+    private run;
+}

package/dist/trace-file.js

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, sep } from "node:path";
+import { sessionFileId } from "./holds.js";
+import { redact } from "./redact.js";
+/**
+ * Trace file for hosts that run Pi without the terminal UI. The widget and the sidebar never reach an RPC host, so with
+ * `PI_WARDEN_TRACE_DIR` set the trace is also appended to `<dir>/<session>.jsonl`, one JSON object per line:
+ *
+ * - `{"v":1,"kind":"session","sessionId","cwd","wardenVersion","mode","judgments","at"}` when the file is opened for a
+ *   session; `judgments` is `"on"` or `"off:<reason>"`, reason one of `no_consent`, `no_key`, `key_rejected`, `budget`;
+ * - `{"v":1,"kind":"judgments","judgments","at"}` when a guard finds the judgment state changed from the last line;
+ * - `{"v":1,"kind":"entry","id","at","guard","line","details","tokens"?}` for every trace entry, as the trace stores it;
+ * - `{"v":1,"kind":"amend","id","line","at"}` for an outcome line added to an entry still in the trace.
+ *
+ * The file keeps every entry; the in-memory limit does not apply. A write error is reported once and ends the file for
+ * the session; it never reaches a guard or a tool call.
+ */
+export const TRACE_DIR_ENV = "PI_WARDEN_TRACE_DIR";
+/** The trace directory, or undefined when the feature is off. A relative path is not resolved against a cwd that moves. */
+export function traceDir(env = process.env) {
+    const dir = env[TRACE_DIR_ENV];
+    return dir && isAbsolute(dir) ? dir : undefined;
+}
+export function traceFilePath(dir, sessionId) {
+    return join(dir, `${sessionFileId(sessionId)}.jsonl`);
+}
+let version;
+function wardenVersion() {
+    if (version !== undefined)
+        return version;
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        version = typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch (error) {
+        console.warn("pi-warden: package version unreadable for the trace file:", error);
+        version = "unknown";
+    }
+    return version;
+}
+/** The home directory as `~`, the way action summaries show a path outside the project. */
+function shownPath(path) {
+    const home = homedir();
+    return redact(path === home || path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path);
+}
+/** Highest entry id already in the file, so a reload or a resumed session keeps ids unique in the session's file. */
+async function lastEntryId(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    let last = 0;
+    for (const match of text.matchAll(/^\{"v":1,"kind":"entry","id":(\d+)/gm))
+        last = Math.max(last, Number(match[1]));
+    return last;
+}
+export function judgmentsState(reason) {
+    return reason === undefined ? "on" : `off:${reason}`;
+}
+/** Appends the session's trace events in trace order, one write at a time. */
+export class TraceFile {
+    path;
+    onFailure;
+    queue = Promise.resolve();
+    base = 0;
+    sequence = 0;
+    ids = new WeakMap();
+    stopped = false;
+    judgmentsNow;
+    constructor(path, dir, session, onFailure) {
+        this.path = path;
+        this.onFailure = onFailure;
+        const header = { v: 1, kind: "session", sessionId: session.sessionId, cwd: shownPath(session.cwd), wardenVersion: wardenVersion(), mode: session.mode, judgments: session.judgments, at: new Date().toISOString() };
+        this.judgmentsNow = session.judgments;
+        this.queue = this.guarded(async () => {
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            this.base = await lastEntryId(path);
+            await appendFile(path, `${JSON.stringify(header)}\n`, { mode: 0o600 });
+        });
+    }
+    /** Trace listener. The record is built now, so a later amend does not show up in the entry line. */
+    listener = (event) => {
+        if (this.stopped || event.kind === "clear")
+            return;
+        const at = new Date().toISOString();
+        if (event.kind === "push") {
+            const local = ++this.sequence;
+            this.ids.set(event.entry, local);
+            const { at: stamp, guard, line, details, tokens } = event.entry;
+            const fields = { at: new Date(stamp).toISOString(), guard, line, details: [...details], ...(tokens ? { tokens: { ...tokens } } : {}) };
+            this.append(() => ({ v: 1, kind: "entry", id: this.base + local, ...fields }));
+            return;
+        }
+        const local = this.ids.get(event.entry);
+        if (local === undefined)
+            return;
+        const { line } = event;
+        this.append(() => ({ v: 1, kind: "amend", id: this.base + local, line, at }));
+    };
+    /** Adds a `judgments` line when the state differs from the last one written. */
+    judgments(state) {
+        if (this.stopped || state === this.judgmentsNow)
+            return;
+        this.judgmentsNow = state;
+        const at = new Date().toISOString();
+        this.append(() => ({ v: 1, kind: "judgments", judgments: state, at }));
+    }
+    /** Resolves when every event so far is on disk or the file has stopped. */
+    flush() {
+        return this.queue;
+    }
+    append(record) {
+        this.queue = this.guarded(() => appendFile(this.path, `${JSON.stringify(record())}\n`, { mode: 0o600 }));
+    }
+    guarded(write) {
+        return this.queue.then(() => this.run(write));
+    }
+    async run(write) {
+        if (this.stopped)
+            return;
+        try {
+            await write();
+        }
+        catch (error) {
+            this.stopped = true;
+            try {
+                this.onFailure(`warden: trace file ${this.path} could not be written (${error instanceof Error ? error.message : String(error)}); no more trace lines go to it this session.`);
+            }
+            catch (reportError) {
+                console.warn("pi-warden: trace file failure could not be reported:", reportError);
+            }
+        }
+    }
+}

package/dist/trace.d.ts

@@ -15,6 +15,17 @@ export interface TraceEntry {
     /** Raw tokens for re-rendering in live mode with sentence templates. */
     tokens?: Record<string, string | undefined> | undefined;
 }
+/** What changed, for a listener that keeps its own record (the trace file); the widget and the panel re-read entries(). */
+export type TraceEvent = {
+    kind: "push";
+    entry: TraceEntry;
+} | {
+    kind: "amend";
+    entry: TraceEntry;
+    line: string;
+} | {
+    kind: "clear";
+};
 /** Session memory of guard decisions; the widget shows the latest line per guard, the panel shows the history. */
 export declare class Trace {
     private readonly limit;
@@ -26,7 +37,7 @@ export declare class Trace {
     amend(entry: TraceEntry, line: string): boolean;
     entries(): readonly TraceEntry[];
     clear(): void;
-    subscribe(listener: () => void): () => void;
+    subscribe(listener: (event: TraceEvent) => void): () => void;
 }
 export declare function actionDetails(verdict: Verdict, extra?: {
     mode?: string;

package/dist/trace.js

@@ -11,7 +11,7 @@ export class Trace {
         if (this.items.length > this.limit)
             this.items.splice(0, this.items.length - this.limit);
         for (const listener of this.listeners)
-            listener();
+            listener({ kind: "push", entry });
     }
     /** Appends a detail line to an entry that is still in the trace, for an outcome that lands after the event. */
     amend(entry, line) {
@@ -19,7 +19,7 @@ export class Trace {
             return false;
         entry.details.push(line);
         for (const listener of this.listeners)
-            listener();
+            listener({ kind: "amend", entry, line });
         return true;
     }
     entries() {
@@ -28,7 +28,7 @@ export class Trace {
     clear() {
         this.items.length = 0;
         for (const listener of this.listeners)
-            listener();
+            listener({ kind: "clear" });
     }
     subscribe(listener) {
         this.listeners.add(listener);