privateer-agent 0.15.4 → 0.15.5

package/bin/session-seal.mjs

@@ -0,0 +1,242 @@
+// Session sealing — Pi's session transcripts, encrypted at rest.
+//
+// Pi writes every conversation to ~/.privateer/agent/sessions/<cwd>/<ts>_<id>.jsonl,
+// one JSON entry per line, and until now in plaintext: every prompt, every reply,
+// every file the agent read and every command's output, readable by anything that
+// can read the home directory — backup and sync tools, indexers, a stray `grep -r`,
+// any other program the user runs.
+//
+// Now each line except the header is sealed with AES-256-GCM:
+//     {"pvs":1,"iv":"<b64 12 bytes>","ct":"<b64 ciphertext‖tag>"}
+// The HEADER (type "session": id, timestamp, cwd) stays readable on purpose. Pi
+// finds and lists sessions by reading only the first line of each file, and the cwd
+// it holds is already spelled out in the directory name, so sealing it would cost
+// session discovery and hide nothing.
+//
+// The patch in patches/@earendil-works+pi-coding-agent+*.patch routes Pi's reads
+// (parseSessionEntryLine / parseSessionEntries) and writes (every JSON.stringify of
+// an entry) through the codec this module installs on globalThis. Without the codec
+// — Pi run by hand, outside `privateer` — Pi writes plaintext as before, and sealed
+// lines read as absent rather than as garbage. Readers accept both forms forever, so
+// files written before this change, and files of mixed form, keep working.
+//
+// THE KEY, AND WHAT THIS DOES NOT DO. One random 32-byte key per machine, in
+// $PRIVATEER_HOME/session-key.json (0600) — next to the data, like this tool's other
+// secrets (terminal-key.json, credentials). So this protects transcripts from
+// anything that reads the session FILES (indexers, a shared or synced sessions
+// folder, an attachment pasted from the wrong directory, tools that scan for
+// .jsonl), and it does NOT protect them from someone who can read the whole
+// ~/.privateer as this user: that reader has the key too. Say exactly that, never
+// more. An OS keychain would move the key out of the folder, at the price of
+// sessions that can't open over ssh or with the keychain locked — a different
+// trade, not a free upgrade.
+//
+// Never mint a key over one that exists: a second key orphans every session sealed
+// under the first. A key file that is present but unreadable or malformed is an
+// error (sealing is switched off and the user is told), never a reason to start over.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const CODEC_KEY = Symbol.for("privateer.sessionCodec");
+const KEY_FILE = "session-key.json";
+
+export function keyPath(home) {
+  return path.join(home, KEY_FILE);
+}
+
+function parseKeyFile(text) {
+  const parsed = JSON.parse(text);
+  const key = Buffer.from(String(parsed?.key ?? ""), "base64");
+  if (parsed?.v !== 1 || key.length !== 32) throw new Error("session key file is malformed");
+  return key;
+}
+
+/**
+ * Load this machine's session key, minting it only when no key file exists at all.
+ * Two terminals starting at once race on `wx`: the loser re-reads the winner's key.
+ */
+export function loadOrCreateKey(home) {
+  const file = keyPath(home);
+  try {
+    return parseKeyFile(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+  }
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const key = crypto.randomBytes(32);
+  try {
+    fs.writeFileSync(file, JSON.stringify({ v: 1, key: key.toString("base64"), created: new Date().toISOString() }) + "\n", { mode: 0o600, flag: "wx" });
+    return key;
+  } catch (e) {
+    if (e?.code === "EEXIST") return parseKeyFile(fs.readFileSync(file, "utf8"));
+    throw e;
+  }
+}
+
+export function isSealed(obj) {
+  return !!obj && typeof obj === "object" && obj.pvs === 1 && typeof obj.iv === "string" && typeof obj.ct === "string";
+}
+
+/** One entry → one line (no newline). The session header is never sealed. */
+export function encodeEntry(entry, key) {
+  if (entry?.type === "session") return JSON.stringify(entry);
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const ct = Buffer.concat([cipher.update(JSON.stringify(entry), "utf8"), cipher.final(), cipher.getAuthTag()]);
+  return JSON.stringify({ pvs: 1, iv: iv.toString("base64"), ct: ct.toString("base64") });
+}
+
+/** A parsed line → the entry. Plaintext passes through; a line that fails to open → null. */
+export function decodeEntry(obj, key) {
+  if (!isSealed(obj)) return obj;
+  try {
+    const iv = Buffer.from(obj.iv, "base64");
+    const raw = Buffer.from(obj.ct, "base64");
+    if (iv.length !== 12 || raw.length < 17) return null;
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(raw.subarray(raw.length - 16));
+    const text = Buffer.concat([decipher.update(raw.subarray(0, raw.length - 16)), decipher.final()]).toString("utf8");
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install the codec Pi's patched session manager calls. Returns { ok, error? }.
+ * `failures` counts lines that would not open (a different machine's key, a damaged
+ * file), so the agent can say so instead of showing a silently shorter session.
+ */
+export function installCodec(home) {
+  let key;
+  try {
+    key = loadOrCreateKey(home);
+  } catch (e) {
+    delete globalThis[CODEC_KEY];
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+  const codec = {
+    failures: 0,
+    encode: (entry) => encodeEntry(entry, key),
+    decode: (obj) => {
+      const out = decodeEntry(obj, key);
+      if (out === null) codec.failures++;
+      return out;
+    },
+  };
+  globalThis[CODEC_KEY] = codec;
+  return { ok: true };
+}
+
+/**
+ * Seal one existing file in place. Lines that are already sealed, the header, and
+ * lines that don't parse are carried over byte-for-byte (a malformed line is Pi's to
+ * skip, not ours to drop). Written to a sibling temp file, VERIFIED by reading it
+ * back, then renamed over the original only if the original hasn't changed since it
+ * was read — a session another terminal is appending to is left for a later pass.
+ * The file keeps its original atime/mtime (Pi sorts sessions by mtime).
+ * Returns "sealed" | "unchanged" | "busy" | "failed".
+ */
+export function sealFile(file, key) {
+  let before, text;
+  try {
+    before = fs.statSync(file);
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return "failed";
+  }
+  const lines = text.split("\n");
+  let changed = false;
+  const out = lines.map((line) => {
+    if (!line.trim()) return line;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      return line;
+    }
+    if (isSealed(obj) || obj?.type === "session") return line;
+    changed = true;
+    return encodeEntry(obj, key);
+  });
+  if (!changed) return "unchanged";
+
+  // Verify: every original entry must come back identical from what we will write.
+  for (let i = 0; i < lines.length; i++) {
+    if (out[i] === lines[i]) continue;
+    const back = decodeEntry(JSON.parse(out[i]), key);
+    if (JSON.stringify(back) !== JSON.stringify(JSON.parse(lines[i]))) return "failed";
+  }
+
+  const tmp = `${file}.sealing-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, out.join("\n"), { mode: 0o600 });
+    const now = fs.statSync(file);
+    if (now.size !== before.size || now.mtimeMs !== before.mtimeMs) {
+      fs.rmSync(tmp, { force: true });
+      return "busy";
+    }
+    // Keep the original times: Pi orders sessions by mtime (`privateer -c` continues
+    // the most recent one), so a conversion must not make an old session look new.
+    fs.utimesSync(tmp, before.atime, before.mtime);
+    fs.renameSync(tmp, file);
+    return "sealed";
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort */ }
+    return "failed";
+  }
+}
+
+/** Every session file under Pi's sessions dir. */
+export function listSessionFiles(sessionsDir) {
+  const out = [];
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(sessionsDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const dir = path.join(sessionsDir, d.name);
+    try {
+      for (const f of fs.readdirSync(dir)) if (f.endsWith(".jsonl")) out.push(path.join(dir, f));
+    } catch { /* unreadable folder: skip */ }
+  }
+  return out;
+}
+
+/**
+ * Seal every plaintext session on this machine — once, then never again. Files
+ * touched in the last QUIET_MS are skipped (another terminal may be writing them);
+ * the done-marker is only written when nothing was skipped or failed, so a later
+ * launch finishes the job. Async-yielding so the launcher's event loop stays live.
+ */
+export const QUIET_MS = 10 * 60 * 1000;
+export async function sweepSessions(home, sessionsDir, { now = Date.now(), quietMs = QUIET_MS } = {}) {
+  const done = path.join(home, "run", "sessions-sealed-v1");
+  if (fs.existsSync(done)) return { skipped: true };
+  let key;
+  try {
+    key = loadOrCreateKey(home);
+  } catch {
+    return { error: true };
+  }
+  const tally = { sealed: 0, unchanged: 0, busy: 0, failed: 0, recent: 0 };
+  for (const file of listSessionFiles(sessionsDir)) {
+    try {
+      if (now - fs.statSync(file).mtimeMs < quietMs) { tally.recent++; continue; }
+    } catch { continue; }
+    tally[sealFile(file, key)]++;
+    await new Promise((r) => setImmediate(r));
+  }
+  if (!tally.busy && !tally.failed && !tally.recent) {
+    try {
+      fs.mkdirSync(path.dirname(done), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(done, new Date().toISOString() + "\n", { mode: 0o600 });
+    } catch { /* retried next launch */ }
+  }
+  return tally;
+}

package/extensions/privateer-gate.ts

@@ -20,6 +20,7 @@ import {
   startParentApprovalRelay,
 } from "../src/remote/subagentRelay.ts";
 import { RelayClient } from "../src/remote/relayClient.ts";
+import { transcriptSnapshot } from "../src/remote/transcriptSnapshot.ts";
 import { makeSendFileTool } from "../src/tools/sendFile.ts";
 import { makeSaveCargoTool } from "../src/tools/cargo.ts";
 import { makeChartTools } from "../src/tools/charts.ts";
@@ -471,7 +472,19 @@ const bridge = new RemoteBridge({
     // snapshot, push live context (model + version) so the app banner reflects this
     // terminal, and advertise the slash commands for the composer's autocomplete.
     setRemoteState("connected");
-    relay?.sendSnapshot([{ kind: "notice", text: "Privateer terminal connected." }]);
+    // The session's transcript, not a "connected" notice: an app coming back from
+    // sleep holds a feed frozen where its socket died, and this is how it learns what
+    // happened since — including that the turn it last saw is over (`running`).
+    let entries: ReturnType<typeof transcriptSnapshot> = [];
+    let running = false;
+    try {
+      entries = transcriptSnapshot(ctxRef?.sessionManager?.getBranch?.() ?? []);
+      running = ctxRef?.isIdle?.() === false;
+    } catch { /* a replaced session's context throws — fall back to the notice */ }
+    relay?.sendSnapshot(
+      entries.length ? entries : [{ kind: "notice", text: "Privateer terminal connected." }],
+      { full: entries.length > 0, running },
+    );
     // cwd rides along here (home-collapsed on the way out, see RelayClient.sendContext).
     // Without it the app's composer shows no working-directory strip at all — and that
     // strip is the only place a driver can see which folder the prompts they type are

package/extensions/privateer-recovery.ts

@@ -0,0 +1,175 @@
+// Session recovery, agent side — keeps this process's live marker current and, when
+// this session is a resumption of one whose agent died, tells the model and the user.
+// Also the one place that tells the user when session sealing (bin/session-seal.mjs)
+// is off for this run, or when lines of the session couldn't be decrypted.
+//
+// The marker (bin/session-recovery.mjs has the whole design) is written at:
+//   session_start          → which session file, no turn open
+//   agent_start            → a turn is open
+//   tool_execution_start   → which tool, and a one-line summary of its target
+//   tool_execution_end     → no tool running (the turn may still be open)
+//   agent_end              → turn closed
+//   session_shutdown       → removed, UNLESS a turn is still open — a terminal closed
+//                            mid-task is an interrupted task, and the next launch in
+//                            that folder should say so
+//
+// On session_start this agent also looks for a dead agent's marker for the SAME
+// session file — handed over by the supervisor in $PRIVATEER_RECOVERY when it
+// relaunched us after a crash, or found on disk when the user resumed by hand
+// (--session / -c / -r) — and turns it into one note for the model (delivered with
+// the user's next message, never triggering a turn on its own) plus one line for
+// the user. Nothing is re-run.
+//
+// TUI only: print/json runs are one-shot and scripted, and the desktop and harbor
+// sessions are in-memory, with no session file to resume into.
+
+import fs from "node:fs";
+import { globalDir } from "../src/config/paths.ts";
+import {
+  RECOVERY_ENV,
+  decodeRecovery,
+  listStale,
+  recoveryNote,
+  recoveryNotice,
+  removeMarker,
+  resumeHint,
+  staleForSession,
+  summarizeToolCall,
+  writeMarker,
+} from "../bin/session-recovery.mjs";
+
+// Read once and taken out of the environment, like the fresh-agent key: every bash
+// command the agent runs inherits process.env, and none of them should see this.
+const HANDOFF = Symbol.for("privateer.recovery.handoff");
+function takeHandoff(): string | undefined {
+  const g = globalThis as any;
+  if (!(HANDOFF in g)) {
+    g[HANDOFF] = process.env[RECOVERY_ENV];
+    delete process.env[RECOVERY_ENV];
+  }
+  const v = g[HANDOFF];
+  g[HANDOFF] = undefined; // one resumption, one note
+  return v;
+}
+
+let sealingWarned = false;
+function sealingNotice(ctx: any): void {
+  const g = globalThis as any;
+  const codec = g[Symbol.for("privateer.sessionCodec")];
+  const error = g[Symbol.for("privateer.sessionCodecError")];
+  if (!codec) {
+    if (sealingWarned || !error) return; // no preload at all = not launched by privateer
+    sealingWarned = true;
+    ctx?.ui?.notify?.(`Session encryption is off for this run (${error}). This session is being saved unencrypted. Your key file was left untouched — sessions sealed with it are unreadable until it's fixed.`, "warning");
+    return;
+  }
+  if (codec.failures > 0) {
+    const n = codec.failures;
+    codec.failures = 0;
+    ctx?.ui?.notify?.(`${n} saved line${n === 1 ? "" : "s"} of this session couldn't be decrypted with this machine's session key and ${n === 1 ? "isn't" : "aren't"} shown. The file itself is unchanged.`, "warning");
+  }
+}
+
+export default function privateerRecovery(pi: any): void {
+  const home = globalDir();
+  const pid = process.pid;
+  let state: {
+    sessionFile: string;
+    cwd: string;
+    startedAt: number;
+    turnOpen: boolean;
+    tool: { name: string; summary: string; startedAt: number } | null;
+  } | null = null;
+
+  const save = () => {
+    if (!state) return;
+    try {
+      writeMarker(home, { v: 1, pid, ...state, updatedAt: Date.now() });
+    } catch {
+      // A marker we can't write costs only the recovery, never the session.
+    }
+  };
+
+  pi.on("session_start", (_event: any, ctx: any) => {
+    if (ctx?.mode !== "tui") return;
+    const sessionFile: string | undefined = ctx?.sessionManager?.getSessionFile?.();
+    if (!sessionFile) {
+      state = null;
+      removeMarker(home, pid);
+      return;
+    }
+    state = { sessionFile, cwd: ctx?.cwd ?? process.cwd(), startedAt: Date.now(), turnOpen: false, tool: null };
+    save();
+
+    // Session sealing (bin/session-seal.mjs) is installed by a preload; say when it
+    // isn't working rather than let a session silently save in plaintext, or open
+    // shorter than it is.
+    sealingNotice(ctx);
+
+    // Sessions written before Pi tightened its file mode are world-readable.
+    try {
+      if (fs.existsSync(sessionFile)) fs.chmodSync(sessionFile, 0o600);
+    } catch { /* not ours to fail over */ }
+
+    const handed = decodeRecovery(takeHandoff());
+    const dead = handed && handed.sessionFile === sessionFile ? handed : staleForSession(home, sessionFile);
+    if (!dead || dead.pid === pid) {
+      if (_event?.reason === "startup") hintInterrupted(ctx, sessionFile);
+      return;
+    }
+    removeMarker(home, dead.pid);
+
+    const note = recoveryNote(dead);
+    if (note) {
+      pi.sendMessage?.(
+        { customType: "privateer-recovery", content: note, display: false },
+        { deliverAs: "nextTurn" },
+      );
+    }
+    ctx?.ui?.notify?.(recoveryNotice(dead), dead.turnOpen ? "warning" : "info");
+  });
+
+  // A NEW session in a folder whose last session died mid-task (the terminal closed,
+  // the machine slept and was killed, the supervisor died with it): say how to get it
+  // back, once. Never resumed on our own here — the user may have come back on purpose
+  // to start something else.
+  const hintInterrupted = (ctx: any, current: string) => {
+    const cwd = ctx?.cwd ?? process.cwd();
+    const m = listStale(home, { cwd }).find((x) => x.turnOpen && !x.hinted && x.sessionFile !== current);
+    if (!m) return;
+    ctx?.ui?.notify?.(resumeHint(m, { cmd: process.env.PRIVATEER_CMD || "privateer" }), "info");
+    try { writeMarker(home, { ...m, hinted: true }); } catch { /* shown once is a nicety */ }
+  };
+
+  pi.on("agent_start", () => {
+    if (!state) return;
+    state.turnOpen = true;
+    save();
+  });
+
+  pi.on("tool_execution_start", (event: any) => {
+    if (!state || event?.parentToolCallId) return; // the outer call is what the user saw
+    state.tool = { name: String(event?.toolName ?? "tool"), summary: summarizeToolCall(event?.toolName, event?.args), startedAt: Date.now() };
+    save();
+  });
+
+  pi.on("tool_execution_end", (event: any) => {
+    if (!state || event?.parentToolCallId) return;
+    state.tool = null;
+    save();
+  });
+
+  pi.on("agent_end", () => {
+    if (!state) return;
+    state.turnOpen = false;
+    state.tool = null;
+    save();
+  });
+
+  pi.on("session_shutdown", () => {
+    if (!state) return;
+    if (state.turnOpen) save(); // interrupted: leave it for whoever comes next
+    else removeMarker(home, pid);
+    state = null;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.15.4",
+  "version": "0.15.5",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/patches/@earendil-works+pi-coding-agent+1.3.0.patch

@@ -826,6 +826,95 @@ index 563d7d5..4f669b6 100644
              return projectPath;
          }
          const globalPath = join(this.agentDir, "APPEND_SYSTEM.md");
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/session-manager.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/session-manager.js
+index 62b469b..7e3c2c1 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/core/session-manager.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/session-manager.js
+@@ -1,6 +1,22 @@
+ import { getCurrentSystemMessage, uuidv7, } from "@earendil-works/pi-ai";
+ import { randomUUID } from "crypto";
+ import { appendFileSync, closeSync, createReadStream, existsSync, mkdirSync, openSync, readdirSync, readSync, statSync, writeFileSync, } from "fs";
++// [privateer] Session sealing (privateer-agent bin/session-seal.mjs): every entry
++// line except the header is written and read through a codec the launcher installs
++// on globalThis before Pi starts. Absent codec → plaintext, as upstream; a sealed
++// line read without the codec is skipped like any other line Pi can't parse.
++const PRIVATEER_SESSION_CODEC = Symbol.for("privateer.sessionCodec");
++function serializeSessionEntry(entry) {
++    const codec = globalThis[PRIVATEER_SESSION_CODEC];
++    return codec ? codec.encode(entry) : JSON.stringify(entry);
++}
++function decodeSessionEntry(entry) {
++    if (entry && typeof entry === "object" && entry.pvs !== undefined) {
++        const codec = globalThis[PRIVATEER_SESSION_CODEC];
++        return codec ? codec.decode(entry) : null;
++    }
++    return entry;
++}
+ import { readdir, stat } from "fs/promises";
+ import { basename, join, resolve } from "path";
+ import { createInterface } from "readline";
+@@ -95,8 +111,9 @@ export function parseSessionEntries(content) {
+         if (!line.trim())
+             continue;
+         try {
+-            const entry = JSON.parse(line);
+-            entries.push(entry);
++            const entry = decodeSessionEntry(JSON.parse(line));
++            if (entry)
++                entries.push(entry);
+         }
+         catch {
+             // Skip malformed lines
+@@ -314,7 +331,7 @@ function parseSessionEntryLine(line) {
+     if (!line.trim())
+         return null;
+     try {
+-        return JSON.parse(line);
++        return decodeSessionEntry(JSON.parse(line));
+     }
+     catch {
+         // Skip malformed lines
+@@ -757,7 +774,7 @@ export class SessionManager {
+         const fd = openSync(this.sessionFile, "w");
+         try {
+             for (const entry of this.fileEntries) {
+-                writeFileSync(fd, `${JSON.stringify(entry)}\n`);
++                writeFileSync(fd, `${serializeSessionEntry(entry)}\n`);
+             }
+         }
+         finally {
+@@ -800,7 +817,7 @@ export class SessionManager {
+             const fd = openSync(this.sessionFile, "wx");
+             try {
+                 for (const e of this.fileEntries) {
+-                    writeFileSync(fd, `${JSON.stringify(e)}\n`);
++                    writeFileSync(fd, `${serializeSessionEntry(e)}\n`);
+                 }
+             }
+             finally {
+@@ -809,7 +826,7 @@ export class SessionManager {
+             this.flushed = true;
+         }
+         else {
+-            appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
++            appendFileSync(this.sessionFile, `${serializeSessionEntry(entry)}\n`);
+         }
+     }
+     _appendEntry(entry) {
+@@ -1403,11 +1420,11 @@ export class SessionManager {
+             cwd: resolvedTargetCwd,
+             parentSession: resolvedSourcePath,
+         };
+-        writeFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`, { flag: "wx" });
++        writeFileSync(newSessionFile, `${serializeSessionEntry(newHeader)}\n`, { flag: "wx" });
+         // Copy all non-header entries from source
+         for (const entry of sourceEntries) {
+             if (entry.type !== "session") {
+-                appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
++                appendFileSync(newSessionFile, `${serializeSessionEntry(entry)}\n`);
+             }
+         }
+         return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js
 index d5ce9cd..a456908 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js

package/src/cli/chat.ts

@@ -16,6 +16,7 @@ import { privacyDisabled } from "../config/privacyDisabled.ts"; // no Pi deps
 import type { GateController } from "../ext/permissionGate.ts"; // type-only → erased, safe pre-boot
 import { createUIContext } from "../ext/headlessUi.ts"; // no Pi deps → safe pre-boot
 import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts"; // node:child_process only → safe pre-boot
+import { transcriptSnapshot, type SnapshotEntry } from "../remote/transcriptSnapshot.ts"; // no deps → safe pre-boot
 
 // This lean REPL has no Pi TUI (and so no Theme), so it detects the terminal background
 // itself (COLORFGBG) and picks a palette — on a light terminal the standard "\x1b[33m"
@@ -181,7 +182,12 @@ async function main() {
     // the driver learns which folder they're driving without the OS username
     // crossing the relay.
     onControllerAttached: () => {
-      relay?.sendSnapshot([]);
+      // The session's transcript, so an app back from sleep catches up (transcriptSnapshot.ts).
+      {
+        let entries: SnapshotEntry[] = [];
+        try { entries = transcriptSnapshot(session?.sessionManager?.getBranch?.() ?? []); } catch { /* no session yet */ }
+        relay?.sendSnapshot(entries, { full: entries.length > 0, running: turnActive });
+      }
       relay?.sendContext({ model: currentSpec, cwd, version: agentVersion() });
       relay?.sendCommands(availableCommands());
     },

package/src/config/moatManifest.json

@@ -26,6 +26,7 @@
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
     { "entry": "extensions/privateer-truncation.ts", "name": "privateer-truncation", "note": "picks the task back up when a reply is cut off at the output limit" },
     { "entry": "extensions/privateer-fresh.ts", "name": "privateer-fresh", "note": "/fresh — replace the agent with a new one and stop everything it started" },
+    { "entry": "extensions/privateer-recovery.ts", "name": "privateer-recovery", "note": "crash recovery — the live marker the supervisor resumes from, the note that tells the model its last action may have half-run, and session-sealing warnings" },
     { "entry": "extensions/privateer-speak.ts", "name": "privateer-speak", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },
     { "entry": "extensions/privateer-web.ts", "name": "privateer-web", "note": "web_search/web_fetch — account search when signed in, else the user's own provider (rpiv-web-tools); crypto_lookup — account market data, in both cases" },
     { "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "name": "rpiv-ask-user-question", "note": "ask_user_question" },

package/src/config/whatsNew.json

@@ -1,10 +1,10 @@
 {
   "$comment": "The banner's What's New list, newest first: the two to four things a returning user should notice, not a changelog. `reviewedFor` is the release this list was last looked at for. A release can't ship until it equals package.json's version (scripts/check-whats-new.mjs, run by `npm test` and by release.yml before anything builds), so every release, patches included, is a deliberate look at this list. If nothing new is worth a line, bumping `reviewedFor` alone is the answer. `since` is the release an entry arrived in. `cmd` is shown in the accent colour.",
-  "reviewedFor": "0.15.4",
+  "reviewedFor": "0.15.5",
   "items": [
+    { "text": "If the agent crashes mid-task it comes back into your session, and saved sessions are now encrypted on disk", "since": "0.15.5" },
     { "text": "Slow images, speech and music run as background jobs — a dropped connection no longer loses a paid result", "since": "0.15.4" },
     { "text": "Driving from the app: a message sent mid-turn steers it, and questions survive a dropped link", "since": "0.15.1" },
-    { "text": "MCP on Pi's built-in support — sign OAuth connectors back in with", "cmd": "/mcp", "since": "0.15.0" },
-    { "text": "Sub-agents are back: hand work to bounded parallel agents", "since": "0.15.0" }
+    { "text": "MCP on Pi's built-in support — sign OAuth connectors back in with", "cmd": "/mcp", "since": "0.15.0" }
   ]
 }

package/src/remote/attentionPush.ts

@@ -0,0 +1,40 @@
+// "Your agent is asking you something" — a push to the account's phones when a
+// question (ask_user_question, a select, a text prompt) is put to an app that isn't
+// there to see it.
+//
+// A question sent up the relay only reaches a LIVE socket. A phone that backgrounded
+// a minute ago has none, so the question sat held on this machine (remoteBridge's
+// holdOpenQuestions) with nothing telling anyone it was waiting — the user found it
+// by chance, or after the hold ran out and the tool came back as an error.
+//
+// Content-free on purpose, like the Inbox nudge (server services/pushService.js): the
+// question itself never leaves the relay, so the push says only that one is waiting.
+// Fire-and-forget and throttled — a failed or skipped push must never touch the turn.
+
+const COOLDOWN_MS = 30_000;
+let lastAt = 0;
+let sink: (() => void) | null = null;
+
+export function requestAttentionPush(): void {
+  const now = Date.now();
+  if (now - lastAt < COOLDOWN_MS) return;
+  lastAt = now;
+  if (sink) return sink();
+  void (async () => {
+    try {
+      const { apiRequest, hasCredentials } = await import("../auth/privateer.ts");
+      if (!hasCredentials()) return;
+      await apiRequest("/api/push/attention", { method: "POST", signal: AbortSignal.timeout(10_000) });
+    } catch {
+      /* best effort — the question is still held and re-sent when the app comes back */
+    }
+  })();
+}
+
+/** Test seam: count pushes instead of sending them (null restores the real one), and
+ *  forget the cooldown. Tests run on machines that are signed in — without this a
+ *  bridge test would buzz the developer's phone. */
+export function setAttentionPushSink(fn: (() => void) | null): void {
+  sink = fn;
+  lastAt = 0;
+}

package/src/remote/liveTaskSession.ts

@@ -25,6 +25,7 @@ import { rememberAccountCredential, persistAccountCredential, dropPersistedAccou
 import { modelRegistryOf } from "../providers/piAuthStore.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
+import { transcriptSnapshot, type SnapshotEntry } from "./transcriptSnapshot.ts";
 import { AttachmentStore, type StoredAttachment } from "../util/attachmentStore.ts";
 import { spawnAccountCredentials, revokeAccountSession } from "../auth/privateer.ts";
 import { createUIContext } from "../ext/headlessUi.ts";
@@ -190,7 +191,12 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     onControllerAttached: () => {
       attached = true;
       if (attachTimer) { clearTimeout(attachTimer); attachTimer = undefined; }
-      relay?.sendSnapshot([]);
+      // The session's transcript, so an app back from sleep catches up (transcriptSnapshot.ts).
+      {
+        let entries: SnapshotEntry[] = [];
+        try { entries = transcriptSnapshot(session?.sessionManager?.getBranch?.() ?? []); } catch { /* no session yet */ }
+        relay?.sendSnapshot(entries, { full: entries.length > 0, running: turnActive });
+      }
       // cwd rides along here (and nowhere else — see RelayClient.sendContext): this
       // session's working directory was either named by the driver in the spawn form
       // or defaulted to the harbor's own, and they have no other way to see which.