privateer-agent 0.12.6 → 0.12.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayden Bulk Tech Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -570,8 +570,9 @@ posts a warning to the transcript, and while it's on the footer carries a perman
 Toggling takes effect from the next gated action — an approval already on screen still
 needs an answer. It's a physical-terminal switch: a phone driving this terminal over
 `/remote-access` can't reach it. The app has its own no-quarter toggle for driven turns,
-which is `bypass` exactly — never less — so dangerous shell and destructive actions
-still surface an Allow there, precisely as they do under `/mode bypass` locally.
+and it means the same thing this flag does: the moat down, dangerous shell and destructive
+actions included — stronger than `/mode bypass`, which keeps those two above it. A hard
+plan-mode deny is the one thing it doesn't talk around.
 
 > shift+tab is Pi's default "cycle thinking level" chord; Privateer takes it for this.
 > Thinking level is still under `/settings`, or bind `app.thinking.cycle` to another key

package/bin/privateer-acp.mjs

@@ -18,7 +18,7 @@
 // process.loadEnvFile and tsx's register() are both silent; keep it that way, and
 // send any diagnostic you add to stderr.
 import { register } from "tsx/esm/api";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -36,5 +36,5 @@ try {
 process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
 
 register();
-const { runAcp } = await import(resolve(repo, "src/acp/run.ts"));
+const { runAcp } = await import(pathToFileURL(resolve(repo, "src/acp/run.ts")).href);
 await runAcp();

package/bin/privateer-harbor.mjs

@@ -7,7 +7,7 @@
 // Invoked two ways: interactively via the bash launcher (`privateer harbor …`), and
 // by the installed launchd/systemd service (`node privateer-harbor.mjs run`).
 import { register } from "tsx/esm/api";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -26,5 +26,5 @@ try {
 process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
 
 register();
-const { runHarborCli } = await import(resolve(repo, "src/cli/harborCli.ts"));
+const { runHarborCli } = await import(pathToFileURL(resolve(repo, "src/cli/harborCli.ts")).href);
 await runHarborCli(process.argv.slice(2));

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
@@ -341,11 +402,11 @@ else {
   const signedIn = fs.existsSync(CRED);
   // Mirrors TINFOIL_MODEL_ID in src/providers/defaultModel.ts — keep them in step; that
   // file carries the measurements behind the choice.
-  const ACCOUNT_MODEL = "privateer/tinfoil/kimi-k2-6";
+  const ACCOUNT_MODEL = "privateer/tinfoil/gpt-oss-120b";
   const MODEL = process.env.PRIVATEER_MODEL
     ? process.env.PRIVATEER_MODEL
     : haveTinfoilKey()
-      ? "tinfoil/kimi-k2-6"
+      ? "tinfoil/gpt-oss-120b"
       : signedIn
         ? ACCOUNT_MODEL
         : haveKey("ANTHROPIC_API_KEY")
@@ -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/privateer.mjs

@@ -4,7 +4,7 @@
 // code and dev keys from the repo. Prefer the `bin/pv` wrapper, which also picks a
 // Node >= 22 (the Pi stack's floor).
 import { register } from "tsx/esm/api";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -19,4 +19,11 @@ try {
 }
 
 register(); // resolves the repo's tsx regardless of the invocation cwd
-await import(resolve(repo, "src/cli/chat.ts"));
+// pathToFileURL, NOT the bare path: on Windows an absolute path starts with a
+// drive letter, and dynamic import() reads "D:\..." as the URL scheme "d:" —
+// ERR_UNSUPPORTED_ESM_URL_SCHEME, before a single line of ours runs. POSIX
+// absolute paths happen to work, which is exactly why this survived so long:
+// every launcher here had it, and `--version` is intercepted upstream in
+// privateer-launch.mjs, so the Windows smoke test booted fine while the actual
+// command was dead. Pinned by tests/launcherImports.test.ts.
+await import(pathToFileURL(resolve(repo, "src/cli/chat.ts")).href);

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-connect.ts

@@ -297,6 +297,20 @@ function pendingFromCatalog(e: CatalogEntry): Pending {
       hint: `Replaces the placeholder ${e.fill}`,
       initial: e.fill,
     });
+  } else if (e.needs === "url") {
+    // A server hosted by an app already running HERE. Nothing to paste, but the
+    // endpoint is the one thing that can differ per machine (Unreal's port and path
+    // are editable in Editor Preferences), and a wrong port is a connector that
+    // saves cleanly and never answers — the failure this catalog exists to avoid.
+    // Pre-filled with the documented default, so <enter> is the common case.
+    steps.push({
+      key: "url",
+      prompt: "Server URL",
+      hint: `Default is ${e.url} — change it only if you moved it.`,
+      initial: e.url,
+      validate: (v) =>
+        /^https?:\/\//i.test(v.trim()) ? undefined : "That needs to be an http:// or https:// URL.",
+    });
   }
   return {
     title: e.label,
@@ -307,12 +321,17 @@ function pendingFromCatalog(e: CatalogEntry): Pending {
       for (const [k, v] of Object.entries(answers)) {
         if (k.startsWith("env:")) env[k.slice(4)] = v;
       }
-      return draftFromCatalog(e, { env, fill: answers.fill });
+      return draftFromCatalog(e, { env, fill: answers.fill, url: answers.url });
     },
     note:
       e.needs === "oauth"
         ? `Authorize it in a browser on THIS machine: /mcp-auth ${e.name}`
-        : undefined,
+        : e.localHttp
+          // Not a warning — a localHttp connector is correct the moment it saves. But
+          // it answers only while its host app is up, so a later failure means "the
+          // app is closed", and saying that now beats debugging it then.
+          ? `Works whenever ${e.label} is running on this machine. Nothing to authorize.`
+          : undefined,
   };
 }
 
@@ -329,6 +348,7 @@ const NEEDS_LABEL: Record<string, string> = {
   token: "needs a token",
   path: "needs a path",
   oauth: "browser sign-in",
+  url: "confirm the URL",
   none: "no setup",
 };