privateer-agent 0.12.47 → 0.12.50

package/bin/headless-flags.mjs

@@ -0,0 +1,166 @@
+// The launcher's argv rules for HEADLESS runs and for Pi's own subcommands.
+//
+// Plain .mjs, like update-route.mjs, because bin/ runs under a bare `node` before any
+// transpiler exists — and separate from the launcher because the launcher runs on
+// import, so nothing inside it can be tested. See tests/headlessFlags.test.ts.
+
+/** Every tool that bills the account — mirrors BILLED_MEDIA_TOOLS in src/permissions/classify.ts. */
+export const BILLED_TOOLS = [
+  "generate_image",
+  "generate_video",
+  "generate_model",
+  "generate_sprite",
+  "generate_speech",
+  "generate_music",
+  "generate_sfx",
+];
+
+/** The env var carrying a `--allow-spend` grant from the launcher to the gate. */
+export const CLI_SPEND_ENV = "PRIVATEER_CLI_SPEND";
+/** The env var carrying `--approve-in-app` (its value is the timeout in ms). */
+export const APPROVE_IN_APP_ENV = "PRIVATEER_APPROVE_IN_APP";
+
+const DEFAULT_APPROVAL_TIMEOUT_SEC = 300;
+
+/** True when these args ask Pi for a one-shot, no-screen run. */
+export function isHeadlessRun(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break;
+    if (a === "-p" || a === "--print") return true;
+    if (a === "--mode" && args[i + 1] === "json") return true;
+    if (a === "--mode=json") return true;
+  }
+  return false;
+}
+
+function toolName(raw) {
+  const t = raw.trim();
+  if (!t) return null;
+  // `video` is accepted for `generate_video`: it is what a person types, and it is
+  // unambiguous. Anything else must be one of the billed tools, spelled out.
+  const full = t.startsWith("generate_") ? t : `generate_${t}`;
+  return BILLED_TOOLS.includes(full) ? full : null;
+}
+
+/**
+ * Pull the headless-run flags out of `args` (in place) and validate them together.
+ *
+ *   --allow-spend <tool[,tool…]>   pre-approve these billed tools for THIS run
+ *   --max-calls <n>                …at most n billed calls in total
+ *   --max-spend <usd>              …at most this much, estimated before each call
+ *   --approve-in-app               send approvals this run can't answer to the app
+ *   --approval-timeout <seconds>   how long to wait for the app (default 300)
+ *
+ * Returns `{ spend, approveInAppMs, error }`. `error` is a message for the user and
+ * means nothing else should be trusted. A spend grant must be capped (calls, dollars
+ * or both) and only exists for `-p` / `--mode json` runs — in the TUI a person
+ * approves each call, so there is nothing to pre-approve.
+ */
+export function extractHeadlessFlags(args) {
+  const tools = [];
+  let maxCalls;
+  let maxSpendUsd;
+  let approveInApp = false;
+  let timeoutSec;
+  let spendFlagSeen = false;
+
+  const take = (i, name) => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith("--")) return { error: `${name} needs a value` };
+    return { value: v };
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break;
+    const [flag, inline] = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, undefined];
+    if (!["--allow-spend", "--max-calls", "--max-spend", "--approve-in-app", "--approval-timeout"].includes(flag)) continue;
+
+    let value = inline;
+    let consumed = 1;
+    if (flag !== "--approve-in-app" && value === undefined) {
+      const t = take(i, flag);
+      if (t.error) return { error: t.error };
+      value = t.value;
+      consumed = 2;
+    }
+    args.splice(i, consumed);
+    i--;
+
+    if (flag === "--allow-spend") {
+      spendFlagSeen = true;
+      for (const raw of value.split(",")) {
+        const name = toolName(raw);
+        if (!name) {
+          return { error: `--allow-spend: "${raw.trim()}" is not a billed tool. Use one of: ${BILLED_TOOLS.join(", ")}` };
+        }
+        if (!tools.includes(name)) tools.push(name);
+      }
+    } else if (flag === "--max-calls") {
+      spendFlagSeen = true;
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1) return { error: `--max-calls must be a whole number of calls, 1 or more (got "${value}")` };
+      maxCalls = n;
+    } else if (flag === "--max-spend") {
+      spendFlagSeen = true;
+      const n = Number(String(value).replace(/^\$/, ""));
+      if (!Number.isFinite(n) || n <= 0) return { error: `--max-spend must be a dollar amount above 0, e.g. 1.00 (got "${value}")` };
+      maxSpendUsd = n;
+    } else if (flag === "--approve-in-app") {
+      approveInApp = true;
+    } else if (flag === "--approval-timeout") {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n < 10 || n > 3600) return { error: `--approval-timeout must be 10-3600 seconds (got "${value}")` };
+      timeoutSec = n;
+    }
+  }
+
+  const headless = isHeadlessRun(args);
+  if (spendFlagSeen) {
+    if (tools.length === 0) return { error: "--max-calls / --max-spend cap a spend grant — name the tools with --allow-spend <tool>" };
+    if (maxCalls === undefined && maxSpendUsd === undefined) {
+      return { error: "--allow-spend needs a cap: add --max-calls <n>, --max-spend <usd>, or both" };
+    }
+    if (!headless) {
+      return { error: "--allow-spend only applies to a headless run (-p / --print, or --mode json). In the terminal UI you approve each call yourself." };
+    }
+  }
+  if (timeoutSec !== undefined && !approveInApp) return { error: "--approval-timeout only applies with --approve-in-app" };
+  if (approveInApp && !headless) {
+    return { error: "--approve-in-app only applies to a headless run (-p / --print, or --mode json). An interactive terminal can use /remote-access." };
+  }
+
+  return {
+    spend: tools.length ? { tools, ...(maxCalls !== undefined ? { maxCalls } : {}), ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}) } : undefined,
+    approveInAppMs: approveInApp ? Math.round((timeoutSec ?? DEFAULT_APPROVAL_TIMEOUT_SEC) * 1000) : undefined,
+  };
+}
+
+// Pi's own subcommands. Pi recognizes each only as args[0], so the launcher must hand
+// them over with NOTHING in front — the normal launch prepends --model, -e and --skill,
+// which is exactly how `privateer auth check` used to become a chat message.
+export const PI_SUBCOMMANDS = ["auth", "install", "remove", "uninstall", "list", "config"];
+
+const AUTH_SUBCOMMANDS = ["check", "print-api-key", "print-bearer-token"];
+
+/**
+ * Is `args` an `auth` invocation Pi won't understand? Returns the message to print, or
+ * null. `status` is ours (answered by the launcher), `help`/--help are Pi's.
+ */
+export function authProblem(args, cmd = "privateer") {
+  if (args[0] !== "auth") return null;
+  const sub = args[1];
+  if (sub === undefined || sub === "help" || sub === "status" || args.includes("--help") || args.includes("-h")) return null;
+  if (AUTH_SUBCOMMANDS.includes(sub)) return null;
+  return [
+    `${cmd} auth: unknown command "${sub}".`,
+    "",
+    `  ${cmd} auth status                               is this machine signed in to Privateer?`,
+    `  ${cmd} auth check --provider <name>              are a provider's credentials ready?`,
+    `  ${cmd} auth print-api-key --provider <name>      print a provider's API key`,
+    `  ${cmd} auth print-bearer-token --provider <name> print a provider's bearer token`,
+    "",
+    `Nothing was sent to a model. To sign in, run \`${cmd}\` and type /login.`,
+  ].join("\n");
+}

package/bin/privateer-launch.mjs

@@ -29,7 +29,9 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 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/
@@ -158,11 +160,19 @@ const NO_QUARTER = args.some((a) => a === "--no-quarter");
 if (NO_QUARTER) {
   for (let i = args.length - 1; i >= 0; i--) if (args[i] === "--no-quarter") args.splice(i, 1);
   process.env.PRIVATEER_NO_QUARTER = "1";
+  // No quarter is also `/privacy off` (src/permissions/noQuarter.ts). Marked, unless the
+  // filter was already off, so shift+tab back to the moat restores it.
+  if (process.env.PRIVATEER_PRIVACY_OFF !== "1" && process.env.PI_PRIVACY_OFF !== "1") {
+    process.env.PRIVATEER_PRIVACY_OFF = "1";
+    process.env.PI_PRIVACY_OFF = "1";
+    process.env.PRIVATEER_PRIVACY_OFF_BY_NO_QUARTER = "1";
+  }
   process.stderr.write(
     [
       "",
-      "  ⚓ \x1b[1;31mNo quarter\x1b[0m — permission gate DISABLED for this session.",
-      "     Every action (shell, edits, destructive tools, out-of-cwd) runs WITHOUT a prompt.",
+      "  ⚓ \x1b[1;31mNo quarter\x1b[0m — permission gate AND privacy filter DISABLED for this session.",
+      "     Every action (shell, edits, destructive tools, out-of-cwd) runs WITHOUT a prompt,",
+      "     and outbound requests are not scanned for PII.",
       "     Only use this in a directory and with a task you fully trust.",
       "     shift+tab (or /no-quarter off) raises the moat again.",
       "",
@@ -178,6 +188,7 @@ if (NO_PRIVACY) {
   for (let i = args.length - 1; i >= 0; i--) if (args[i] === "--no-privacy" || args[i] === "--privacy-off") args.splice(i, 1);
   process.env.PRIVATEER_PRIVACY_OFF = "1";
   process.env.PI_PRIVACY_OFF = "1";
+  delete process.env.PRIVATEER_PRIVACY_OFF_BY_NO_QUARTER; // asked for outright — raising the moat keeps it off
   process.stderr.write(
     [
       "",
@@ -219,6 +230,25 @@ if (ALLOW_COMPUTER) {
   );
 }
 
+// Headless-run flags — spend pre-approval and app approvals for `-p` runs. Stripped
+// before Pi sees them, exactly like the flags above; grammar in bin/headless-flags.mjs.
+//
+// THE ENV IS OURS, NEVER THE SHELL'S. The grant reaches the gate as an env var (the only
+// channel into Pi's process), so an inherited value is deleted FIRST: a
+// PRIVATEER_CLI_SPEND left exported in someone's shell must never pre-approve a run
+// they didn't type the flag for. Only this invocation's argv can set it.
+delete process.env[CLI_SPEND_ENV];
+delete process.env[APPROVE_IN_APP_ENV];
+{
+  const headless = extractHeadlessFlags(args);
+  if (headless.error) {
+    process.stderr.write(`privateer: ${headless.error}\n`);
+    process.exit(2);
+  }
+  if (headless.spend) process.env[CLI_SPEND_ENV] = JSON.stringify(headless.spend);
+  if (headless.approveInAppMs) process.env[APPROVE_IN_APP_ENV] = String(headless.approveInAppMs);
+}
+
 const sub = args[0];
 
 // `privateer --version` — report OUR version, not Pi's. Left to Pi's cli.js it would
@@ -541,6 +571,98 @@ 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
+// auth list` was answered by the model, which listed the project folders in the
+// user's home directory. Hand them over bare instead, and refuse an `auth` Pi doesn't
+// know rather than let it become a prompt.
+else if (PI_SUBCOMMANDS.includes(sub)) {
+  const cmd = process.env.PRIVATEER_CMD || "privateer";
+  const problem = authProblem(args, cmd);
+  if (problem) {
+    process.stderr.write(problem + "\n");
+    process.exit(2);
+  }
+  if (sub === "auth" && args[1] === "status") {
+    printAuthStatus(cmd);
+    process.exit(0);
+  }
+  const CLI = resolveDep(REPO, "@earendil-works/pi-coding-agent", "dist", "cli.js");
+  if (!CLI || !fs.existsSync(CLI)) {
+    console.error(
+      "privateer: couldn't find pi-coding-agent — the install looks incomplete.\n" +
+        "  Try reinstalling: npm install -g privateer-agent@latest",
+    );
+    process.exit(1);
+  }
+  configureCompileCache(PRIVATEER_HOME); // same Pi module graph as a launch — reuse its compiled code
+  ensurePatches(); // project `.privateer/` config dirs are a patch; -l scope needs them
+  process.env.PI_CODING_AGENT_DIR = AGENT_DIR;
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  runToCompletion(NODE_BIN, [...nodeArgs, CLI, ...args]);
+}
+
 // --- normal launch: resolve the moat, then exec Pi's TUI with it -----------
 else {
   // Node 22 can reuse compiled code across launches instead of reparsing Pi and every
@@ -687,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}`] : [];
@@ -725,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 ---------------------------------------------------------------
@@ -872,6 +1004,28 @@ function warnKeylessLaunch() {
   process.stderr.write(lines.join("\n") + "\n");
 }
 
+// `privateer auth status` — the question people (and agents) actually ask, answered
+// from local state only: no network, nothing sent anywhere, and no secret printed.
+function printAuthStatus(cmd) {
+  let creds = null;
+  try {
+    creds = JSON.parse(fs.readFileSync(path.join(PRIVATEER_HOME, "credentials.json"), "utf8"));
+  } catch { /* absent or unreadable → signed out */ }
+  const lines = [];
+  if (creds && typeof creds.accessToken === "string") {
+    const who = creds.user?.email || "your account";
+    lines.push(`Privateer account: signed in as ${who}${creds.serverBaseUrl ? ` (${creds.serverBaseUrl})` : ""}`);
+    lines.push("  This checks the local login only; a session revoked from the app shows up on the next request.");
+  } else {
+    lines.push("Privateer account: not signed in");
+    lines.push(`  Run \`${cmd}\` and type /login, then approve the code in the Privateer app.`);
+  }
+  const keys = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY", "TINFOIL_API_KEY", "PRIVATEER_API_KEY"].filter(haveKey);
+  lines.push(`Provider keys in the environment: ${keys.length ? keys.join(", ") : "none"}`);
+  lines.push(`To check one provider end to end: ${cmd} auth check --provider <name>`);
+  console.log(lines.join("\n"));
+}
+
 function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
   console.log(
     [
@@ -886,12 +1040,14 @@ 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`,
       `  ${cmd} list                 List installed extensions from settings`,
       `  ${cmd} config               Open TUI to enable/disable package resources`,
-      `  ${cmd} auth <command>       Print credentials or check provider readiness`,
+      `  ${cmd} auth status          Show whether this machine is signed in`,
+      `  ${cmd} auth <command>       Check provider readiness or print credentials (check, print-api-key, print-bearer-token)`,
       `  ${cmd} <command> --help     Show help for a specific command`,
       "",
       "Options:",
@@ -902,6 +1058,12 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       "  --append-system-prompt <text>  Append text or file contents to the system prompt",
       "  --mode <mode>                  Output mode: text (default), json, or rpc",
       "  --print, -p                    Non-interactive mode: process prompt and exit",
+      "  --allow-spend <tools>          -p only: pre-approve billed tools for this run (e.g. generate_video)",
+      "  --max-calls <n>                …at most n billed calls (a cap is required)",
+      "  --max-spend <usd>              …at most this much, estimated before each call",
+      "  --approve-in-app               -p only: send approvals to the Privateer app instead of denying",
+      "  --approval-timeout <seconds>   How long --approve-in-app waits (default 300)",
+      "  --no-quarter                   Run with NO approval prompts at all (trusted tasks only)",
       "  --continue, -c                 Continue previous session",
       "  --resume, -r                   Select a session to resume",
       "  --session <path|id>            Use specific session file or partial UUID",

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");
+      }
+    },
+  });
+}