privateer-agent 0.12.7 → 0.12.10

package/bin/privateer-verify.mjs

@@ -0,0 +1,289 @@
+// `privateer verify` — check the install that is actually on this disk.
+//
+// Every other trust signal we offer is an INSTALL-TIME signal: npm provenance is
+// checked when you install, install.sh verifies a checksum before it unpacks, the
+// npm page shows a green badge to whoever is looking at the npm page. None of that
+// answers the question a user actually has three weeks later, which is "is the
+// thing on my machine right now still the thing you published?"
+//
+// So this command reads local state first and the network second, and it is careful
+// about the difference between "verified", "couldn't check", and "wrong". A check
+// that cannot reach the registry says so; it never reports a pass it didn't make.
+//
+// Deliberately NOT a security boundary: anything that can rewrite node_modules can
+// rewrite this file too. It is a tampering *smoke alarm* and an honest inventory —
+// useful exactly because most breakage is accidental (a half-finished upgrade, a
+// stale patch stamp, a hand-edited dependency) rather than adversarial.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { findDepRoot } from "./apply-patches.mjs";
+
+const REGISTRY = process.env.npm_config_registry || "https://registry.npmjs.org";
+const NET_TIMEOUT_MS = 8000;
+
+// --- tiny reporter ---------------------------------------------------------
+// Three outcomes, and the third one is the point: "unknown" must never be
+// rendered as a pass. Exit code reflects only real failures, so `privateer verify`
+// is safe to put in a CI step without breaking on an offline runner.
+const C = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (C ? `\x1b[2m${s}\x1b[0m` : s);
+const bold = (s) => (C ? `\x1b[1m${s}\x1b[0m` : s);
+const green = (s) => (C ? `\x1b[32m${s}\x1b[0m` : s);
+const red = (s) => (C ? `\x1b[31m${s}\x1b[0m` : s);
+const yellow = (s) => (C ? `\x1b[33m${s}\x1b[0m` : s);
+
+let failures = 0;
+let unknowns = 0;
+
+function pass(label, detail) {
+  console.log(`  ${green("✓")} ${label}${detail ? ` ${dim(detail)}` : ""}`);
+}
+function fail(label, detail) {
+  failures++;
+  console.log(`  ${red("✗")} ${label}${detail ? ` ${dim(detail)}` : ""}`);
+}
+function unknown(label, detail) {
+  unknowns++;
+  console.log(`  ${yellow("?")} ${label}${detail ? ` ${dim(detail)}` : ""}`);
+}
+function note(text) {
+  console.log(`    ${dim(text)}`);
+}
+function heading(text) {
+  console.log(`\n${bold(text)}`);
+}
+
+const readJson = (p) => {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+async function getJson(url) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), NET_TIMEOUT_MS);
+  try {
+    const r = await fetch(url, { signal: ac.signal, headers: { accept: "application/json" } });
+    if (!r.ok) return { error: `HTTP ${r.status}` };
+    return { data: await r.json() };
+  } catch (e) {
+    return { error: e.name === "AbortError" ? "timed out" : e.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/** sha256 over every patch file's name + contents — must match apply-patches.mjs. */
+function patchSetHash(patchDir, files, stampVersion) {
+  const h = crypto.createHash("sha256").update(String(stampVersion));
+  for (const f of files) {
+    h.update(f);
+    h.update(fs.readFileSync(path.join(patchDir, f)));
+  }
+  return h.digest("hex");
+}
+
+export async function verify({ repo, offline = false } = {}) {
+  // Reset: the counters are module state, so a second call in one process (a test,
+  // or any future programmatic caller) would otherwise inherit the first's verdict.
+  failures = 0;
+  unknowns = 0;
+
+  const pkg = readJson(path.join(repo, "package.json")) || {};
+  const version = pkg.version || "unknown";
+  const bundleInfo = readJson(path.join(repo, "BUNDLE_INFO.json"));
+
+  console.log(`\n${bold("⚓ Privateer install check")}  ${dim(`v${version}`)}`);
+
+  // --- 1. what kind of install is this ------------------------------------
+  heading("Install");
+  if (bundleInfo) {
+    pass("self-contained bundle", `${bundleInfo.target || "?"} · pinned Node ${bundleInfo.node || "?"}`);
+    note("bundles ship a fixed file set — nothing was resolved on this machine at install time");
+  } else {
+    pass("npm install", "dependencies were resolved on this machine");
+  }
+  console.log(`  ${dim("path")}   ${repo}`);
+  console.log(`  ${dim("node")}   ${process.version}`);
+
+  // --- 2. is this version the one the registry knows about ----------------
+  // The strongest thing checkable from here without re-downloading a tarball:
+  // does this exact version exist upstream, and does it carry a provenance
+  // attestation? A version the registry has never heard of is the loud case.
+  heading("Published provenance");
+  if (offline) {
+    unknown("skipped (--offline)");
+  } else {
+    const { data, error } = await getJson(`${REGISTRY}/${pkg.name || "privateer-agent"}/${version}`);
+    if (error) {
+      unknown("couldn't reach the npm registry", `(${error})`);
+      note("re-run with a network connection, or use --offline to skip this section");
+    } else if (!data || data.error) {
+      fail(`the registry has no ${pkg.name}@${version}`, "this build was not published");
+      note("an unpublished version is not automatically malicious — an unreleased local");
+      note("checkout looks identical — but a machine you only ever installed from npm");
+      note("should never be in this state.");
+    } else {
+      pass(`published as ${pkg.name}@${version}`);
+      const att = data.dist?.attestations;
+      if (att?.provenance?.predicateType) {
+        pass("carries an npm provenance attestation", att.provenance.predicateType);
+        note("verify the signature chain end-to-end with:  npm audit signatures");
+      } else {
+        fail("no provenance attestation on this version");
+        note("every release from 0.6.7 on is published from CI with --provenance;");
+        note("a later version without one did not come from that workflow.");
+      }
+      const npmUser = data._npmUser?.trustedPublisher?.id;
+      if (npmUser) pass("published by a trusted publisher", npmUser);
+      else if (att) unknown("publisher identity not reported by the registry");
+    }
+  }
+
+  // --- 3. did the dependency tree drift from what we declared -------------
+  // Every direct dependency is pinned to an exact version, precisely so this
+  // check can be exact: a resolved version that differs from the declared one
+  // means the tree was changed after install.
+  heading("Dependencies");
+  const deps = Object.entries(pkg.dependencies || {});
+  const drift = [];
+  const ranged = []; // declared with a range, so there is nothing exact to check against
+  let checked = 0;
+  let missing = 0;
+  for (const [name, want] of deps) {
+    const root = findDepRoot(repo, name);
+    const manifest = root && readJson(path.join(root, "node_modules", ...name.split("/"), "package.json"));
+    if (!manifest) {
+      missing++;
+      continue;
+    }
+    // An exact pin is the only thing this check can be exact about. A caret range
+    // is not a failure, but counting it as a match would be a lie — it would report
+    // "matches its pinned version" for a dependency that has no pinned version.
+    if (!/^\d/.test(want)) {
+      ranged.push(`${name} ${want} (resolved ${manifest.version})`);
+      continue;
+    }
+    checked++;
+    if (manifest.version !== want) drift.push(`${name} ${want} → ${manifest.version}`);
+  }
+  if (missing) {
+    unknown(`${missing} of ${deps.length} direct dependencies not found on disk`);
+    note("normal inside a bundle, which flattens its own tree; unexpected for an npm install");
+  }
+  if (drift.length > 0) {
+    fail(`${drift.length} dependenc${drift.length === 1 ? "y differs" : "ies differ"} from the pinned version`);
+    for (const d of drift) note(d);
+  } else if (checked > 0) {
+    pass(`${checked} direct dependenc${checked === 1 ? "y matches its" : "ies match their"} exact pin`);
+  }
+  if (ranged.length > 0) {
+    // Versions before 0.12.9 shipped caret ranges, so an older install lands here.
+    unknown(`${ranged.length} direct dependenc${ranged.length === 1 ? "y is" : "ies are"} declared as a range — cannot be checked exactly`);
+    for (const d of ranged.slice(0, 5)) note(d);
+    if (ranged.length > 5) note(`… and ${ranged.length - 5} more`);
+  }
+
+  const piRoot = findDepRoot(repo, "@earendil-works/pi-coding-agent");
+  const piPkg =
+    piRoot && readJson(path.join(piRoot, "node_modules", "@earendil-works", "pi-coding-agent", "package.json"));
+  if (piPkg) console.log(`  ${dim("runtime")} pi-coding-agent ${piPkg.version}`);
+
+  // --- 4. patch state ------------------------------------------------------
+  // Patches are applied at LAUNCH into node_modules, so the running tree is
+  // legitimately not byte-identical to the published tarball. That is by design
+  // (it is how we avoid an install script), but it means "the files changed" is
+  // not by itself a finding — this is the section that says which changes are ours.
+  heading("Launch-time patches");
+  const patchDir = path.join(repo, "patches");
+  const patchFiles = fs.existsSync(patchDir)
+    ? fs
+        .readdirSync(patchDir)
+        .filter((f) => f.endsWith(".patch"))
+        .sort()
+    : [];
+  if (patchFiles.length === 0) {
+    pass("none shipped");
+  } else {
+    const stampFile = piRoot && path.join(piRoot, "node_modules", ".privateer-patches.json");
+    const stamp = stampFile && readJson(stampFile);
+    // STAMP_VERSION is private to apply-patches.mjs; try the current value and
+    // report a mismatch as "stale" rather than guessing at the applier's internals.
+    const want = patchSetHash(patchDir, patchFiles, 1);
+    if (!stamp) {
+      unknown(`${patchFiles.length} patch(es) shipped, none recorded as applied`);
+      note("expected before the first launch, or when node_modules is root-owned");
+      note("(sudo npm i -g) — Privateer then runs on stock Pi and says so at startup");
+    } else if (stamp.hash === want) {
+      pass(`${patchFiles.length} patch(es) applied and current`, `at ${stamp.at || "?"}`);
+      for (const f of patchFiles) note(f);
+    } else {
+      unknown("recorded patch set does not match the shipped one", "— will re-apply next launch");
+    }
+  }
+
+  // --- 5. where config and credentials live -------------------------------
+  heading("Config");
+  const home = process.env.PRIVATEER_HOME || path.join(process.env.HOME || "", ".privateer");
+  console.log(`  ${dim("home")}   ${home}${fs.existsSync(home) ? "" : dim(" (not created yet)")}`);
+  for (const d of [".privateer", ".pi"]) {
+    const p = path.join(process.cwd(), d);
+    if (fs.existsSync(p)) console.log(`  ${dim("project")} ${p}`);
+  }
+
+  // --- verdict -------------------------------------------------------------
+  console.log("");
+  if (failures > 0) {
+    console.log(
+      red(`✗ ${failures} check(s) failed`) +
+        (unknowns ? dim(`, ${unknowns} inconclusive`) : "") +
+        "\n" +
+        dim("  If you did not expect this, reinstall from a known-good source:\n") +
+        dim("    curl -fsSL https://privateer.pro/install.sh | sh\n") +
+        dim("  and report it at https://github.com/privateer-agent/privateer-agent/issues"),
+    );
+    return 1;
+  }
+  if (unknowns > 0) {
+    console.log(yellow(`✓ no failures, ${unknowns} check(s) inconclusive`));
+    return 0;
+  }
+  console.log(green("✓ everything checks out"));
+  return 0;
+}
+
+// --- CLI -------------------------------------------------------------------
+// Guarded, so importing this module (from a test, or from the launcher) does not
+// run the command and exit the process out from under the caller.
+//
+// fileURLToPath, not `new URL(...).pathname`: on Windows the latter yields
+// "/C:/Users/..." with percent-encoded spaces, so every path built from it is wrong
+// — and win32 is a platform we ship a bundle for.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    const cmd = process.env.PRIVATEER_CMD || "privateer";
+    console.log(
+      [
+        `${cmd} verify — check the Privateer install on this machine.`,
+        "",
+        `  ${cmd} verify              run every check`,
+        `  ${cmd} verify --offline    skip the checks that need the npm registry`,
+        "",
+        "Reports the install shape, whether this version is published with npm",
+        "provenance, whether the dependency tree still matches its pinned versions,",
+        "and which launch-time patches are applied.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+  process.exit(await verify({ repo: path.resolve(HERE, ".."), offline: argv.includes("--offline") }));
+}

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));
 
@@ -403,8 +404,14 @@ export default function privateerBrand(pi: any): void {
   //     entry is dead for every terminal;
   //   - the default ownership-checked drop for THIS process's exit, which must not
   //     delete the credential another running terminal is using.
-  const dropPersistedAccount = (ctx: any, opts: { force?: boolean } = {}): void => {
-    dropPersistedAccountCredential(ctx, opts);
+  // `ctx` is no longer passed through: pi 0.84 removed ctx.modelRegistry.authStorage, so
+  // the store is resolved from piAuthStore() inside. Kept in the signature because every
+  // caller here is a Pi command handler that has one, and dropping the parameter would
+  // churn call sites for no gain. Fire-and-forget as before — the drop is best-effort and
+  // the server-side TTL is the fallback — but the promise is now caught explicitly rather
+  // than left to become an unhandled rejection.
+  const dropPersistedAccount = (_ctx: any, opts: { force?: boolean } = {}): void => {
+    void dropPersistedAccountCredential(opts).catch(() => { /* best effort — server TTL covers it */ });
   };
 
   // /update — run the global npm install in a child process and report the outcome via
@@ -684,6 +691,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-hints.ts

@@ -39,6 +39,12 @@ function key(binding: Parameters<typeof keyText>[0], fallback: string): string {
   }
 }
 
+// Mirror of privateer-speak's DEFAULT_SHORTCUT. One constant, not a literal at each
+// return, so the two paths below can't drift apart from each other — they can still
+// drift from the package, which is why the value is named here rather than inlined:
+// grep for it when bumping privateer-speak.
+const DEFAULT_TALK_KEY = "alt+t";
+
 // Push-to-talk is pi-speak's own binding, not a Pi keybinding action, so keyText
 // can't see it — it lives in speak.json beside config.json and /talk key rebinds
 // it. Read it the same defensive way (any failure = the default).
@@ -46,9 +52,9 @@ function talkKey(): string {
   try {
     const shortcut = JSON.parse(readFileSync(join(globalDir(), "speak.json"), "utf8"))?.input?.shortcut;
     // An explicit "" is "unbound", not "missing" — only an absent field defaults.
-    return typeof shortcut === "string" ? shortcut : "ctrl+x";
+    return typeof shortcut === "string" ? shortcut : DEFAULT_TALK_KEY;
   } catch {
-    return "ctrl+x";
+    return DEFAULT_TALK_KEY;
   }
 }
 

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