privateer-agent 0.12.7 → 0.12.8

package/bin/privateer-launch.mjs

@@ -26,8 +26,9 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
+import { routeUpdate } from "./update-route.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
 const REPO = path.resolve(HERE, "..");
@@ -202,10 +203,9 @@ function updateNpmPackage() {
   });
 }
 
-// --- `privateer update` ----------------------------------------------------
-// Fetch the latest release and exit. Bundle installs re-run the download+extract
-// installer; npm installs update the global package.
-if (sub === "update") {
+// Update the CLI itself: fetch the latest release and exit. Bundle installs re-run the
+// download+extract installer; npm installs update the global package.
+function updateSelf() {
   if (BUNDLED) {
     // PRIVATEER_UPDATE=1 flips the installer into update mode: weigh-anchor banner,
     // "X → Y" version reporting, and an early exit (no download) when already current.
@@ -222,6 +222,67 @@ if (sub === "update") {
   // both paths exit via their child's exit handler.
 }
 
+// Update TOOL PACKS (Pi "packages": npm/git sources contributing extensions, skills,
+// prompts, themes) by handing the job to Pi's package-manager CLI, which owns npm/git
+// installs, scopes and project trust. `then` runs only on a clean exit — that's how
+// `--all` chains packs → self without either half being silently skipped.
+//
+// PI_CODING_AGENT_DIR is NOT optional here: without it Pi resolves the agent dir to a
+// standalone ~/.pi/agent and would update packages belonging to a different install
+// entirely, leaving the Privateer terminal's own packs untouched (and reporting success).
+function updatePacks(cliArgs, then) {
+  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);
+  }
+  ensurePatches(); // project `.privateer/` config dirs are a patch; -l scope needs them
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  const env = { ...process.env, PI_CODING_AGENT_DIR: AGENT_DIR };
+  const child = spawn(NODE_BIN, [...nodeArgs, CLI, "update", ...cliArgs], { stdio: "inherit", env });
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else if (code === 0 && then) then();
+    else process.exit(code ?? 0);
+  });
+  child.on("error", (e) => {
+    console.error(`privateer: failed to launch the package manager — ${e.message}`);
+    process.exit(1);
+  });
+}
+
+// --- `privateer update [--extensions | --all | <pack>]` --------------------
+// Two different things wear the same verb — the CLI itself and the tool packs — so the
+// grammar and the reasoning behind it live in bin/update-route.mjs, next to its test.
+// Tool packs can also be updated from inside a running terminal with /update, with no
+// restart at all; see extensions/privateer-update.ts.
+if (sub === "update") {
+  const rest = args.slice(1);
+  const route = routeUpdate(rest);
+  if (route === "help") {
+    const cmd = process.env.PRIVATEER_CMD || "privateer";
+    console.log(
+      [
+        `${cmd} update — fetch the latest release, or newer tool packs.`,
+        "",
+        `  ${cmd} update                  update the Privateer CLI itself`,
+        `  ${cmd} update --extensions     update every installed tool pack`,
+        `  ${cmd} update <pack>           update one pack (npm name or git URL)`,
+        `  ${cmd} update --all            tool packs, then the CLI`,
+        "",
+        "Inside a running terminal, /update fetches tool packs in place — no restart.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+  if (route === "all") updatePacks(["--extensions"], updateSelf);
+  else if (route === "packs") updatePacks(rest);
+  else updateSelf();
+}
+
 // --- `privateer harbor [run|install|uninstall|status]` ---------------------
 // The resident background harbor (routines + app-driven headless task spawns). Boots
 // straight into src/harbor via bin/privateer-harbor.mjs — the harbor loads the moat as
@@ -402,6 +463,15 @@ else {
 
   // Dev convenience: load provider keys from the repo's .env if present.
   const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+
+  // 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.
+  // TUI branch only: harbor/acp/subagent children have no terminal to animate on (and
+  // acp's stdout is a JSON-RPC stream). pathToFileURL, not the bare path — a Windows
+  // absolute path reads as the URL scheme "d:"; see bin/privateer.mjs for the same trap.
+  const splash = path.join(HERE, "privateer-splash.mjs");
+  if (fs.existsSync(splash)) nodeArgs.push("--import", pathToFileURL(splash).href);
+
   runToCompletion(NODE_BIN, [...nodeArgs, CLI, ...modelArgs, ...extArgs, ...skillArgs, ...args]);
 }
 

package/bin/privateer-splash.mjs

@@ -0,0 +1,247 @@
+// Boot splash — the wave that runs while Pi's TUI is still coming up.
+//
+// WHY THIS EXISTS. A cold `privateer` measured ~30s between the shell prompt and the
+// first painted frame, all of it silent:
+//
+//   0.1s   launcher banner (the login/keyless notice) — the last thing the user sees
+//   ~11s   Pi's own module graph loads (bare `pi` with zero extensions costs this)
+//   ~19s   …plus the 16 moat/tool-pack extensions we pass as `-e`
+//   ~30s   session_start handlers finish and the TUI paints its first frame
+//
+// Worse than the wait is its shape: Pi enables raw mode and HIDES THE CURSOR at the
+// ~19s mark, so the last third is a terminal with no prompt, no cursor and no output.
+// Every report of this reads as "privateer hangs".
+//
+// Loaded with `node --import` (see the TUI branch of bin/privateer-launch.mjs) so it
+// runs BEFORE Pi's entry module — the module loading it covers is most of the wait, and
+// a splash started any later would miss it.
+//
+// WHY A WORKER THREAD. The first version of this drew from a setInterval and animated
+// nothing: Pi's boot is a synchronous module-loading storm (compileSourceTextModule,
+// readFileUtf8, the CJS lexer — see the profile), so the main thread's event loop never
+// gets a turn between here and the first frame. A timer that only fires once the wait is
+// over is not a loading indicator. The animation therefore lives on its own thread, with
+// its own loop, which keeps drawing while the main thread is wedged. The main thread
+// still owns the two things that must be synchronous — noticing Pi's output and getting
+// out of its way — and steers the worker through a SharedArrayBuffer.
+//
+// HOW IT KNOWS WHEN TO STOP. Nothing tells us "the TUI is up", so we watch Pi's own
+// output: process.stdout is patched here, before Pi ever touches it. Two signals:
+//   • `\x1b[?2004h` (bracketed paste) — TUI.start(). Raw mode is on, the cursor is
+//     hidden, extensions' session_start handlers are now running. The wave switches to
+//     its second message and keeps going; the first frame is still seconds away.
+//   • ≥ FRAME_BYTES of stdout AFTER that point — the first frame is being written. We
+//     stop the worker, erase the line and get out of the way in the same tick, before
+//     the frame reaches the terminal.
+// Anything else Pi writes (a stray log line) just clears our line first, so the wave
+// never lands in front of real output.
+//
+// The wave is drawn on STDERR; stdout belongs to the TUI's canvas.
+
+import { Worker } from "node:worker_threads";
+
+const enabled =
+  process.stdout.isTTY &&
+  process.stderr.isTTY &&
+  !process.env.PRIVATEER_NO_SPLASH &&
+  !process.env.CI;
+
+// Bytes of stdout after TUI.start() that mean "this is the first frame, not a control
+// sequence". Everything Pi writes between raw mode and the frame is short (the paste
+// toggle, a Kitty protocol query, the cursor hide, an OSC window title — 42 bytes all
+// told on the run this was measured from); the frame itself is thousands.
+const FRAME_BYTES = 200;
+
+// Nothing is shown for this long. A launch that fails fast (`--help`, a flag Pi
+// rejects, a broken install) is done well inside it and never sees a wave flash across
+// its output.
+const HOLD_MS = 600;
+
+if (enabled) {
+  const err = process.stderr;
+  const errWrite = err.write.bind(err);
+  const outWrite = process.stdout.write.bind(process.stdout);
+
+  // Shared state, the only channel to the drawing thread. Slots, in order: stop
+  // requested / which message to draw / the worker has stopped and will not write
+  // again / the worker has drawn at least once (so there is a line to erase and a
+  // hidden cursor to restore).
+  const STOP = 0, PHASE = 1, ACK = 2, DREW = 3;
+  const sab = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
+  const state = new Int32Array(sab);
+
+  // Room for "  ⚓ " + wave + message + elapsed, clamped so a narrow terminal doesn't
+  // wrap (a wrapped line survives our `\r\x1b[K` erase only on its last row).
+  const width = Math.max(12, Math.min(28, (err.columns || 80) - 34));
+
+  // The worker source is plain logic with no escape sequences of its own — every ANSI
+  // string is handed over in workerData, so nothing here has to survive two rounds of
+  // backslash escaping.
+  const worker = new Worker(
+    `
+    const fs = require("node:fs");
+    const { workerData: w } = require("node:worker_threads");
+    const s = new Int32Array(w.sab);
+    const STOP = 0, PHASE = 1, ACK = 2, DREW = 3;
+    const t0 = Date.now();
+    let frame = 0;
+
+    // A swell travelling right to left, in eighth-blocks. Two summed sines at different
+    // wavelengths — one sine on its own reads as a metronome. Two-tone rather than a
+    // per-cell gradient, so a frame is a handful of escapes and not one per column.
+    function wave(phase) {
+      let out = "", tone = "";
+      for (let x = 0; x < w.width; x++) {
+        const y = (Math.sin(x * 0.45 - phase) * 0.65 + Math.sin(x * 0.21 - phase * 0.6) * 0.35 + 1) / 2;
+        const i = Math.max(0, Math.min(7, Math.round(y * 7)));
+        const want = i >= 4 ? w.crest : w.trough;
+        if (want !== tone) { out += want; tone = want; }
+        out += w.blocks[i];
+      }
+      return out + w.off;
+    }
+
+    function draw() {
+      const secs = Math.round((Date.now() - t0) / 1000);
+      const msg = w.msgs[Atomics.load(s, PHASE)];
+      const age = secs >= 3 ? w.dim + " " + secs + "s" + w.off : "";
+      fs.writeSync(2, w.cr + "  " + w.anchor + " " + wave(frame++ * 0.35) + " " + w.dim + msg + "…" + w.off + age + w.clearEol);
+    }
+
+    // Atomics.wait doubles as the sleep: an exact 80ms tick that the main thread can cut
+    // short the instant it needs the line back.
+    Atomics.wait(s, STOP, 0, w.hold);
+    if (!Atomics.load(s, STOP)) {
+      fs.writeSync(2, w.hideCursor);
+      Atomics.store(s, DREW, 1);
+      while (!Atomics.load(s, STOP)) {
+        draw();
+        Atomics.wait(s, STOP, 0, 80);
+      }
+    }
+    Atomics.store(s, ACK, 1);
+    Atomics.notify(s, ACK);
+    `,
+    {
+      eval: true,
+      stdout: false,
+      workerData: {
+        sab,
+        width,
+        hold: HOLD_MS,
+        blocks: "▁▂▃▄▅▆▇█",
+        msgs: ["hoisting sail", "raising the colours"],
+        anchor: "\x1b[38;5;69m⚓\x1b[0m",
+        crest: "\x1b[38;5;109m",
+        trough: "\x1b[38;5;67m",
+        dim: "\x1b[2m",
+        off: "\x1b[0m",
+        cr: "\r",
+        clearEol: "\x1b[K",
+        hideCursor: "\x1b[?25l",
+      },
+    },
+  );
+  worker.unref(); // never the reason this process stays alive
+  worker.on("error", () => Atomics.store(state, STOP, 1)); // a splash is never worth a crash
+
+  let running = true;
+  let started = false; // seen TUI.start()
+  let bytesAfterStart = 0;
+  let appHidCursor = false; // Pi hid the cursor — leave it hidden on the way out
+
+  // Park the drawing thread and WAIT for it to confirm, so the caller can write to the
+  // terminal knowing nothing else will. Without the acknowledgement the worker could
+  // land one last frame on top of Pi's first paint.
+  function park() {
+    Atomics.store(state, STOP, 1);
+    Atomics.notify(state, STOP);
+    if (!Atomics.load(state, ACK)) Atomics.wait(state, ACK, 0, 50);
+  }
+
+  function clearLine() {
+    if (Atomics.load(state, DREW)) errWrite("\r\x1b[K");
+  }
+
+  function stop() {
+    if (!running) return;
+    running = false;
+    park();
+    clearLine();
+    // Only give the cursor back if Pi hasn't deliberately hidden it — the TUI hides it
+    // for the whole session and would never get the chance to hide it again.
+    if (Atomics.load(state, DREW) && !appHidCursor) errWrite("\x1b[?25h");
+    process.stdout.write = outWrite;
+    err.write = errWrite;
+    worker.terminate();
+  }
+
+  // ── watch Pi's output ─────────────────────────────────────────────────────
+  const size = (chunk) =>
+    typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk?.length ?? 0;
+  const text = (chunk) =>
+    typeof chunk === "string" ? chunk : Buffer.isBuffer(chunk) ? chunk.toString("latin1") : "";
+
+  process.stdout.write = function (chunk, ...rest) {
+    if (running) {
+      const s = text(chunk);
+      if (s.includes("\x1b[?25l")) appHidCursor = true;
+      if (started) {
+        bytesAfterStart += size(chunk);
+        // Erase our line BEFORE the write lands, so Pi's output — a log line now, the
+        // first frame in a moment — never has half a wave in front of it.
+        if (bytesAfterStart >= FRAME_BYTES) stop();
+        else clearLine();
+      } else if (s.includes("\x1b[?2004h")) {
+        started = true;
+        Atomics.store(state, PHASE, 1);
+        clearLine();
+      } else {
+        clearLine();
+      }
+    }
+    return outWrite(chunk, ...rest);
+  };
+
+  // Pi's own warnings go to stderr, on the line we're animating.
+  err.write = function (chunk, ...rest) {
+    if (running) clearLine();
+    return errWrite(chunk, ...rest);
+  };
+
+  process.on("exit", stop);
+
+  // ── setRawMode EIO ────────────────────────────────────────────────────────
+  // The other half of the long silent boot. Pi grabs raw mode ~19s in, and the tcsetattr
+  // behind it returns EIO when the terminal is no longer ours to configure — an orphaned
+  // process group (the shell that started us has exited), or a controlling terminal that
+  // was revoked outright (window or tab closed, ssh dropped, session torn down). A boot
+  // that spends half a minute unattended is exactly when that happens. Pi lets the error
+  // out as an uncaught exception, so the user's reward for waiting is a native stack
+  // trace ending in node:tty. Nothing can rescue the TUI — it has no way to read keys —
+  // but it can say what happened in a sentence. (A merely BACKGROUNDED process is a
+  // different case: it gets SIGTTOU and stops, and `fg` resumes it as normal.)
+  const setRawMode = process.stdin.setRawMode?.bind(process.stdin);
+  if (setRawMode) {
+    process.stdin.setRawMode = function (mode) {
+      try {
+        return setRawMode(mode);
+      } catch (e) {
+        if (e?.code !== "EIO") throw e;
+        stop();
+        errWrite(
+          [
+            "",
+            "  ⚓ Privateer couldn't take the helm — this terminal stopped accepting keyboard",
+            "     control while the agent was still loading (setRawMode EIO).",
+            "",
+            "     That usually means the window, tab or ssh session it started in went away.",
+            `     Run \x1b[1m${process.env.PRIVATEER_CMD || "privateer"}\x1b[0m again from a terminal you're sitting in front of.`,
+            "",
+          ].join("\n") + "\n",
+        );
+        process.exit(1);
+      }
+    };
+  }
+}

package/bin/update-route.d.mts

@@ -0,0 +1,6 @@
+// Types for the `privateer update` argv router. Same reason as apply-patches.d.mts:
+// the implementation is plain .mjs because bin/ runs under a bare `node`, before any
+// transpiler exists — but the tests that pin the grammar are TypeScript.
+
+/** Which half of `privateer update` the argv after the subcommand asks for. */
+export function routeUpdate(rest: string[] | undefined): "self" | "packs" | "all" | "help";

package/bin/update-route.mjs

@@ -0,0 +1,35 @@
+// Which half of `privateer update` did the user mean?
+//
+// "update" used to mean ONE thing — replace the CLI — and the launcher swallowed every
+// flag after it. So `privateer update --extensions`, the command Pi's own startup banner
+// told people to run (as `pi update --extensions`, naming a binary that is installed
+// nowhere on a Privateer machine), silently reinstalled the CLI instead of fetching the
+// tool pack that had an update waiting. Splitting the verb the way Pi's own grammar
+// already does is the fix; this is the decision, kept apart from the launcher so it can
+// be tested without spawning anything (tests/updates.test.ts).
+//
+//   privateer update                              → "self"   (unchanged: the common case)
+//   privateer update --self | self | pi           → "self"
+//   privateer update --extensions                 → "packs"
+//   privateer update <pack> | --extension <pack>  → "packs"
+//   privateer update --all                        → "all"    (packs, then the CLI)
+//
+// "all" is deliberately not Pi's "--all": to Pi that includes updating pi-coding-agent
+// globally via npm, which is not how this CLI is installed. Ours means tool packs plus
+// `privateer update`, so the launcher translates it and chains the self-update after.
+
+/**
+ * @param {string[]} rest — argv after the `update` subcommand
+ * @returns {"self" | "packs" | "all" | "help"}
+ */
+export function routeUpdate(rest) {
+  const args = rest ?? [];
+  // `update --help` must not fall through to "no pack flags → update the CLI", which
+  // would answer a question by reinstalling the program.
+  if (args.includes("--help") || args.includes("-h")) return "help";
+  if (args.includes("--all")) return "all";
+  // A bare word that isn't "self"/"pi" is a pack name (Pi's positional source form).
+  const namesPack = args.some((a) => !a.startsWith("-") && a !== "self" && a !== "pi");
+  if (args.includes("--extensions") || args.includes("--extension") || namesPack) return "packs";
+  return "self";
+}

package/extensions/privateer-brand.ts

@@ -37,6 +37,7 @@ import {
 import { resolveSignedInModel, savedPiDefaultSpec } from "../src/providers/defaultModel.ts";
 import { canOpenBrowser, openInBrowser } from "../src/util/openBrowser.ts";
 import { discoverContextFiles, onContextChanged } from "../src/context.ts";
+import { onPackUpdatesChanged, pendingCliUpdate, pendingPackUpdates } from "../src/updates.ts";
 import { type Palette, paletteFor } from "../src/ui/palette.ts";
 
 const VERSION: string = (() => {
@@ -225,32 +226,30 @@ function accountLine(p: Palette, modelProvider?: string): string {
   return `${p.DIM}not signed in · ${p.INK}/login${p.DIM} to connect your account${p.RESET}`;
 }
 
-// Is dotted version `a` newer than `b`? Plain numeric compare of major.minor.patch —
-// enough for our npm releases; anything unparseable sorts as 0 and is treated as older.
-function isNewer(a: string, b: string): boolean {
-  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
-  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
-    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
-  }
-  return false;
-}
-
 // The "update available" banner line, or "" when we're current / offline / unchecked.
 // Reads the cache the launcher refreshes in the background (see bin/privateer-tui) —
 // never fetches here, so the banner stays synchronous and never blocks on the network.
 function updateNotice(p: Palette): string {
-  try {
-    const home = process.env.PRIVATEER_HOME || join(homedir(), ".privateer");
-    const { latest } = JSON.parse(readFileSync(join(home, "update-check.json"), "utf8"));
-    if (typeof latest === "string" && isNewer(latest, VERSION)) {
-      return `${p.YELLOW}↑ v${latest} available${p.DIM} · run ${p.RESET}${p.INK}privateer update${p.RESET}`;
-    }
-  } catch {
-    // no cache yet, unreadable, or malformed — show nothing.
-  }
-  return "";
+  const latest = pendingCliUpdate(VERSION);
+  if (!latest) return "";
+  return `${p.YELLOW}↑ v${latest} available${p.DIM} · run ${p.RESET}${p.INK}privateer update${p.RESET}`;
+}
+
+// The tool-pack sibling of that line: a pack (an npm/git package contributing extensions,
+// skills, prompts or themes) has a newer version installed-able. Pi's own surface for this
+// was a warning-bordered box below the banner naming a command that doesn't exist here —
+// see extensions/privateer-update.ts, which owns the check and the /update that acts on it.
+// One line, same rule as the release notice: nothing at all when there's nothing to fetch.
+// Empty at startup and fills in when the background check lands (onPackUpdatesChanged
+// re-renders the header), so a slow registry never holds up the banner.
+function packNotice(p: Palette): string {
+  const packs = pendingPackUpdates();
+  if (packs.length === 0) return "";
+  const what =
+    packs.length === 1
+      ? `update ready for ${clean(packs[0].displayName)}`
+      : `${packs.length} tool pack updates ready`;
+  return `${p.YELLOW}⚑ ${what}${p.DIM} · ${p.RESET}${p.INK}/update${p.RESET}`;
 }
 
 // The PRIVATEER.md line under the block: green anchor when a project-context file is
@@ -307,6 +306,8 @@ function renderBanner(width: number, p: Palette, mark: string[], modelProvider?:
   ];
   const notice = updateNotice(p);
   if (notice) text.push(notice);
+  const packs = packNotice(p);
+  if (packs) text.push(packs);
   // A blank spacer, then the What's New block — set off below the identity lines.
   text.push("", ...whatsNewRows(p));
 
@@ -684,6 +685,10 @@ export default function privateerBrand(pi: any): void {
   // banner so its context line flips from the "/init" hint to "PRIVATEER.md loaded".
   onContextChanged(() => refresh(ctxRef));
 
+  // privateer-update's background check came back (or an /update cleared the list) —
+  // re-render so the ⚑ line appears or disappears without waiting for the next event.
+  onPackUpdatesChanged(() => refresh(ctxRef));
+
   // The terminal is quitting (Ctrl+C, Ctrl+D, /quit, SIGTERM …). Pi awaits this
   // handler inside runtimeHost.dispose() BEFORE process.exit, so it's our one
   // reliable window to revoke the server-side sessions this run created — the

package/extensions/privateer-update.ts

@@ -0,0 +1,187 @@
+// `/update` — fetch newer tool packs without leaving the terminal.
+//
+// A "tool pack" is what Pi calls a package: an npm or git source that contributes
+// extensions, skills, prompts or themes (pi-hermes-memory, a private tools repo, …).
+// Pi already checked for updates at startup and drew its own yellow box about it. We
+// suppress that box (patches/, in interactive-mode's run()) and own the surface here,
+// for two reasons:
+//
+//   1. THE BOX NAMED A COMMAND THAT DOES NOT EXIST. It said "Run pi update --extensions".
+//      No `pi` binary is installed on a Privateer machine, and `privateer update` means
+//      the CLI's own self-update — so the one instruction on screen either failed with
+//      "command not found" or reinstalled the wrong thing. The launcher now routes
+//      `privateer update --extensions` properly (bin/privateer-launch.mjs), and in the
+//      TUI the answer is simply /update.
+//   2. IT WAS THE WRONG SIZE. A warning-bordered box under the banner, for "a pack has a
+//      newer version". Privateer's own release notice is a single line INSIDE the banner;
+//      packs get a line beside it (extensions/privateer-brand.ts) and nothing more.
+//
+// WHY THIS CAN HAPPEN LIVE. Nothing here needs a restart, and that is a property of Pi's
+// own machinery rather than a trick of ours:
+//   - DefaultPackageManager.update() installs into the same on-disk locations the
+//     resolver reads from, so the new code is simply *there* when something looks again.
+//   - ctx.reload() runs the same path as /reload: resourceLoader.reload() re-runs
+//     packageManager.resolve() AND calls clearExtensionCache(), and extensions are loaded
+//     through jiti with moduleCache:false — so every extension file is re-read from disk,
+//     not served from a module cache. Keybindings, skills, prompts and themes come back
+//     with it, and the chat is rebuilt from the session's messages, so scrollback and
+//     context survive.
+// The honest caveat: in Node (not the bundle) jiti leaves `tryNative` on, so a dependency
+// DEEP inside an updated npm pack that Node already loaded natively can stay the old copy
+// in memory. The pack's own source always reloads; if something still looks stale after
+// an update, a restart is the guaranteed fix, and we say so rather than pretending.
+//
+// The CLI itself is the one thing that genuinely cannot be swapped live — updating it
+// replaces the program that is running — so /update reports it and points at the shell.
+
+import { DefaultPackageManager, SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { agentVersion } from "../src/config/version.ts";
+import {
+  type PackUpdate,
+  pendingCliUpdate,
+  pendingPackUpdates,
+  setPendingPackUpdates,
+} from "../src/updates.ts";
+
+// A check costs an npm/git round trip per configured pack. Once at startup is the point;
+// the extra checks come from reload (including the one our own /update triggers), where
+// re-asking the registry seconds after we already know the answer is pure waste.
+const RECHECK_AFTER_MS = 60_000;
+let lastCheckedAt = 0;
+
+// Build a package manager against THIS session's cwd and trust decision. Mirrors what
+// interactive-mode does for its own startup check: an untrusted project's packages must
+// stay out, and trust is the session's answer (ctx.isProjectTrusted), not a fresh guess.
+function packageManagerFor(ctx: any): any {
+  const cwd = ctx?.cwd ?? process.cwd();
+  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.create(cwd, agentDir, {
+    projectTrusted: ctx?.isProjectTrusted?.() ?? false,
+  });
+  return new DefaultPackageManager({ cwd, agentDir, settingsManager });
+}
+
+async function runCheck(ctx: any, opts: { force?: boolean } = {}): Promise<readonly PackUpdate[]> {
+  if (!opts.force && Date.now() - lastCheckedAt < RECHECK_AFTER_MS) return pendingPackUpdates();
+  // --offline / PI_OFFLINE means "no startup network", and a registry check is exactly
+  // that. Pi's own check bails the same way.
+  if (process.env.PI_OFFLINE) return pendingPackUpdates();
+  lastCheckedAt = Date.now();
+  const updates = await packageManagerFor(ctx).checkForAvailableUpdates();
+  const packs: PackUpdate[] = updates.map((u: any) => ({
+    source: u.source,
+    displayName: u.displayName,
+    type: u.type,
+    scope: u.scope,
+  }));
+  setPendingPackUpdates(packs);
+  return packs;
+}
+
+// "pi-hermes-memory", "pi-hermes-memory and pi-speak", "pi-hermes-memory, pi-speak and 2 more".
+function nameList(packs: readonly PackUpdate[]): string {
+  const names = packs.map((p) => p.displayName);
+  if (names.length <= 2) return names.join(" and ");
+  return `${names.slice(0, 2).join(", ")} and ${names.length - 2} more`;
+}
+
+// The CLI half of "what's out of date", appended to /update's replies so the answer to
+// "am I current?" is complete in one place. Null when the CLI is current or unchecked.
+function cliNote(): string | null {
+  const latest = pendingCliUpdate(agentVersion());
+  return latest
+    ? `Privateer v${latest} is out too — that one replaces the running program, so run \`privateer update\` from a shell.`
+    : null;
+}
+
+export default function privateerUpdate(pi: any): void {
+  // Check in the background on startup and after a reload. Never on a headless surface
+  // (harbor, ACP, print, channels): there's no banner to flag it on and nobody to type
+  // /update, so the network call would buy nothing.
+  pi.on("session_start", (event: any, ctx: any) => {
+    if (!ctx?.hasUI) return;
+    if (event?.reason !== "startup" && event?.reason !== "reload") return;
+    void runCheck(ctx).catch(() => {
+      // Offline, a private registry that won't answer, a git remote behind a VPN — an
+      // update check is never worth an error in the user's face. The flag just stays down.
+    });
+  });
+
+  pi.registerCommand?.("update", {
+    description: "Fetch tool pack updates in place: /update [<pack> | check]",
+    handler: async (args: string, ctx: any) => {
+      const arg = String(args ?? "").trim();
+      const notify = (msg: string, kind: "info" | "warning" | "error" = "info") =>
+        ctx?.ui?.notify?.(msg, kind);
+
+      if (arg === "check") {
+        try {
+          const packs = await runCheck(ctx, { force: true });
+          const cli = cliNote();
+          notify(
+            packs.length
+              ? `${packs.length} tool pack update${packs.length === 1 ? "" : "s"} ready: ${nameList(packs)} — /update to fetch${cli ? `. ${cli}` : ""}`
+              : `Tool packs are current.${cli ? ` ${cli}` : ""}`,
+          );
+        } catch (err) {
+          notify(`Update check failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+        return;
+      }
+
+      // A named pack is passed straight through to the package manager, which matches it
+      // against configured sources and reports a better "no such pack" than we could.
+      // With no argument we act on what the check found, re-checking first if it never
+      // ran (a terminal that started offline, or a pack installed since launch).
+      let targets = pendingPackUpdates();
+      if (!arg) {
+        try {
+          targets = await runCheck(ctx, { force: pendingPackUpdates().length === 0 });
+        } catch {
+          // fall through with whatever the last check knew — update() re-checks anyway.
+        }
+        if (targets.length === 0) {
+          const cli = cliNote();
+          notify(`Tool packs are current.${cli ? ` ${cli}` : ""}`);
+          return;
+        }
+      }
+
+      const label = arg || nameList(targets);
+      ctx?.ui?.setStatus?.("update", `⚑ updating ${arg || `${targets.length} pack${targets.length === 1 ? "" : "s"}`}`);
+      try {
+        const pm = packageManagerFor(ctx);
+        // Progress goes to the footer, not the transcript: an install emits several
+        // events per pack and each one as a notification would bury the chat.
+        pm.setProgressCallback((e: any) => {
+          if (e?.type === "error") return; // update() throws; the catch below reports it
+          ctx?.ui?.setStatus?.("update", `⚑ ${e?.action ?? "update"} ${e?.source ?? ""}`.trimEnd());
+        });
+        await pm.update(arg || undefined);
+        pm.setProgressCallback(undefined);
+      } catch (err) {
+        ctx?.ui?.setStatus?.("update", undefined);
+        notify(`Update failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+        return;
+      }
+      ctx?.ui?.setStatus?.("update", undefined);
+      // Whatever was pending is on disk now. Clear the flag before the reload so the
+      // banner that comes back is already correct, rather than flying a stale one until
+      // the post-reload check answers.
+      setPendingPackUpdates([]);
+      lastCheckedAt = 0;
+
+      // The reload is refused mid-turn (Pi guards on streaming/compaction), so don't ask
+      // for one — say plainly that the new code is on disk and waiting.
+      if (ctx?.isIdle?.() === false) {
+        notify(`Updated ${label}. Run /reload when this turn finishes to load it.`);
+        return;
+      }
+
+      notify(`Updated ${label} — reloading.`);
+      // ⚠️ ctx is STALE after this line (Pi invalidates it when the runtime is replaced).
+      // Nothing may touch it, so this is the last statement in the handler.
+      await ctx.reload();
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.7",
+  "version": "0.12.8",
   "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+0.80.3.patch

@@ -904,8 +904,76 @@ index 3355a47..8c6bba9 100644
      }
      getResourcePattern(item) {
          const scope = item.metadata.scope;
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
+index 68d0308..f7208f1 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
+@@ -1,5 +1,5 @@
+ import { isAbsolute, relative, resolve, sep } from "node:path";
+-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
++import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+ import { areExperimentalFeaturesEnabled } from "../../../core/experimental.js";
+ import { theme } from "../theme/theme.js";
+ /**
+@@ -13,6 +13,43 @@ function sanitizeStatusText(text) {
+         .replace(/ +/g, " ")
+         .trim();
+ }
++/**
++ * Lay extension statuses out over as many lines as the terminal needs, keeping
++ * each status whole. Upstream joined them into ONE line and truncated it to the
++ * width, which silently hid whatever didn't fit — and what didn't fit was often
++ * the loudest indicator on screen (Privateer's "permission gate OFF" flag). A
++ * status too wide to fit on a line of its own is wrapped, never clipped.
++ */
++function packStatusLines(statuses, width) {
++    if (width <= 0)
++        return [];
++    const lines = [];
++    let current = "";
++    let currentWidth = 0;
++    const flush = () => {
++        if (current)
++            lines.push(current);
++        current = "";
++        currentWidth = 0;
++    };
++    for (const status of statuses) {
++        if (!status)
++            continue;
++        const statusWidth = visibleWidth(status);
++        if (statusWidth > width) {
++            flush();
++            lines.push(...wrapTextWithAnsi(status, width));
++            continue;
++        }
++        const separator = current ? 1 : 0;
++        if (currentWidth + separator + statusWidth > width)
++            flush();
++        current = current ? `${current} ${status}` : status;
++        currentWidth += separator + statusWidth;
++    }
++    flush();
++    return lines;
++}
+ /**
+  * Format token counts for compact footer display.
+  */
+@@ -211,9 +248,9 @@ export class FooterComponent {
+             const sortedStatuses = Array.from(extensionStatuses.entries())
+                 .sort(([a], [b]) => a.localeCompare(b))
+                 .map(([, text]) => sanitizeStatusText(text));
+-            const statusLine = sortedStatuses.join(" ");
+-            // Truncate to terminal width with dim ellipsis for consistency with footer style
+-            lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
++            // Wrap onto extra lines instead of truncating: a status is there because
++            // something wants to be seen, so none of them may be cut off.
++            lines.push(...packStatusLines(sortedStatuses, width));
+         }
+         return lines;
+     }
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index 5d65200..f827cd7 100644
+index 5d65200..397a7b7 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 @@ -10,7 +10,7 @@ import { getProviders, } from "@earendil-works/pi-ai/compat";
@@ -948,7 +1016,28 @@ index 5d65200..f827cd7 100644
              .map((command) => ({
              type: "warning",
              message: command.invocationName === command.name
-@@ -2042,7 +2053,17 @@ export class InteractiveMode {
+@@ -549,12 +560,14 @@ export class InteractiveMode {
+                 this.showNewVersionNotification(newRelease);
+             }
+         });
+-        // Start package update check asynchronously
+-        this.checkForPackageUpdates().then((updates) => {
+-            if (updates.length > 0) {
+-                this.showPackageUpdateNotification(updates);
+-            }
+-        });
++        // Privateer owns the package ("tool pack") update surface — see
++        // extensions/privateer-update.ts. Upstream ran its own check here and drew a
++        // warning-bordered box telling the user to run `pi update --extensions`: a
++        // binary that is installed nowhere on a Privateer machine, so the only
++        // instruction on screen could not be followed. We replace it with a single
++        // line in the startup banner plus /update, which applies packs in place. The
++        // CHECK is removed too, not just the box, so this costs no registry round
++        // trip — the extension does exactly one, on the same startup.
+         // Check tmux keyboard setup asynchronously
+         this.checkTmuxKeyboardSetup().then((warning) => {
+             if (warning) {
+@@ -2042,7 +2055,17 @@ export class InteractiveMode {
              if (text === "/model" || text.startsWith("/model ")) {
                  const searchTerm = text.startsWith("/model ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -967,7 +1056,7 @@ index 5d65200..f827cd7 100644
                  return;
              }
              if (text === "/export" || text.startsWith("/export ")) {
-@@ -2105,14 +2126,44 @@ export class InteractiveMode {
+@@ -2105,14 +2128,44 @@ export class InteractiveMode {
                  this.editor.setText("");
                  return;
              }
@@ -1015,7 +1104,7 @@ index 5d65200..f827cd7 100644
                  return;
              }
              if (text === "/new") {
-@@ -2650,7 +2701,7 @@ export class InteractiveMode {
+@@ -2650,7 +2703,7 @@ export class InteractiveMode {
          if (this.chatContainer.children.length > 0) {
              this.chatContainer.addChild(new Spacer(1));
          }
@@ -1055,71 +1144,3 @@ index f81b4b4..9712a37 100644
    -a, --approve     Trust project-local files for this command
    -na, --no-approve Ignore project-local files for this command
  
-diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
-index 68d0308..f7208f1 100644
---- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
-+++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
-@@ -1,5 +1,5 @@
- import { isAbsolute, relative, resolve, sep } from "node:path";
--import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
- import { areExperimentalFeaturesEnabled } from "../../../core/experimental.js";
- import { theme } from "../theme/theme.js";
- /**
-@@ -13,6 +13,43 @@ function sanitizeStatusText(text) {
-         .replace(/ +/g, " ")
-         .trim();
- }
-+/**
-+ * Lay extension statuses out over as many lines as the terminal needs, keeping
-+ * each status whole. Upstream joined them into ONE line and truncated it to the
-+ * width, which silently hid whatever didn't fit — and what didn't fit was often
-+ * the loudest indicator on screen (Privateer's "permission gate OFF" flag). A
-+ * status too wide to fit on a line of its own is wrapped, never clipped.
-+ */
-+function packStatusLines(statuses, width) {
-+    if (width <= 0)
-+        return [];
-+    const lines = [];
-+    let current = "";
-+    let currentWidth = 0;
-+    const flush = () => {
-+        if (current)
-+            lines.push(current);
-+        current = "";
-+        currentWidth = 0;
-+    };
-+    for (const status of statuses) {
-+        if (!status)
-+            continue;
-+        const statusWidth = visibleWidth(status);
-+        if (statusWidth > width) {
-+            flush();
-+            lines.push(...wrapTextWithAnsi(status, width));
-+            continue;
-+        }
-+        const separator = current ? 1 : 0;
-+        if (currentWidth + separator + statusWidth > width)
-+            flush();
-+        current = current ? `${current} ${status}` : status;
-+        currentWidth += separator + statusWidth;
-+    }
-+    flush();
-+    return lines;
-+}
- /**
-  * Format token counts for compact footer display.
-  */
-@@ -211,9 +248,9 @@ export class FooterComponent {
-             const sortedStatuses = Array.from(extensionStatuses.entries())
-                 .sort(([a], [b]) => a.localeCompare(b))
-                 .map(([, text]) => sanitizeStatusText(text));
--            const statusLine = sortedStatuses.join(" ");
--            // Truncate to terminal width with dim ellipsis for consistency with footer style
--            lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
-+            // Wrap onto extra lines instead of truncating: a status is there because
-+            // something wants to be seen, so none of them may be cut off.
-+            lines.push(...packStatusLines(sortedStatuses, width));
-         }
-         return lines;
-     }

package/src/config/moatManifest.json

@@ -12,6 +12,7 @@
     { "name": "privateer-connect", "entry": "extensions/privateer-connect.ts", "note": "/connect — MCP connector manager" },
     { "name": "privateer-media", "entry": "extensions/privateer-media.ts", "note": "image/video/speech/music + ffmpeg compose" },
     { "name": "privateer-hints", "entry": "extensions/privateer-hints.ts", "note": "rotating tips in the working line + /hints" },
+    { "name": "privateer-update", "entry": "extensions/privateer-update.ts", "note": "tool pack updates in place — banner flag + /update" },
     { "name": "privateer-speak", "entry": "extensions/privateer-speak.ts", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },
     { "name": "rpiv-web-tools", "dep": ["@juicesharp/rpiv-web-tools", "index.ts"], "note": "private web tools (user's own provider key)" },
     { "name": "rpiv-ask-user-question", "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "note": "ask_user_question" },

package/src/context.ts

@@ -153,8 +153,16 @@ export function writeTemplate(dir: string = process.cwd()): WriteResult {
 // Lets /init (in the context extension) tell the banner (in the brand extension) that
 // PRIVATEER.md state changed, so the header re-renders its loaded/hint line immediately —
 // without either extension importing the other. Mirrors priv.onSignedIn.
+//
+// ⚠️ The listener set CANNOT be plain module state. Pi gives every extension its own jiti
+// instance with moduleCache:false, so this module is instantiated once per extension that
+// imports it: /init's copy and the banner's copy are different objects, and an emit on one
+// never reaches a listener registered on the other — the refresh silently did nothing.
+// globalThis is the one thing the two copies share. Same fix, same reason, as the pack
+// state in src/updates.ts.
 type Listener = () => void;
-const listeners = new Set<Listener>();
+const LISTENERS = Symbol.for("privateer.context.listeners");
+const listeners: Set<Listener> = (((globalThis as any)[LISTENERS] ??= new Set<Listener>()) as Set<Listener>);
 
 export function onContextChanged(fn: Listener): void {
   listeners.add(fn);

package/src/updates.ts

@@ -0,0 +1,106 @@
+// What's out of date — the two kinds of update a Privateer terminal can have pending,
+// owned in one place so every surface gives the same answer.
+//
+//   1. THE CLI ITSELF (privateer-agent). Read from the cache the launcher refreshes in
+//      the background at most ~daily (bin/privateer-launch.mjs refreshUpdateCache). We
+//      never fetch here, so the banner stays synchronous and offline-safe. Applying it
+//      REPLACES the running program, so it can only ever be `privateer update` from a
+//      shell — never live.
+//   2. TOOL PACKS (Pi "packages": extensions/skills/prompts/themes installed from npm or
+//      git). Checked in-process by extensions/privateer-update.ts, held here in memory,
+//      and applied live — see that file for why a running terminal can swap them out.
+//
+// The two consumers are different extensions (the banner draws the pending state, /update
+// acts on it), so the pack list gets the same listener idiom as src/context.ts's
+// onContextChanged: a setter fires listeners, and neither extension imports the other.
+// In memory rather than on disk ON PURPOSE — a cache file outlives the update that
+// cleared it, and a banner still flying the flag after you've fetched everything is worse
+// than one that shows up a second late.
+//
+// IMPORT-SAFETY: no Pi imports, no side effects — safe to load from a jiti-loaded
+// extension and from pre-boot code alike.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "./config/paths.ts";
+
+// ── the CLI release ──────────────────────────────────────────────────────────
+
+// Is dotted version `a` newer than `b`? Plain numeric compare of major.minor.patch —
+// enough for our npm releases; anything unparseable sorts as 0 and is treated as older.
+function isNewer(a: string, b: string): boolean {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+  }
+  return false;
+}
+
+/**
+ * The newer privateer-agent release the launcher's cache knows about, or null when we're
+ * current / offline / never checked. Reads only — the refresh is the launcher's job.
+ */
+export function pendingCliUpdate(current: string): string | null {
+  try {
+    const { latest } = JSON.parse(readFileSync(join(globalDir(), "update-check.json"), "utf8"));
+    if (typeof latest === "string" && isNewer(latest, current)) return latest;
+  } catch {
+    // no cache yet, unreadable, or malformed — nothing pending as far as we know.
+  }
+  return null;
+}
+
+// ── tool packs ───────────────────────────────────────────────────────────────
+
+/** One installed pack with a newer version available. Mirrors Pi's PackageUpdate. */
+export interface PackUpdate {
+  /** The configured source string ("pi-hermes-memory", "github:owner/repo", …). */
+  source: string;
+  /** What to show a human — Pi's own label for the pack. */
+  displayName: string;
+  type: "npm" | "git";
+  scope: "user" | "project";
+}
+
+type Listener = () => void;
+
+// ⚠️ MODULE STATE IS NOT SHARED BETWEEN EXTENSIONS. Pi loads every extension through its
+// OWN jiti instance with moduleCache:false (core/extensions/loader.js), so a module two
+// extensions both import is instantiated TWICE — a plain module-level `let` here would
+// leave the banner reading a different copy from the one /update writes, and the flag
+// would never appear. Verified rather than assumed: two jiti instances importing the same
+// relative module see completely independent state, and a globalThis-keyed store is what
+// crosses between them. Symbol.for so both copies resolve the same key.
+const STATE = Symbol.for("privateer.updates.packs");
+interface PackState {
+  pending: readonly PackUpdate[];
+  listeners: Set<Listener>;
+}
+const state: PackState = (((globalThis as any)[STATE] ??= {
+  pending: [],
+  listeners: new Set<Listener>(),
+}) as PackState);
+
+/** Packs with an update waiting, as of the last check. Empty until the check lands. */
+export function pendingPackUpdates(): readonly PackUpdate[] {
+  return state.pending;
+}
+
+/** Record the result of a check (or of an update that cleared the list) and notify. */
+export function setPendingPackUpdates(next: readonly PackUpdate[]): void {
+  state.pending = [...next];
+  for (const fn of state.listeners) {
+    try {
+      fn();
+    } catch {
+      // a broken listener must not break the check that called us.
+    }
+  }
+}
+
+/** Called whenever the pending list changes — the banner re-renders from it. */
+export function onPackUpdatesChanged(fn: Listener): void {
+  state.listeners.add(fn);
+}