privateer-agent 0.12.7 → 0.12.10

package/README.md

@@ -12,9 +12,6 @@
   <a href="https://www.npmjs.com/package/privateer-agent">
     <img src="https://img.shields.io/npm/v/privateer-agent" alt="npm" />
   </a>
-  <a href="https://www.npmjs.com/package/privateer-agent">
-    <img src="https://img.shields.io/npm/dm/privateer-agent" alt="npm downloads" />
-  </a>
   <a href="https://github.com/privateer-agent/privateer-agent/releases">
     <img src="https://img.shields.io/badge/changelog-what's%20new-5b8def" alt="Changelog" />
   </a>
@@ -125,7 +122,7 @@ silently. The moat is swappable; the floor under it holds.
   shots stay continuous, cut them together, then score and narrate the result. Generated media
   is handed straight back as files on your machine; none of it is stored in our cloud. See
   [docs/media-generation.md](docs/media-generation.md).
-- **Talk to it.** `/speak on` reads answers aloud as they're written; **ctrl+x** is push-to-talk
+- **Talk to it.** `/speak on` reads answers aloud as they're written; **alt+t** is push-to-talk
   and the mic closes when you stop talking. Your OS voice by default — nothing leaves the
   machine — or your account's confidential-compute TTS/STT once you sign in. `/talk loop on`
   makes it hands-free. See [Talk to it](#talk-to-it--voice-both-directions).
@@ -187,9 +184,31 @@ npm view privateer-agent dist.attestations   # published from CI with npm proven
 npm audit signatures                         # verify registry signatures + provenance
 ```
 
-The package also declares **no install scripts** — no `postinstall`, nothing. Installing
-it writes files and executes nothing; `npm install -g privateer-agent --ignore-scripts`
-gives an identical result. Code runs only when you run `privateer`.
+And **after** installing — the check nobody else offers, because every signal above is
+an install-time one:
+
+```bash
+privateer verify        # is the install on THIS disk still the one we published?
+```
+
+It reports the install shape, whether this exact version is published and carries a
+provenance attestation, whether any dependency has drifted from its pinned version,
+and which launch-time patches are applied. Inconclusive checks say so rather than
+counting as a pass; `--offline` skips the ones that need the registry.
+
+The package also declares **no install scripts** — no `postinstall`, nothing — so
+nothing we publish executes at install time, and `--ignore-scripts` gives an identical
+result. That is a claim about *our* tarball, not your whole install: a handful of
+packages in the ~500-package dependency tree do declare install hooks, and none of them
+are needed here, so the install we recommend and test is
+
+```bash
+npm install -g privateer-agent --ignore-scripts
+```
+
+Or skip the dependency graph entirely with a bundle (the `curl | sh` one-liner above),
+which verifies a published SHA-256 and, from the next release on, a signed build
+attestation before it unpacks anything.
 
 See [SECURITY.md](SECURITY.md) for the threat model, the permission gate, and how to
 report a vulnerability.
@@ -295,11 +314,11 @@ with `/signout`; manage linked terminals from the app.
 ## Talk to it — voice, both directions
 
 `/speak on` and answers are read aloud **as they are written**, sentence by sentence, with
-code blocks, tables and URLs stripped. Press **ctrl+x** and talk; the mic closes when you
+code blocks, tables and URLs stripped. Press **alt+t** and talk; the mic closes when you
 stop talking and the transcript lands in the composer for you to read before Enter sends it.
 
 ```
-/speak on             read answers aloud    ctrl+x    push to talk (press again to send)
+/speak on             read answers aloud    alt+t     push to talk (press again to send)
 /speak voice <name>   pick a speaker        /talk     the same thing, typed
 /speak rate <n>       0.5–3× pace           /talk loop on   conversation mode, hands-free
 /speak stream off     wait for the full answer instead of speaking as it arrives
@@ -610,7 +629,7 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/signin` · `/signout` | sign in to a Privateer account (device flow) / sign out |
 | `/remote-access` | link this terminal to the app and allow it to drive (off by default) |
 | `/connect` · `/mcp` | add, enable, or remove MCP connectors / see what actually connected |
-| `/speak` · `/talk` | read answers aloud / voice input (**ctrl+x** is push-to-talk) |
+| `/speak` · `/talk` | read answers aloud / voice input (**alt+t** is push-to-talk) |
 | `/extensions` | list loaded Pi extensions |
 | `/init` | scaffold a starter `PRIVATEER.md` in this directory |
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |

package/SECURITY.md

@@ -12,11 +12,27 @@ Privateer is a terminal coding agent: it reads and writes files, runs shell comm
 talks to model providers on your behalf. That is the point of it, and it is also the
 threat model. Two things are worth verifying rather than taking on faith.
 
-**The package runs no install scripts.** There is no `preinstall`, `install`,
-`postinstall` or `prepare` hook. `npm install -g privateer-agent` writes files and
-executes nothing; installing with `--ignore-scripts` produces an identical result. Code
-runs only when you run `privateer`. (Dependency patching happens at first launch — see
-`bin/apply-patches.mjs` and `docs/shipping.md`.)
+**This package runs no install scripts.** There is no `preinstall`, `install`,
+`postinstall` or `prepare` hook in `privateer-agent`: nothing we publish executes at
+install time, and installing with `--ignore-scripts` produces an identical result. Our
+code runs only when you run `privateer`. (Dependency patching happens at first launch —
+see `bin/apply-patches.mjs` and `docs/shipping.md`.)
+
+That is a claim about *our* tarball, not about your whole install, and the difference
+matters. `npm install -g privateer-agent` resolves a tree of roughly 500 packages, and
+seven of them do declare install scripts — `esbuild`, `koffi`, `fsevents`, `protobufjs`
+(×2) and `@google/genai` (×2). On a default npm config those execute on your machine, as
+they would for anything else that depends on them. Every one is a build-from-source or
+compatibility-warning fallback we don't need, so install with scripts off:
+
+```bash
+npm install -g privateer-agent --ignore-scripts
+```
+
+That is the install we test and the shape CI publishes from, and it produces a working
+`privateer`. To skip the dependency graph altogether, use a release bundle
+(`curl -fsSL https://privateer.pro/install.sh | sh`): a fixed set of files with a pinned
+Node, no resolution step on your machine at all.
 
 **Releases carry npm provenance.** Published from `.github/workflows/release.yml` with
 `npm publish --provenance`, so npm holds a signed Sigstore attestation binding the
@@ -29,6 +45,26 @@ npm view privateer-agent dist.attestations   # attestation metadata exists
 npm audit signatures                          # verifies registry signatures + provenance
 ```
 
+**You can re-check the install later.** Everything above is an install-time signal, which
+is not much use to someone asking the question weeks afterwards. `privateer verify` reads
+the install actually on disk and reports the shape it took, whether this version is
+published with provenance, whether any dependency has drifted from its pinned version,
+and which launch-time patches are applied. It distinguishes "verified" from "couldn't
+check" and never reports the second as the first. It is not a security boundary — anything
+that can rewrite `node_modules` can rewrite the checker — but it catches the accidental
+and opportunistic cases, which is nearly all of them.
+
+**Bundle downloads are verified before they unpack.** `install.sh` / `install.ps1` fetch
+the release's published SHA-256 and refuse to install on a mismatch, a missing digest, or
+a machine with no way to compute one (`PRIVATEER_SKIP_CHECKSUM=1` overrides, loudly). A
+checksum served from the same origin as the file proves integrity but not provenance, so
+from the release following this change the bundles also carry a GitHub build attestation,
+which the installers verify automatically when `gh` is available:
+
+```bash
+gh attestation verify privateer-darwin-arm64.tar.gz --repo privateer-agent/privateer-agent
+```
+
 If a version lacks provenance, it did not come from this workflow. Treat that as
 suspicious and report it — with one documented exception: **0.6.7 is the first release
 published this way.** Trusted publishing was misconfigured until then, so every earlier

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
@@ -233,6 +294,16 @@ else if (sub === "harbor" || sub === "daemon") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)]);
 }
 
+// --- `privateer verify` ----------------------------------------------------
+// Check the install that is on this disk right now. Every other trust signal we
+// publish is an install-time one (npm provenance at `npm i`, a checksum inside
+// install.sh, a badge on a web page nobody revisits); this is the one a user can
+// run afterwards, on the machine they're worried about. Runs BEFORE ensurePatches
+// so it can report the real patch state rather than the state it just created.
+else if (sub === "verify") {
+  runToCompletion(NODE_BIN, [path.join(REPO, "bin", "privateer-verify.mjs"), ...args.slice(1)]);
+}
+
 // --- `privateer acp` -------------------------------------------------------
 // Privateer as an Agent Client Protocol server, spawned by an ACP host (Buzz's
 // `buzz-acp`, Zed, …) and driven over newline-delimited JSON-RPC on stdio.
@@ -402,6 +473,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-verify.d.mts

@@ -0,0 +1,10 @@
+// Types for `privateer verify`. The implementation is plain .mjs for the same
+// reason apply-patches.mjs is: bin/ runs under a bare `node`, before any transpiler.
+
+/**
+ * Check the install rooted at `repo` and print a report. Returns a process exit
+ * code: 0 when nothing FAILED (inconclusive checks are not failures), 1 otherwise.
+ *
+ * `offline` skips every check that needs the npm registry.
+ */
+export function verify(opts: { repo: string; offline?: boolean }): Promise<number>;