privateer-agent 0.15.4 → 0.15.6

package/README.md

@@ -505,6 +505,17 @@ privateer -p --approve-in-app --approval-timeout 300 "make a 6s intro clip"
 `--max-spend` is checked before each call against the server's estimate for that call
 (`media_capabilities` shows the same prices). A call that can't be priced is refused.
 
+Piped input is waited for, however long the pipe stays silent
+(`pytest | privateer -p "why did this fail?"`). If a program starts Privateer with stdin
+open and never writes to it, a run that already has a prompt continues after 3 seconds.
+Scripts with nothing to send can skip the wait with `< /dev/null`.
+
+Before a one-shot run that used tools ends, Privateer asks the model to check its result
+against what actually happened and to open its final message with anything it invented,
+could not verify or lost. That is one extra model call; `PRIVATEER_FINAL_AUDIT=0` turns it
+off. If the provider goes silent mid-run, the request is resent up to twice before the run
+stops with an error.
+
 ## Hand off sensitive work
 
 Your coding agent's context goes to its provider. When a task touches files that shouldn't

package/bin/boot-bundle.d.mts

@@ -0,0 +1,2 @@
+export const BOOT_DIR: string;
+export function bootCliPath(repo: string, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string | null;

package/bin/boot-bundle.mjs

@@ -0,0 +1,44 @@
+// Which Pi entry should this launch run: the compiled boot build, or the source tree?
+// scripts/build-boot.mjs makes the build; docs/startup-performance.md explains why.
+//
+// The answer is the build only when it is certainly the same code as the source next
+// to it. Every other case returns null and the launcher runs from source, which is
+// slower and always correct, so nothing here is ever a reason a launch fails.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const BOOT_DIR = "dist-boot";
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Absolute path of the build's entry script, or null to run from source. */
+export function bootCliPath(repo, env = process.env) {
+  if (env.PRIVATEER_NO_BOOT_BUNDLE === "1") return null;
+
+  // A checkout is where source gets edited, and the build wouldn't see those edits.
+  if (fs.existsSync(path.join(repo, ".git")) && env.PRIVATEER_BOOT_BUNDLE !== "1") return null;
+
+  const dir = path.join(repo, BOOT_DIR);
+  const manifest = readJson(path.join(dir, "manifest.json"));
+  if (!manifest) return null;
+
+  // A build left behind by an upgrade is older code wearing the new version's name.
+  const pkg = readJson(path.join(repo, "package.json"));
+  if (!pkg || manifest.version !== pkg.version) return null;
+
+  // The build maps each file back to its place under <repo>/node_modules. A hoisted
+  // install (npx, or a dependency of another project) has no such place.
+  if (!fs.existsSync(path.join(repo, "node_modules", "@earendil-works", "pi-coding-agent", "package.json"))) {
+    return null;
+  }
+
+  const entry = path.join(dir, "boot.mjs");
+  return fs.existsSync(entry) && fs.existsSync(path.join(dir, "cli.mjs")) ? entry : null;
+}

package/bin/fresh-supervisor.d.mts

@@ -32,4 +32,8 @@ export function runDir(home: string): string;
 export function listTerminals(home: string): TerminalEntry[];
 export function requestFresh(socket: string, token: string, timeoutMs?: number): Promise<{ ok: true; pid: number }>;
 /** Run the TUI under supervision; `buildArgs(true)` for the first launch, false after. */
-export function runSupervised(cmd: string, buildArgs: (first: boolean) => string[], opts: { home: string }): void;
+export function runSupervised(
+  cmd: string,
+  buildArgs: (first: boolean, extra?: string[]) => string[],
+  opts: { home: string; interactive?: boolean },
+): void;

package/bin/fresh-supervisor.mjs

@@ -44,6 +44,7 @@ import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { RECOVERY_ENV, encodeRecovery, readMarker, removeMarker, shouldAutoResume } from "./session-recovery.mjs";
 
 const isWin = process.platform === "win32";
 
@@ -254,9 +255,15 @@ export function requestFresh(socket, token, timeoutMs = 3000) {
 // ── supervisor ──────────────────────────────────────────────────────────────
 
 /** Put a terminal a killed TUI left in raw mode / hidden cursor / paste mode back. */
-function resetTerminal() {
+function resetTerminal({ clear = true } = {}) {
   if (!process.stdout.isTTY) return;
   if (!isWin) spawnSync("stty", ["sane"], { stdio: ["inherit", "ignore", "ignore"] });
+  // After a CRASH the screen is kept: the error the old agent printed is the only
+  // record of why it died, and the resumed agent redraws the conversation anyway.
+  if (!clear) {
+    process.stdout.write("\x1b[?25h\x1b[?1049l\x1b[?2004l\x1b[<u\x1b[0m\n");
+    return;
+  }
   // Show cursor, leave the alternate screen, bracketed paste off, pop the kitty keyboard
   // protocol, reset attributes, then clear screen + scrollback so the new agent starts on
   // a blank page rather than under the old conversation.
@@ -305,12 +312,20 @@ async function reap(child) {
 }
 
 /**
- * Run the TUI under supervision. `buildArgs(first)` returns the node argv for each
- * launch — the first uses the user's args as typed, later ones go through
- * filterRespawnArgs — and is called fresh each time so a model the user picked in the old
- * session (saved to settings.json) is what the new one boots on.
+ * Run the TUI under supervision. `buildArgs(first, extra)` returns the node argv for
+ * each launch — the first uses the user's args as typed, later ones go through
+ * filterRespawnArgs, with `extra` appended (a crash resume adds --session <file>) — and
+ * is called fresh each time so a model the user picked in the old session (saved to
+ * settings.json) is what the new one boots on.
+ *
+ * Crash resume (bin/session-recovery.mjs): when the agent dies like a crash — a
+ * non-requested exit code or a crash signal — while its live marker says it was in a
+ * session, the supervisor relaunches straight back into that session and hands the
+ * marker over in $PRIVATEER_RECOVERY so the new agent can tell the model what was
+ * interrupted. Bounded: RESUME_BUDGET per RESUME_WINDOW_MS, and an agent that dies
+ * before its session loaded has no marker, so a session that kills it on load can't loop.
  */
-export function runSupervised(cmd, buildArgs, { home }) {
+export function runSupervised(cmd, buildArgs, { home, interactive } = {}) {
   const token = crypto.randomBytes(24).toString("hex");
   const dir = runDir(home);
   const regFile = path.join(dir, `${process.pid}.json`);
@@ -318,6 +333,7 @@ export function runSupervised(cmd, buildArgs, { home }) {
   let child = null;
   let replacing = false;
   let registered = false;
+  const restarts = [];
 
   const register = () => {
     try {
@@ -334,13 +350,32 @@ export function runSupervised(cmd, buildArgs, { home }) {
     if (!isWin) fs.rmSync(sock, { force: true });
   };
 
-  const launch = (first) => {
-    child = spawn(cmd, buildArgs(first), {
+  const launch = (first, extra = [], extraEnv = {}) => {
+    const me = spawn(cmd, buildArgs(first, extra), {
       stdio: "inherit",
-      env: { ...process.env, [FRESH_SOCKET_ENV]: sock, [FRESH_TOKEN_ENV]: token },
+      env: { ...process.env, [FRESH_SOCKET_ENV]: sock, [FRESH_TOKEN_ENV]: token, ...extraEnv },
     });
-    child.on("exit", (code, signal) => {
+    child = me;
+    me.on("exit", (code, signal) => {
       if (replacing) return;
+      const marker = readMarker(home, me.pid);
+      const now = Date.now();
+      if (shouldAutoResume({
+        code, signal, marker, restarts, now,
+        sessionExists: !!marker && fs.existsSync(marker.sessionFile),
+        interactive: interactive ?? !!process.stdin.isTTY,
+      })) {
+        restarts.push(now);
+        resetTerminal({ clear: false });
+        const why = signal ? `signal ${signal}` : `exit code ${code}`;
+        process.stdout.write(`\x1b[2m⚓ The agent stopped unexpectedly (${why}). Resuming your session…\x1b[0m\n`);
+        // The marker stays on disk until the new agent consumes it, so a resume that
+        // itself fails still leaves the next launch something to point at.
+        launch(false, ["--session", marker.sessionFile], { [RECOVERY_ENV]: encodeRecovery(marker) });
+        return;
+      }
+      // Asked to stop with nothing in flight: no reason to keep it.
+      if (marker && !marker.turnOpen && (code === 0 || signal === "SIGINT" || signal === "SIGTERM")) removeMarker(home, me.pid);
       server.close();
       unregister();
       if (signal) process.kill(process.pid, signal);
@@ -361,6 +396,8 @@ export function runSupervised(cmd, buildArgs, { home }) {
     const exited = new Promise((r) => (old.exitCode !== null || old.signalCode !== null ? r() : old.once("exit", r)));
     const count = await reap(old);
     await exited;
+    // /fresh is a requested stop, even mid-turn: never offer that turn back later.
+    if (old.pid) removeMarker(home, old.pid);
     resetTerminal();
     const extra = count > 1 ? ` and ${count - 1} process${count - 1 === 1 ? "" : "es"} it started` : "";
     process.stdout.write(`\x1b[2m⚓ Fresh agent — the previous one${extra} stopped.\x1b[0m\n`);

package/bin/privateer-launch.mjs

@@ -34,6 +34,8 @@ import { runToCompletion } from "./run-to-completion.mjs";
 import { modelArgs } from "./model-args.mjs";
 import { filterRespawnArgs, listTerminals, requestFresh, runSupervised } from "./fresh-supervisor.mjs";
 import { configureCompileCache } from "./startup-cache.mjs";
+import { bootCliPath } from "./boot-bundle.mjs";
+import { sweepSessions } from "./session-seal.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
 const REPO = path.resolve(HERE, "..");
@@ -132,7 +134,16 @@ const BUNDLED = fs.existsSync(bundledNode) && fs.existsSync(path.join(REPO, "BUN
 // very node already running this script (a suitable >=22, since we booted under it).
 const NODE_BIN = BUNDLED ? bundledNode : process.execPath;
 // Make sure the chosen node's directory is on PATH for shebang-spawned grandchildren.
-process.env.PATH = path.dirname(NODE_BIN) + path.delimiter + (process.env.PATH || "");
+// The agent's own shells get that entry filtered back out (getShellEnv and the background
+// task registry, both patched): seeing a `node` the machine does not really have, it wrote
+// `#!/usr/bin/env node` tools that die the moment Privateer exits. PRIVATEER_NODE is how a
+// shell reaches this runtime on purpose. A directory the user already had on PATH stays.
+const runtimeDir = path.dirname(NODE_BIN);
+if (!(process.env.PATH || "").split(path.delimiter).includes(runtimeDir)) {
+  process.env.PRIVATEER_PRIVATE_RUNTIME_DIR = runtimeDir;
+}
+process.env.PRIVATEER_NODE = NODE_BIN;
+process.env.PATH = runtimeDir + path.delimiter + (process.env.PATH || "");
 
 const args = process.argv.slice(2);
 
@@ -753,6 +764,8 @@ else {
     );
     process.exit(1);
   }
+  // The compiled build when it is valid for this install, else the source tree.
+  const ENTRY = bootCliPath(REPO) ?? CLI;
   process.env.PI_CODING_AGENT_DIR = AGENT_DIR;
   // The binary pi-subagents spawns for each child, and the moat that child must load.
   //
@@ -895,6 +908,9 @@ else {
 
   // Dev convenience: load provider keys from the repo's .env if present.
   const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  // Session sealing (bin/session-seal.mjs): the codec has to be in place before Pi's
+  // main() opens a session, so it rides in as a preload on EVERY run that can write one.
+  nodeArgs.push("--import", pathToFileURL(path.join(HERE, "session-seal-preload.mjs")).href);
 
   // The boot splash. `--import` so it runs before Pi's entry module — most of the wait
   // it covers IS that module graph loading, so a splash started any later would miss it.
@@ -920,11 +936,19 @@ else {
   // Supervised rather than runToCompletion: the launcher stays up so /fresh, a voice
   // command, or `privateer fresh` from another terminal can swap this agent for a new
   // process with the old tree reaped. Print/export/version runs have nothing to swap.
-  const tuiArgs = (launchArgs) => [...nodeArgs, CLI, ...modelArgsFor(launchArgs), ...extArgs, ...skillArgs, ...launchArgs];
+  const tuiArgs = (launchArgs) => [...nodeArgs, ENTRY, ...modelArgsFor(launchArgs), ...extArgs, ...skillArgs, ...launchArgs];
   // forwardSignals: a `kill` reaches only this launcher, and a -p run left behind keeps
   // working (and spending) with nobody waiting for its answer.
   if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args), { forwardSignals: true });
-  else runSupervised(NODE_BIN, (first) => tuiArgs(first ? args : filterRespawnArgs(args)), { home: PRIVATEER_HOME });
+  // `extra` is how a crash resume re-enters the session (--session <file>).
+  else {
+    // Seal the sessions written before sealing existed — once, in this (the
+    // supervisor's) process, in the background, while the agent boots.
+    setTimeout(() => {
+      sweepSessions(PRIVATEER_HOME, path.join(AGENT_DIR, "sessions")).catch(() => {});
+    }, 3000).unref();
+    runSupervised(NODE_BIN, (first, extra = []) => tuiArgs([...(first ? args : filterRespawnArgs(args)), ...extra]), { home: PRIVATEER_HOME });
+  }
 }
 
 // --- helpers ---------------------------------------------------------------

package/bin/privateer-subagent.mjs

@@ -18,7 +18,7 @@
 // spawn only runs when this file is invoked as a binary.
 
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve, join, delimiter } from "node:path";
 import { existsSync } from "node:fs";
 
@@ -91,7 +91,10 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
   if (!process.env.PI_SKIP_VERSION_CHECK) process.env.PI_SKIP_VERSION_CHECK = "1";
   if (!process.env.PI_BG_DISABLE_UPDATE_CHECK) process.env.PI_BG_DISABLE_UPDATE_CHECK = "1";
   const args = buildChildArgs(process.argv.slice(2));
-  const child = spawn(process.execPath, [piCliPath(), ...args], { stdio: "inherit", env: process.env });
+  // The session codec, as for the TUI (bin/session-seal-preload.mjs): a child writes
+  // its own session file, and it must be sealed like the parent's.
+  const preload = pathToFileURL(join(HERE, "session-seal-preload.mjs")).href;
+  const child = spawn(process.execPath, ["--import", preload, piCliPath(), ...args], { stdio: "inherit", env: process.env });
   // Propagate the child's exit faithfully so pi-subagents' parent reads the real
   // outcome (a signal re-raises; otherwise exit with the same code).
   child.on("exit", (code, signal) => {

package/bin/privateer-verify.mjs

@@ -21,6 +21,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { findDepRoot } from "./apply-patches.mjs";
+import { BOOT_DIR, bootCliPath } from "./boot-bundle.mjs";
 
 const REGISTRY = process.env.npm_config_registry || "https://registry.npmjs.org";
 const NET_TIMEOUT_MS = 8000;
@@ -228,6 +229,17 @@ export async function verify({ repo, offline = false } = {}) {
     }
   }
 
+  // Which code a launch actually runs: the compiled build, when valid, is the patched
+  // source above in one place, so "patched" is only half the answer without this.
+  heading("Boot build");
+  const bootBuild = readJson(path.join(repo, BOOT_DIR, "manifest.json"));
+  if (bootCliPath(repo)) {
+    pass("compiled entry in use", `${bootBuild.modules} modules · pi ${bootBuild.pi}`);
+    note("built from this release's source and patches; PRIVATEER_NO_BOOT_BUNDLE=1 runs the source tree");
+  } else {
+    note(bootBuild ? "present but not used here, so launches run from source" : "none, so launches run from source");
+  }
+
   // --- 5. where config and credentials live -------------------------------
   heading("Config");
   const home = process.env.PRIVATEER_HOME || path.join(process.env.HOME || "", ".privateer");

package/bin/session-recovery.d.mts

@@ -0,0 +1,53 @@
+// Types for session recovery (bin/session-recovery.mjs). Same reason as the other
+// bin/*.d.mts: bin/ runs under a bare `node`, but the recovery extension and its tests
+// are TypeScript.
+
+export const RECOVERY_ENV: "PRIVATEER_RECOVERY";
+export const MARKER_MAX_AGE_MS: number;
+export const RESUME_BUDGET: number;
+export const RESUME_WINDOW_MS: number;
+
+export interface MarkerTool {
+  name: string;
+  summary: string;
+  startedAt: number;
+}
+
+/** A live marker, as kept in PRIVATEER_HOME/run/live/<pid>.json. */
+export interface LiveMarker {
+  v: 1;
+  pid: number;
+  sessionFile: string;
+  cwd: string;
+  startedAt: number;
+  updatedAt: number;
+  turnOpen: boolean;
+  tool: MarkerTool | null;
+  hinted?: boolean;
+}
+
+export function liveDir(home: string): string;
+export function markerPath(home: string, pid: number): string;
+export function writeMarker(home: string, marker: Omit<LiveMarker, "v"> & { v: 1 } | LiveMarker): void;
+export function readMarker(home: string, pid: number): LiveMarker | null;
+export function removeMarker(home: string, pid: number): void;
+export function parseMarker(text: string | null): LiveMarker | null;
+export function isAlive(pid: number): boolean;
+export function listStale(home: string, opts?: { cwd?: string; now?: number; alive?: (pid: number) => boolean }): LiveMarker[];
+export function staleForSession(home: string, sessionFile: string, opts?: { now?: number; alive?: (pid: number) => boolean }): LiveMarker | null;
+export function shouldAutoResume(input: {
+  code: number | null;
+  signal: string | null;
+  marker: LiveMarker | null;
+  restarts?: number[];
+  now?: number;
+  sessionExists?: boolean;
+  interactive?: boolean;
+}): boolean;
+export function summarizeToolCall(name: unknown, args: unknown): string;
+export function recoveryNote(marker: LiveMarker | null, opts?: { reason?: string }): string | null;
+export function recoveryNotice(marker: LiveMarker, opts?: { now?: number }): string;
+export function sessionIdFromFile(file: string): string | null;
+export function resumeHint(marker: LiveMarker, opts?: { cmd?: string; now?: number }): string;
+export function encodeRecovery(marker: LiveMarker): string;
+export function decodeRecovery(value: string | undefined | null): LiveMarker | null;

package/bin/session-recovery.mjs

@@ -0,0 +1,240 @@
+// Session recovery — what lets a terminal survive its agent dying mid-task.
+//
+// Pi already writes the session to disk as it goes (~/.privateer/agent/sessions,
+// one JSONL file per session, the user's prompt persisted BEFORE the first reply),
+// and it already patches a tool call that never got a result ("No result
+// provided"). What nothing did was notice the death and act on it:
+//   - an uncaught exception was logged (crashes.json) and the next launch said
+//     "Run /bug" — it never offered the session back;
+//   - SIGKILL, the OOM killer, a closed terminal or a power cut left no trace at all;
+//   - a resumed session gave the model no hint that its last tool may have half-run.
+//
+// So each agent process keeps a LIVE MARKER (run/live/<pid>.json, 0600): which
+// session file it is in, whether a turn is open, and which tool is running. The
+// agent writes it (extensions/privateer-recovery.ts); whoever outlives the agent
+// reads it:
+//   - the supervisor (fresh-supervisor.mjs), when its child dies like a crash,
+//     relaunches into the same session at once;
+//   - the launcher, on the next `privateer` in that folder, prints how to resume a
+//     session that died with a turn open (it never resumes on its own there — the
+//     user may have come back to start something new);
+//   - the resumed agent turns the marker into ONE note for the model: the previous
+//     process stopped during `<tool>`, the work may be partly applied, check before
+//     continuing. Never an automatic re-run: replaying `git push` or a migration is
+//     worse than losing the turn.
+//
+// A marker is removed when the agent shuts down cleanly with NO turn open. A
+// graceful shutdown with a turn open (the terminal closed, SIGTERM) leaves it: the
+// work was interrupted all the same.
+//
+// Dependency-free on purpose: the launcher reads this before anything is patched,
+// and the supervisor runs it with no TS loader.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const RECOVERY_ENV = "PRIVATEER_RECOVERY";
+
+/** Markers older than this are garbage: nobody is coming back for that turn. */
+export const MARKER_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Auto-resume at most this many times… */
+export const RESUME_BUDGET = 2;
+/** …within this window, so a session that crashes on load can't loop forever. */
+export const RESUME_WINDOW_MS = 3 * 60 * 1000;
+
+// Deaths that look like the process failing rather than being asked to stop.
+// SIGKILL is in: it is what the OOM killer sends. SIGINT/SIGTERM/SIGHUP are not —
+// those are a person, a terminal or a service manager saying stop.
+const CRASH_SIGNALS = new Set(["SIGKILL", "SIGSEGV", "SIGABRT", "SIGBUS", "SIGILL", "SIGFPE", "SIGTRAP"]);
+// Exit codes that mean "stopped on request" (128 + SIGINT / SIGTERM / SIGHUP).
+const REQUESTED_CODES = new Set([0, 129, 130, 143]);
+
+export function liveDir(home) {
+  return path.join(home, "run", "live");
+}
+
+export function markerPath(home, pid) {
+  return path.join(liveDir(home), `${pid}.json`);
+}
+
+/** Write atomically (tmp + rename) and owner-only: it names files and commands. */
+export function writeMarker(home, marker) {
+  const dir = liveDir(home);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = markerPath(home, marker.pid);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(marker) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+export function readMarker(home, pid) {
+  return parseMarker(safeRead(markerPath(home, pid)));
+}
+
+export function removeMarker(home, pid) {
+  try {
+    fs.rmSync(markerPath(home, pid), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+function safeRead(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Shape-check a marker. Anything malformed reads as absent, never as a crash. */
+export function parseMarker(text) {
+  if (typeof text !== "string") return null;
+  let m;
+  try {
+    m = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!m || m.v !== 1 || !Number.isInteger(m.pid) || typeof m.sessionFile !== "string" || !m.sessionFile) return null;
+  return {
+    v: 1,
+    pid: m.pid,
+    sessionFile: m.sessionFile,
+    cwd: typeof m.cwd === "string" ? m.cwd : "",
+    startedAt: Number(m.startedAt) || 0,
+    updatedAt: Number(m.updatedAt) || 0,
+    turnOpen: m.turnOpen === true,
+    tool: m.tool && typeof m.tool.name === "string"
+      ? { name: m.tool.name, summary: typeof m.tool.summary === "string" ? m.tool.summary : "", startedAt: Number(m.tool.startedAt) || 0 }
+      : null,
+    hinted: m.hinted === true,
+  };
+}
+
+export function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+
+/**
+ * Markers whose agent died MID-TURN, newest first. Prunes the rest of the dead: idle
+ * ones, ones past MARKER_MAX_AGE_MS, and ones whose session file is gone.
+ */
+export function listStale(home, { cwd, now = Date.now(), alive = isAlive } = {}) {
+  let names = [];
+  try {
+    names = fs.readdirSync(liveDir(home)).filter((n) => /^\d+\.json$/.test(n));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    const file = path.join(liveDir(home), name);
+    const m = parseMarker(safeRead(file));
+    if (!m) continue;
+    if (alive(m.pid)) continue;
+    // Dead while IDLE says nothing worth saying (a closed terminal can kill Pi on its
+    // dead-tty path, which skips session_shutdown, so these do happen). The
+    // supervisor's crash resume reads its child's marker directly, not through here.
+    if (!m.turnOpen || now - (m.updatedAt || m.startedAt) > MARKER_MAX_AGE_MS || !fs.existsSync(m.sessionFile)) {
+      try { fs.rmSync(file, { force: true }); } catch { /* best-effort */ }
+      continue;
+    }
+    if (cwd && path.resolve(m.cwd) !== path.resolve(cwd)) continue;
+    out.push(m);
+  }
+  return out.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/** The stale marker (if any) for one session file — what a resumed agent consumes. */
+export function staleForSession(home, sessionFile, opts = {}) {
+  const want = path.resolve(sessionFile);
+  return listStale(home, opts).find((m) => path.resolve(m.sessionFile) === want) ?? null;
+}
+
+/**
+ * Should the supervisor relaunch into the session right now? Pure.
+ * `restarts` = timestamps of earlier auto-resumes by this supervisor.
+ */
+// There is deliberately no minimum-lifetime floor. The marker is written only once a
+// session has LOADED (session_start), so an agent that crashes while booting or while
+// loading the session has no marker and is never resumed — that, plus the budget, is
+// the loop guard. A 5s floor was tried and wrongly refused a real kill -9 of a warm
+// agent that had been up for 3s.
+export function shouldAutoResume({ code, signal, marker, restarts = [], now = Date.now(), sessionExists = true, interactive = true }) {
+  if (!marker || !interactive || !sessionExists) return false;
+  const crashed = signal ? CRASH_SIGNALS.has(signal) : !REQUESTED_CODES.has(code ?? 0);
+  if (!crashed) return false;
+  return restarts.filter((t) => now - t < RESUME_WINDOW_MS).length < RESUME_BUDGET;
+}
+
+/** One line describing a tool call, safe to keep in a 0600 file and show the model. */
+export function summarizeToolCall(name, args) {
+  const flat = (s) => String(s).replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  const clip = (s, n = 160) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+  if (!args || typeof args !== "object") return clip(flat(name));
+  const pick = args.command ?? args.cmd ?? args.path ?? args.file_path ?? args.file ?? args.url ?? args.query;
+  if (typeof pick === "string" && pick.trim()) return clip(flat(pick));
+  return clip(Object.keys(args).slice(0, 6).join(", "));
+}
+
+const ago = (ms) => {
+  const m = Math.round(ms / 60000);
+  if (m < 1) return "moments ago";
+  if (m < 60) return `${m} min ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`;
+};
+
+/** The note the resumed agent hands the model. Null when no turn was open. */
+export function recoveryNote(marker, { reason = "stopped unexpectedly" } = {}) {
+  if (!marker?.turnOpen) return null;
+  const during = marker.tool
+    ? `while it was running the \`${marker.tool.name}\` tool${marker.tool.summary ? ` (\`${marker.tool.summary}\`)` : ""}`
+    : "in the middle of a turn, between tool calls";
+  return [
+    `[Privateer] The previous agent process for this session ${reason} ${during}.`,
+    "Its last action may have run fully, partly, or not at all, and anything it started (a server, a build, a migration) may still be running or may have been killed.",
+    "Do not repeat that action blindly. Check the current state first (files, git status, running processes, the remote) and tell the user briefly what you found before carrying on.",
+  ].join(" ");
+}
+
+/** What the user sees in the resumed terminal. */
+export function recoveryNotice(marker, { now = Date.now() } = {}) {
+  const when = ago(now - (marker.updatedAt || marker.startedAt || now));
+  if (!marker.turnOpen) return `Resumed your session — the previous agent stopped ${when}.`;
+  const what = marker.tool ? ` during ${marker.tool.name}${marker.tool.summary ? `: ${marker.tool.summary}` : ""}` : "";
+  return `Resumed your session — the previous agent stopped ${when} mid-task${what}. It may have been partly done; the agent will check before continuing.`;
+}
+
+/** Pi's session id from its file name (`<timestamp>_<id>.jsonl`). */
+export function sessionIdFromFile(file) {
+  const m = path.basename(file).match(/_([0-9a-f-]{8,})\.jsonl$/i);
+  return m ? m[1] : null;
+}
+
+/** Copy-pasteable resume hint for the next launch in that folder. */
+export function resumeHint(marker, { cmd = "privateer", now = Date.now() } = {}) {
+  const id = sessionIdFromFile(marker.sessionFile);
+  const target = id ?? marker.sessionFile;
+  const what = marker.tool ? ` (during ${marker.tool.name}${marker.tool.summary ? `: ${marker.tool.summary}` : ""})` : "";
+  return `⚓ Your last session in this folder stopped mid-task ${ago(now - (marker.updatedAt || now))}${what}.\n   Resume it: ${cmd} --session ${target}`;
+}
+
+/** Encode a marker for the relaunched child's environment (and decode it there). */
+export function encodeRecovery(marker) {
+  return Buffer.from(JSON.stringify(marker)).toString("base64");
+}
+export function decodeRecovery(value) {
+  if (typeof value !== "string" || !value) return null;
+  try {
+    return parseMarker(Buffer.from(value, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+}

package/bin/session-seal-preload.mjs

@@ -0,0 +1,17 @@
+// `node --import` preload for every Pi process privateer starts (the TUI, -p runs,
+// subagent children): installs the session codec (bin/session-seal.mjs) BEFORE
+// Pi's main() opens a session, which happens before any extension loads — so an
+// extension is too late for this, and a preload is the only place it fits.
+//
+// A key file that exists but can't be read is NOT papered over with a new key (that
+// would orphan every sealed session). Sealing stays off for this run, the agent
+// tells the user (extensions/privateer-recovery.ts reads the reason below), and Pi
+// writes plaintext exactly as it did before sealing existed.
+
+import os from "node:os";
+import path from "node:path";
+import { installCodec } from "./session-seal.mjs";
+
+const home = process.env.PRIVATEER_HOME || path.join(os.homedir(), ".privateer");
+const result = installCodec(home);
+if (!result.ok) globalThis[Symbol.for("privateer.sessionCodecError")] = result.error;

package/bin/session-seal.d.mts

@@ -0,0 +1,25 @@
+// Types for session sealing (bin/session-seal.mjs). Same reason as the other
+// bin/*.d.mts: bin/ runs under a bare `node`, but its tests are TypeScript.
+
+export const CODEC_KEY: unique symbol;
+export const QUIET_MS: number;
+
+export interface SessionCodec {
+  failures: number;
+  encode(entry: unknown): string;
+  decode(obj: unknown): any;
+}
+
+export function keyPath(home: string): string;
+export function loadOrCreateKey(home: string): Buffer;
+export function isSealed(obj: unknown): boolean;
+export function encodeEntry(entry: unknown, key: Buffer): string;
+export function decodeEntry(obj: unknown, key: Buffer): any;
+export function installCodec(home: string): { ok: true } | { ok: false; error: string };
+export function sealFile(file: string, key: Buffer): "sealed" | "unchanged" | "busy" | "failed";
+export function listSessionFiles(sessionsDir: string): string[];
+export function sweepSessions(
+  home: string,
+  sessionsDir: string,
+  opts?: { now?: number; quietMs?: number },
+): Promise<{ skipped: true } | { error: true } | { sealed: number; unchanged: number; busy: number; failed: number; recent: number }>;