privateer-agent 0.12.49 → 0.12.50

package/README.md

@@ -688,6 +688,8 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/remote-access` | link this terminal to the app and allow it to drive (off by default) |
 | `/connect` · `/mcp` | add, enable, or remove MCP connectors / see what actually connected |
 | `/speak` · `/talk` | read answers aloud / voice input (**alt+t** is push-to-talk) |
+| `/mood` | pick a voice mood (focused, relaxed, hands-free, quiet, or your own; `/mood save <name>` keeps the current setup) |
+| `/fresh` | replace this agent with a new process: everything it started (dev servers, watchers, subagents) is stopped, and the new agent has no link to the old one (`/resume` still reaches the old session). Saying "fresh start" does the same |
 | `/extensions` | list loaded Pi extensions |
 | `/web-tools` | point `web_search`/`web_fetch` at a search provider of your own (signed in, they already work on your account) |
 | `/init` | scaffold a starter `PRIVATEER.md` in this directory |
@@ -695,6 +697,8 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |
 
 Shell subcommands: `privateer` (interactive), `privateer update`, `privateer harbor …`,
+`privateer fresh [n]` (swap a running terminal's agent from another terminal, even when that
+agent is stuck),
 `privateer acp` (serve the agent to an ACP host like Buzz or Zed — see
 [`docs/acp.md`](docs/acp.md)), `privateer auth status` (is this machine signed in?),
 `privateer -p … [--allow-spend …] [--approve-in-app]` (see

package/bin/fresh-supervisor.d.mts

@@ -0,0 +1,35 @@
+// Types for the fresh-agent supervisor. Same reason as run-to-completion.d.mts: bin/
+// runs under a bare `node` before any transpiler exists, but the /fresh extension and
+// the tests that pin the reaping and arg-filtering are TypeScript.
+
+export const FRESH_GRACE_MS: number;
+export const FRESH_SOCKET_ENV: "PRIVATEER_FRESH_SOCKET";
+export const FRESH_TOKEN_ENV: "PRIVATEER_FRESH_TOKEN";
+
+export interface PsRow {
+  pid: number;
+  ppid: number;
+  pgid: number;
+}
+
+/** A supervised terminal, as registered in PRIVATEER_HOME/run/<pid>.json. */
+export interface TerminalEntry {
+  pid: number;
+  childPid?: number;
+  socket: string;
+  token: string;
+  cwd: string;
+  startedAt: number;
+}
+
+export function parsePs(text: string): PsRow[];
+/** The root, its descendants, and every member of a group a descendant leads —
+ *  never the supervisor's own group (`protectPgid`) as a group. */
+export function collectTree(rows: PsRow[], rootPid: number, protectPgid?: number): { pids: number[]; groups: number[] };
+/** The user's launch args minus session selection, the initial prompt and @files. */
+export function filterRespawnArgs(args: string[]): string[];
+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;

package/bin/fresh-supervisor.mjs

@@ -0,0 +1,419 @@
+/**
+ * Fresh agent: the launcher stays up as the TUI's supervisor, so a terminal can swap its
+ * agent for a brand-new PROCESS without the user relaunching anything.
+ *
+ * WHY A PROCESS, NOT A SESSION. Pi's own /new (and an extension's ctx.newSession()) runs
+ * in the same process. That is the wrong tool for both reasons this exists:
+ *  - GARBAGE COLLECTION. A TUI can wedge, leak, or leave a pile of children behind (dev
+ *    servers, watchers, subagents). A new session inherits all of it; a new process
+ *    inherits none of it, because the old tree is reaped first.
+ *  - ISOLATION. A subagent is a child its parent knows about. A fresh agent is not: it
+ *    gets a new session file, no --continue, and nothing linking it to the one before.
+ *
+ * WHY THE LAUNCHER. It already sits above the TUI (runToCompletion), shares its
+ * terminal, and is the one process that stays responsive when the agent does not. A
+ * jammed agent can't run its own /fresh, voice command or hotkey — they all live on the
+ * event loop that is jammed — so the rescue has to come from outside it.
+ *
+ * THE CONTROL CHANNEL. Each supervised terminal listens on a local socket (a unix socket
+ * under PRIVATEER_HOME/run, a named pipe on Windows) and registers itself in
+ * PRIVATEER_HOME/run/<launcherPid>.json. Anything that knows the socket AND the random
+ * per-launch token can ask for a fresh agent: the /fresh command inside the TUI (handed
+ * both through the environment) and `privateer fresh` from another terminal (reads them
+ * from the 0600 registry file). The token is what stops another local user from
+ * restarting your agent through a pipe whose default ACL they can open.
+ *
+ * REAPING, AND WHY IT SNAPSHOTS FIRST. Pi's bash tool spawns every command detached
+ * (its own process group) on unix. The moment the TUI dies, those are reparented to init
+ * and the parent→child link that says "this dev server belonged to that agent" is gone.
+ * So the tree is read BEFORE anything is signalled: every descendant by ppid, plus every
+ * process in a group one of them leads (which catches a grandchild whose own parent
+ * already exited). SIGTERM first — Pi shuts down cleanly on it — then SIGKILL whatever
+ * is left after the grace period. The launcher's own process group is never signalled as
+ * a group: the TUI shares it (it's the terminal's foreground group), and so does the
+ * launcher. Windows keeps no process groups worth using here; `taskkill /T` walks the
+ * tree while it is still intact.
+ *
+ * Not caught: a process that double-forked AND called setsid on its own (a classic
+ * daemon) before the snapshot. It has left both the tree and the group, and nothing short
+ * of guessing by name would find it.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+const isWin = process.platform === "win32";
+
+/** How long the old agent gets to exit on SIGTERM before it is killed outright. */
+export const FRESH_GRACE_MS = 3000;
+
+/** Env the TUI (and so /fresh) receives: where its supervisor listens, and the key. */
+export const FRESH_SOCKET_ENV = "PRIVATEER_FRESH_SOCKET";
+export const FRESH_TOKEN_ENV = "PRIVATEER_FRESH_TOKEN";
+
+// ── process tree (pure, tested) ─────────────────────────────────────────────
+
+/** Parse `ps -A -o pid=,ppid=,pgid=` output into rows. Junk lines are skipped. */
+export function parsePs(text) {
+  const rows = [];
+  for (const line of String(text).split("\n")) {
+    const [pid, ppid, pgid] = line.trim().split(/\s+/).map(Number);
+    if (Number.isInteger(pid) && Number.isInteger(ppid) && Number.isInteger(pgid) && pid > 0) {
+      rows.push({ pid, ppid, pgid });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Everything to stop when `rootPid` is replaced: the root, all its descendants, and
+ * every member of a process group a descendant leads. `protectPgid` is the supervisor's
+ * own group — never signalled as a group, and members of it are only included when they
+ * are real descendants of the root.
+ *
+ * Returns { pids, groups }: `groups` are signalled as -pgid (catching members we never
+ * saw), `pids` individually.
+ */
+export function collectTree(rows, rootPid, protectPgid) {
+  const kids = new Map();
+  for (const r of rows) {
+    if (!kids.has(r.ppid)) kids.set(r.ppid, []);
+    kids.get(r.ppid).push(r);
+  }
+  const byPid = new Map(rows.map((r) => [r.pid, r]));
+  const pids = new Set([rootPid]);
+  const queue = [rootPid];
+  while (queue.length) {
+    const p = queue.shift();
+    for (const c of kids.get(p) ?? []) {
+      if (!pids.has(c.pid)) {
+        pids.add(c.pid);
+        queue.push(c.pid);
+      }
+    }
+  }
+  const groups = new Set();
+  for (const p of pids) {
+    const g = byPid.get(p)?.pgid;
+    if (g && g !== protectPgid && g > 1) groups.add(g);
+  }
+  // Orphans still in one of those groups: their parent exited before the snapshot, but
+  // they are the same job and would otherwise outlive the agent that started it.
+  for (const r of rows) if (groups.has(r.pgid)) pids.add(r.pid);
+  return { pids: [...pids], groups: [...groups] };
+}
+
+/**
+ * The user's own launch args, minus what would tie the new agent to the old one or
+ * replay what it was told: session selection (--continue, --resume, --session,
+ * --session-id, --fork, --name), the initial prompt, and @file attachments. Everything
+ * about HOW to run stays — model, key, tools, posture flags like --no-quarter or
+ * --allow-computer-control — because the user chose those for this terminal, and a
+ * fresh agent that silently changed its permissions would be a different surprise.
+ *
+ * Walks the args with Pi's own grammar (dist/cli/args.js), because arity is the whole
+ * problem: dropping a positional is only safe if we know it isn't the value of the flag
+ * before it. Pi's rule for a flag it doesn't know (every extension flag) is to take the
+ * next arg as its value unless it starts with "-" or "@"; so is ours.
+ */
+const DROP_BOOL = new Set(["-c", "--continue", "-r", "--resume"]);
+const DROP_VALUE = new Set(["--session", "--session-id", "--fork", "--name", "-n"]);
+const KEEP_BOOL = new Set([
+  "--no-session", "--no-tools", "--no-builtin-tools", "--print", "--no-extensions", "--no-skills",
+  "--no-prompt-templates", "--no-themes", "--no-context-files", "--verbose", "--approve",
+  "--no-approve", "--offline", "--help", "--version",
+]);
+const KEEP_VALUE = new Set([
+  "--mode", "--provider", "--model", "--api-key", "--system-prompt", "--append-system-prompt",
+  "--session-dir", "--models", "--tools", "-t", "--exclude-tools", "-xt", "--thinking",
+  "--export", "--extension", "-e", "--skill", "--prompt-template", "--theme", "--use-theme",
+  "--tui-mode",
+]);
+export function filterRespawnArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break; // everything after is message text
+    if (DROP_BOOL.has(a)) continue;
+    if (DROP_VALUE.has(a)) {
+      i++;
+      continue;
+    }
+    if (KEEP_VALUE.has(a)) {
+      if (i + 1 < args.length) out.push(a, args[++i]);
+      continue;
+    }
+    if (KEEP_BOOL.has(a)) {
+      out.push(a);
+      continue;
+    }
+    if (a.startsWith("@")) continue; // file attachment for the old first prompt
+    if (a.startsWith("--") && !a.includes("=")) {
+      const next = args[i + 1];
+      out.push(a);
+      if (next !== undefined && !next.startsWith("-") && !next.startsWith("@")) out.push(args[++i]);
+      continue;
+    }
+    if (a.startsWith("-")) {
+      out.push(a); // --flag=value, or a short bool Pi knows
+      continue;
+    }
+    // A bare word is an initial message: that was the OLD agent's task.
+  }
+  return out;
+}
+
+// ── registry + socket paths ─────────────────────────────────────────────────
+
+export function runDir(home) {
+  return path.join(home, "run");
+}
+
+function socketPath(home, token) {
+  const id = `${process.pid}-${token.slice(0, 8)}`;
+  if (isWin) return `\\\\.\\pipe\\privateer-fresh-${id}`;
+  // sun_path is ~104 bytes on macOS; a long PRIVATEER_HOME (a dev home inside a repo)
+  // can overflow it, and listen() then fails with a confusing EINVAL.
+  const preferred = path.join(runDir(home), `${id}.sock`);
+  return Buffer.byteLength(preferred) < 100 ? preferred : path.join(os.tmpdir(), `pv-fresh-${id}.sock`);
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+};
+
+/** Every supervised terminal still running, oldest first. Stale entries are removed. */
+export function listTerminals(home) {
+  const dir = runDir(home);
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => /^\d+\.json$/.test(n));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const n of names) {
+    const file = path.join(dir, n);
+    try {
+      const t = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (alive(t.pid)) {
+        out.push(t);
+        continue;
+      }
+      // A supervisor that died by signal (its terminal closed) never ran its exit
+      // cleanup; its entry and socket are cleared by whoever looks next.
+      fs.rmSync(file, { force: true });
+      if (!isWin && typeof t.socket === "string" && t.socket.endsWith(".sock")) fs.rmSync(t.socket, { force: true });
+    } catch {
+      /* half-written or unreadable — not ours to act on */
+    }
+  }
+  return out.sort((a, b) => a.startedAt - b.startedAt);
+}
+
+// ── client ──────────────────────────────────────────────────────────────────
+
+/** Ask one supervisor for a fresh agent. Resolves with its reply, rejects on no answer. */
+export function requestFresh(socket, token, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    const conn = net.createConnection(socket);
+    let buf = "";
+    const timer = setTimeout(() => {
+      conn.destroy();
+      reject(new Error("the terminal didn't answer"));
+    }, timeoutMs);
+    conn.on("connect", () => conn.write(JSON.stringify({ op: "fresh", token }) + "\n"));
+    conn.on("data", (d) => {
+      buf += d;
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+      clearTimeout(timer);
+      conn.end();
+      try {
+        const reply = JSON.parse(buf.slice(0, nl));
+        reply.ok ? resolve(reply) : reject(new Error(reply.error || "refused"));
+      } catch {
+        reject(new Error("unreadable reply"));
+      }
+    });
+    conn.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+
+// ── supervisor ──────────────────────────────────────────────────────────────
+
+/** Put a terminal a killed TUI left in raw mode / hidden cursor / paste mode back. */
+function resetTerminal() {
+  if (!process.stdout.isTTY) return;
+  if (!isWin) spawnSync("stty", ["sane"], { stdio: ["inherit", "ignore", "ignore"] });
+  // 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.
+  process.stdout.write("\x1b[?25h\x1b[?1049l\x1b[?2004l\x1b[<u\x1b[0m\x1b[2J\x1b[3J\x1b[H");
+}
+
+function snapshotTree(rootPid) {
+  if (isWin) return null;
+  const r = spawnSync("ps", ["-A", "-o", "pid=,ppid=,pgid="], { encoding: "utf8" });
+  if (r.status !== 0) return { pids: [rootPid], groups: [] };
+  const rows = parsePs(r.stdout);
+  const self = rows.find((x) => x.pid === process.pid);
+  return collectTree(rows, rootPid, self?.pgid);
+}
+
+function signalTree(tree, sig) {
+  for (const g of tree.groups) {
+    try {
+      process.kill(-g, sig);
+    } catch {
+      /* group already gone */
+    }
+  }
+  for (const p of tree.pids) {
+    try {
+      process.kill(p, sig);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Stop the agent and everything it started. Resolves with how many processes that was. */
+async function reap(child) {
+  if (isWin) {
+    spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    return 1;
+  }
+  const tree = snapshotTree(child.pid);
+  signalTree(tree, "SIGTERM");
+  const deadline = Date.now() + FRESH_GRACE_MS;
+  while (Date.now() < deadline && tree.pids.some(alive)) await new Promise((r) => setTimeout(r, 50));
+  const survivors = { pids: tree.pids.filter(alive), groups: tree.groups };
+  if (survivors.pids.length) signalTree(survivors, "SIGKILL");
+  return tree.pids.length;
+}
+
+/**
+ * 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.
+ */
+export function runSupervised(cmd, buildArgs, { home }) {
+  const token = crypto.randomBytes(24).toString("hex");
+  const dir = runDir(home);
+  const regFile = path.join(dir, `${process.pid}.json`);
+  const sock = socketPath(home, token);
+  let child = null;
+  let replacing = false;
+  let registered = false;
+
+  const register = () => {
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      const entry = { pid: process.pid, childPid: child?.pid, socket: sock, token, cwd: process.cwd(), startedAt: Date.now() };
+      fs.writeFileSync(regFile, JSON.stringify(entry) + "\n", { mode: 0o600 });
+      registered = true;
+    } catch {
+      /* no registry means `privateer fresh` can't find this terminal; /fresh still works */
+    }
+  };
+  const unregister = () => {
+    if (registered) fs.rmSync(regFile, { force: true });
+    if (!isWin) fs.rmSync(sock, { force: true });
+  };
+
+  const launch = (first) => {
+    child = spawn(cmd, buildArgs(first), {
+      stdio: "inherit",
+      env: { ...process.env, [FRESH_SOCKET_ENV]: sock, [FRESH_TOKEN_ENV]: token },
+    });
+    child.on("exit", (code, signal) => {
+      if (replacing) return;
+      server.close();
+      unregister();
+      if (signal) process.kill(process.pid, signal);
+      else process.exit(code ?? 0);
+    });
+    child.on("error", (e) => {
+      console.error(`privateer: failed to launch — ${e.message}`);
+      unregister();
+      process.exit(1);
+    });
+    register();
+  };
+
+  const replace = async () => {
+    if (replacing || !child) return;
+    replacing = true;
+    const old = child;
+    const exited = new Promise((r) => (old.exitCode !== null || old.signalCode !== null ? r() : old.once("exit", r)));
+    const count = await reap(old);
+    await exited;
+    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`);
+    replacing = false;
+    launch(false);
+  };
+
+  const server = net.createServer((conn) => {
+    let buf = "";
+    conn.on("data", (d) => {
+      buf += d;
+      if (buf.length > 4096) return conn.destroy();
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+      let msg = null;
+      try {
+        msg = JSON.parse(buf.slice(0, nl));
+      } catch {
+        /* falls through to refusal */
+      }
+      const given = Buffer.from(String(msg?.token ?? ""));
+      const want = Buffer.from(token);
+      const authed = given.length === want.length && crypto.timingSafeEqual(given, want);
+      if (!authed || msg?.op !== "fresh") {
+        conn.end(JSON.stringify({ ok: false, error: authed ? "unknown op" : "bad token" }) + "\n");
+        return;
+      }
+      // Answer BEFORE reaping: when /fresh asked, the asker is the process about to die.
+      conn.end(JSON.stringify({ ok: true, pid: process.pid }) + "\n");
+      void replace();
+    });
+    conn.on("error", () => {});
+  });
+  server.on("error", () => {
+    /* no control channel — the TUI still runs, only fresh-agent is unavailable */
+  });
+
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    /* socketPath falls back to tmpdir only on length; an unwritable home just fails listen */
+  }
+  if (!isWin) fs.rmSync(sock, { force: true });
+  const oldMask = isWin ? 0 : process.umask(0o077); // socket file created 0600
+  server.listen(sock, () => {
+    if (!isWin) process.umask(oldMask);
+  });
+  // listen() binds synchronously enough for the umask window; restore on failure too.
+  server.once("error", () => {
+    if (!isWin) process.umask(oldMask);
+  });
+  server.unref();
+
+  process.on("exit", unregister);
+  launch(true);
+}

package/bin/privateer-launch.mjs

@@ -31,6 +31,7 @@ import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 import { routeUpdate } from "./update-route.mjs";
 import { APPROVE_IN_APP_ENV, CLI_SPEND_ENV, PI_SUBCOMMANDS, authProblem, extractHeadlessFlags } from "./headless-flags.mjs";
 import { runToCompletion } from "./run-to-completion.mjs";
+import { filterRespawnArgs, listTerminals, requestFresh, runSupervised } from "./fresh-supervisor.mjs";
 import { configureCompileCache } from "./startup-cache.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
@@ -570,6 +571,66 @@ else if (sub === "acp") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-acp.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
+// --- `privateer fresh [n|pid] [--list]` --------------------------------------
+// Swap a running terminal's agent for a brand-new process, reaping everything the old
+// one started. This is the rescue path: an agent that has jammed can't run its own
+// /fresh, so you run this from another terminal. See bin/fresh-supervisor.mjs.
+else if (sub === "fresh") {
+  const cmd = process.env.PRIVATEER_CMD || "privateer";
+  const rest = args.slice(1);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(
+      [
+        `${cmd} fresh — replace a running terminal's agent with a new one.`,
+        "",
+        `  ${cmd} fresh            the only running terminal`,
+        `  ${cmd} fresh <n|pid>    one of several — pick from the list`,
+        `  ${cmd} fresh --list     show running terminals`,
+        "",
+        "The old agent and every process it started are stopped; the new one starts in",
+        "the same terminal with a new session and no link to the old one. Inside a",
+        "terminal, /fresh does the same. The old session stays resumable with /resume.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+  const terms = listTerminals(PRIVATEER_HOME);
+  const describe = (t, i) =>
+    `  ${i + 1}. ${t.cwd}  (pid ${t.pid}, up ${Math.max(1, Math.round((Date.now() - t.startedAt) / 60000))}m)`;
+  if (rest.includes("--list")) {
+    console.log(terms.length ? terms.map(describe).join("\n") : "No running Privateer terminals.");
+    process.exit(0);
+  }
+  const pick = rest.find((a) => !a.startsWith("-"));
+  let target;
+  if (pick) {
+    const n = Number(pick);
+    target = terms.find((t) => t.pid === n) ?? (Number.isInteger(n) && n >= 1 ? terms[n - 1] : undefined);
+    if (!target) {
+      console.error(`${cmd} fresh: no running terminal "${pick}" — ${cmd} fresh --list shows them.`);
+      process.exit(1);
+    }
+  } else if (terms.length === 1) {
+    target = terms[0];
+  } else if (terms.length === 0) {
+    console.error("No running Privateer terminals.");
+    process.exit(1);
+  } else {
+    console.error(`Several Privateer terminals are running — pick one:\n${terms.map(describe).join("\n")}\n\n  ${cmd} fresh <n>`);
+    process.exit(2);
+  }
+  requestFresh(target.socket, target.token).then(
+    () => {
+      console.log(`Fresh agent starting in ${target.cwd}.`);
+      process.exit(0);
+    },
+    (e) => {
+      console.error(`${cmd} fresh: ${e.message}`);
+      process.exit(1);
+    },
+  );
+}
+
 // --- Pi's own subcommands: `auth`, and the package commands -------------------
 // Pi matches these only as args[0]. The normal launch below prepends --model, -e and
 // --skill, so every one of them used to fall through as a CHAT MESSAGE — `privateer
@@ -748,19 +809,24 @@ else {
   //   3. a saved pick in settings.json → pass NO flag; Pi resolves it itself (and
   //      falls back sanely if that model has vanished from the registry)
   //   4. nothing saved (first run / fresh home) → the computed MODEL above
-  const userPassedModel = args.includes("--model");
-  let savedDefault = null;
-  try {
-    const s = JSON.parse(fs.readFileSync(path.join(AGENT_DIR, "settings.json"), "utf8"));
-    if (
-      typeof s.defaultProvider === "string" && s.defaultProvider.trim() &&
-      typeof s.defaultModel === "string" && s.defaultModel.trim()
-    ) {
-      savedDefault = `${s.defaultProvider}/${s.defaultModel}`;
-    }
-  } catch { /* absent/unreadable → no saved pick */ }
-  const modelArgs =
-    userPassedModel || (savedDefault && !process.env.PRIVATEER_MODEL) ? [] : ["--model", MODEL];
+  //
+  // A FUNCTION, called per launch: a fresh agent (bin/fresh-supervisor.mjs) re-reads it,
+  // so a model picked in the old session boots the new one instead of being stomped by
+  // a first-run --model computed before that pick existed.
+  const modelArgsFor = (launchArgs) => {
+    const userPassedModel = launchArgs.includes("--model");
+    let savedDefault = null;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(AGENT_DIR, "settings.json"), "utf8"));
+      if (
+        typeof s.defaultProvider === "string" && s.defaultProvider.trim() &&
+        typeof s.defaultModel === "string" && s.defaultModel.trim()
+      ) {
+        savedDefault = `${s.defaultProvider}/${s.defaultModel}`;
+      }
+    } catch { /* absent/unreadable → no saved pick */ }
+    return userPassedModel || (savedDefault && !process.env.PRIVATEER_MODEL) ? [] : ["--model", MODEL];
+  };
 
   // Dev convenience: load provider keys from the repo's .env if present.
   const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
@@ -786,7 +852,12 @@ else {
   const splash = path.join(HERE, "privateer-splash.mjs");
   if (!isNonInteractive && fs.existsSync(splash)) nodeArgs.push("--import", pathToFileURL(splash).href);
 
-  runToCompletion(NODE_BIN, [...nodeArgs, CLI, ...modelArgs, ...extArgs, ...skillArgs, ...args]);
+  // 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];
+  if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args));
+  else runSupervised(NODE_BIN, (first) => tuiArgs(first ? args : filterRespawnArgs(args)), { home: PRIVATEER_HOME });
 }
 
 // --- helpers ---------------------------------------------------------------
@@ -969,6 +1040,7 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       `  ${cmd} harbor <command>     Manage the resident background Harbor daemon (run/install/uninstall/status)`,
       `  ${cmd} verify               Check local installation integrity and patch state`,
       `  ${cmd} acp                  Run as an Agent Client Protocol server (JSON-RPC on stdio)`,
+      `  ${cmd} fresh [n]            Replace a running terminal's agent with a new one (stops everything it started)`,
       `  ${cmd} install <source>     Install extension source and add to settings`,
       `  ${cmd} remove <source>      Remove extension source from settings`,
       `  ${cmd} uninstall <source>   Alias for remove`,

package/extensions/privateer-fresh.ts

@@ -0,0 +1,59 @@
+// /fresh — replace this agent with a brand-new one, in the same terminal.
+//
+// Not /new. Pi's /new starts a new session inside THIS process: whatever has wedged,
+// leaked or been left running (a dev server, a watcher, a subagent) comes along. /fresh
+// asks the launcher above us (bin/fresh-supervisor.mjs) to stop this process and every
+// process it started, then boot a new agent with a new session and nothing linking it
+// to this one. The session file stays on disk, so /resume can still bring it back.
+//
+// It runs immediately, with no confirmation, because nothing is lost that /resume
+// can't bring back — except the processes it reaps, which is the point.
+//
+// Only a terminal started by `privateer` has a supervisor. The desktop app, the harbor,
+// ACP and subagent children don't, and they say so instead of failing quietly. A jammed
+// agent can't run this at all — its event loop is the thing that's stuck — which is
+// what `privateer fresh` from another terminal is for.
+//
+// Voice: extensions/privateer-speak.ts maps a few spoken phrases ("fresh start", …)
+// onto this command.
+
+import { FRESH_SOCKET_ENV, FRESH_TOKEN_ENV, requestFresh } from "../bin/fresh-supervisor.mjs";
+
+// Read once, then taken out of this process's environment: every bash command and
+// subagent the agent runs inherits process.env, and none of them has any business
+// holding the key that restarts this terminal (and kills whatever it's running).
+// Kept on globalThis rather than in a module variable because /reload and a new
+// session re-run this factory, possibly through a fresh module instance, and by then
+// the environment no longer has it.
+const KEY = Symbol.for("privateer.fresh.launcher");
+function launcherKey(): { socket?: string; token?: string } {
+  const g = globalThis as any;
+  if (!g[KEY]) {
+    g[KEY] = { socket: process.env[FRESH_SOCKET_ENV], token: process.env[FRESH_TOKEN_ENV] };
+    delete process.env[FRESH_SOCKET_ENV];
+    delete process.env[FRESH_TOKEN_ENV];
+  }
+  return g[KEY];
+}
+
+export default function privateerFresh(pi: any): void {
+  const { socket, token } = launcherKey();
+
+  pi.registerCommand?.("fresh", {
+    description: "Replace this agent with a new one — stops everything it started, keeps the session for /resume",
+    handler: async (_args: string, ctx: any) => {
+      const notify = (m: string, kind: "info" | "warning" | "error" = "info") => ctx?.ui?.notify?.(m, kind);
+      if (!socket || !token) {
+        notify("/fresh needs a terminal started with `privateer` — this session has no launcher to hand over to. /new starts a new session in place.", "warning");
+        return;
+      }
+      notify("Starting a fresh agent…");
+      try {
+        await requestFresh(socket, token);
+        // The launcher now stops this process; nothing more to do here.
+      } catch (e) {
+        notify(`Couldn't reach the launcher (${e instanceof Error ? e.message : String(e)}). /new starts a new session in place.`, "error");
+      }
+    },
+  });
+}

package/extensions/privateer-speak.ts

@@ -120,5 +120,16 @@ export default function privateerSpeak(pi: any): void {
   // with the generic package keeps two independent setups instead of a fought-over
   // file. globalDir() is read here, not at module load, so PRIVATEER_HOME set around
   // session creation (tests, the daemon) is honoured.
-  makePiSpeakExtension({ configFile: join(globalDir(), "speak.json") })(pi);
+  //
+  // voiceCommands: saying one of these AS THE WHOLE UTTERANCE runs /fresh (see
+  // extensions/privateer-fresh.ts) instead of sending the words to the model. Whole
+  // utterance only, so "why did the fresh start fail" is still a question.
+  makePiSpeakExtension({ configFile: join(globalDir(), "speak.json"), voiceCommands: VOICE_COMMANDS })(pi);
 }
+
+const VOICE_COMMANDS: Record<string, string> = {
+  "fresh start": "/fresh",
+  "start fresh": "/fresh",
+  "fresh agent": "/fresh",
+  "new agent": "/fresh",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.49",
+  "version": "0.12.50",
   "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",
@@ -86,7 +86,7 @@
     "pi-privacy": "0.14.1",
     "pi-subagents": "0.70.0",
     "picomatch": "4.0.5",
-    "privateer-speak": "0.2.2",
+    "privateer-speak": "0.3.0",
     "privateer-workflow": "0.1.0",
     "tinfoil": "1.1.11",
     "tsx": "4.23.0",

package/src/config/moatManifest.json

@@ -22,6 +22,7 @@
     { "entry": "extensions/privateer-desktop.ts", "name": "privateer-desktop", "note": "/desktop — open the Privateer desktop app" },
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
+    { "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-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)" },
     { "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "name": "rpiv-ask-user-question", "note": "ask_user_question" },