privateer-agent 0.12.34 → 0.12.35

package/README.md

@@ -171,6 +171,13 @@ for how you installed) or check your version with `privateer --version`.
 > `~/.privateer/agent/settings.json`. Linux arm64 and Windows arm64 bundles aren't built
 > yet — arm64 Windows runs the x64 bundle under emulation.
 
+Background-task storage is created only when a task starts, not when you open Privateer.
+Tasks normally write logs to `.pi/tasks` in your working directory. If that directory
+denies writes (for example, Git Bash opened in `C:\Program Files\Git`), Privateer
+uses `~/.privateer/agent/tasks/<project-id>/<run-id>` instead, respecting
+`PRIVATEER_HOME`. The task's output path shows the actual location. This does **not**
+change the working directory for commands or grant permission to edit protected files.
+
 ### Verifying what you're about to run
 
 Privateer is a coding agent — it runs shell commands and edits files, so "should I trust

package/bin/apply-patches.mjs

@@ -67,13 +67,16 @@ export function resolveDep(from, name, ...rest) {
 }
 
 function resolvePatchRoots(repo, patchFiles) {
-  const roots = new Set();
+  const roots = new Map();
   for (const file of patchFiles) {
     // "@earendil-works+pi-coding-agent+0.80.3.patch" -> "@earendil-works/pi-coding-agent"
     const parts = path.basename(file, ".patch").split("+");
     const name = parts[0].startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
     const root = findDepRoot(repo, name);
-    if (root) roots.add(root);
+    if (root) {
+      if (!roots.has(root)) roots.set(root, []);
+      roots.get(root).push(file);
+    }
   }
   return [...roots];
 }
@@ -112,23 +115,35 @@ export function applyPatchesIfNeeded(repo, nodeBin = process.execPath) {
     if (!pp || !fs.existsSync(pp)) return "skipped";
 
     let did = false;
-    for (const root of roots) {
+    for (const [root, files] of roots) {
       const stampFile = path.join(root, "node_modules", ".privateer-patches.json");
       try {
         if (JSON.parse(fs.readFileSync(stampFile, "utf8")).hash === want) continue; // current
       } catch { /* missing or unreadable stamp — (re)apply */ }
 
-      // --patch-dir points at OUR patches even though cwd is wherever the deps landed.
-      // It MUST be relative: patch-package resolves it against cwd, so an absolute path
-      // is silently mangled into a non-existent one and every patch "fails" to apply.
-      const relPatchDir = path.relative(root, patchDir);
-      const r = spawnSync(nodeBin, [pp, "--error-on-fail", "--patch-dir", relPatchDir], {
-        cwd: root,
-        stdio: ["ignore", "ignore", "pipe"],
-        timeout: 60_000,
-        windowsHide: true,
-      });
-      if (r.status !== 0) return "failed";
+      // Different targets can be hoisted to different roots. Apply only the patches
+      // belonging to this root, or patch-package fails on the absent/wrong copy of
+      // another target. Keep the staging dir on the SAME drive on Windows: --patch-dir
+      // must be relative (an absolute path is mangled by patch-package).
+      let stagedDir;
+      try {
+        let sourceDir = patchDir;
+        if (files.length !== patchFiles.length) {
+          stagedDir = fs.mkdtempSync(path.join(root, "node_modules", ".privateer-patches-"));
+          for (const file of files) fs.copyFileSync(path.join(patchDir, file), path.join(stagedDir, file));
+          sourceDir = stagedDir;
+        }
+        const relPatchDir = path.relative(root, sourceDir);
+        const r = spawnSync(nodeBin, [pp, "--error-on-fail", "--patch-dir", relPatchDir], {
+          cwd: root,
+          stdio: ["ignore", "ignore", "pipe"],
+          timeout: 60_000,
+          windowsHide: true,
+        });
+        if (r.status !== 0) return "failed";
+      } finally {
+        if (stagedDir) fs.rmSync(stagedDir, { recursive: true, force: true });
+      }
       did = true;
 
       // Only stamp after a clean apply, so a partial/failed run retries next launch.

package/bin/privateer-launch.mjs

@@ -30,6 +30,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 import { routeUpdate } from "./update-route.mjs";
 import { runToCompletion } from "./run-to-completion.mjs";
+import { configureCompileCache } from "./startup-cache.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
 const REPO = path.resolve(HERE, "..");
@@ -41,15 +42,19 @@ const isWin = process.platform === "win32";
 // Unicode wave blocks and emojis into 3-byte mojibake that wraps and floods the console.
 if (isWin) {
   try {
-    const chcp = process.env.SystemRoot
-      ? path.join(process.env.SystemRoot, "System32", "chcp.com")
-      : "chcp.com";
-    spawnSync(chcp, ["65001"], { stdio: "ignore", windowsHide: true });
+    const comspec = process.env.ComSpec || "cmd.exe";
+    spawnSync(comspec, ["/d", "/s", "/c", "chcp 65001 >nul"], { stdio: "inherit", windowsHide: true });
   } catch {
     /* best effort */
   }
 }
 
+// Suppress upstream update checks: Pi's CLI update banner and pi-background-tasks'
+// update check / footer notice ("bg ⬆ v... /bg-update"). Privateer manages updates
+// at the distribution level via `privateer update` and its own banner.
+if (!process.env.PI_SKIP_VERSION_CHECK) process.env.PI_SKIP_VERSION_CHECK = "1";
+if (!process.env.PI_BG_DISABLE_UPDATE_CHECK) process.env.PI_BG_DISABLE_UPDATE_CHECK = "1";
+
 const PRIVATEER_HOME = process.env.PRIVATEER_HOME || path.join(os.homedir(), ".privateer");
 const ENV_FILE = path.join(REPO, ".env"); // dev-only; a real install has none
 const AGENT_DIR = path.join(PRIVATEER_HOME, "agent");
@@ -348,6 +353,134 @@ if (sub === "update") {
   else updateSelf();
 }
 
+// --- `privateer init [directory]` ------------------------------------------
+// Scaffold a starter PRIVATEER.md project-context file. Runs synchronously and exits
+// immediately — no Pi boot, no splash screen, no API keys needed.
+else if (sub === "init") {
+  const rest = args.slice(1);
+  const help = rest.includes("--help") || rest.includes("-h");
+  const cmd = process.env.PRIVATEER_CMD || "privateer";
+  if (help) {
+    console.log(
+      [
+        `${cmd} init — scaffold a starter PRIVATEER.md project-context file.`,
+        "",
+        `Usage: ${cmd} init [directory]`,
+        "",
+        "Options:",
+        "  -h, --help    Show this help message",
+        "",
+        "Creates a starter PRIVATEER.md in the current directory (or the specified directory).",
+        "Privateer loads this file automatically at startup to give the agent project context.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+
+  const unknownOpt = rest.find((a) => a.startsWith("-"));
+  if (unknownOpt) {
+    console.error(`privateer init: unknown option '${unknownOpt}'`);
+    console.error(`Run '${cmd} init --help' for usage.`);
+    process.exit(1);
+  }
+
+  const positionals = rest.filter((a) => !a.startsWith("-"));
+  if (positionals.length > 1) {
+    console.error(`privateer init: unexpected argument '${positionals[1]}'`);
+    console.error(`Run '${cmd} init --help' for usage.`);
+    process.exit(1);
+  }
+
+  const targetDir = positionals[0] ? path.resolve(positionals[0]) : process.cwd();
+  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+    console.error(`privateer init: directory not found '${targetDir}'`);
+    process.exit(1);
+  }
+
+  const targetFile = path.join(targetDir, "PRIVATEER.md");
+  if (fs.existsSync(targetFile)) {
+    console.log(`PRIVATEER.md already exists at ${targetFile} — left untouched.`);
+    process.exit(0);
+  }
+
+  const template = [
+    "# PRIVATEER.md",
+    "",
+    "Project context for the Privateer agent. Privateer loads this file automatically at",
+    "startup (the same way it loads AGENTS.md / CLAUDE.md) and prepends it to the model's",
+    "system prompt — so put anything the agent should always know about THIS project here.",
+    "",
+    "## Project",
+    "",
+    "<One or two lines: what this project is and what it does.>",
+    "",
+    "## Conventions",
+    "",
+    "- <Coding style, patterns, and idioms to follow.>",
+    "- <Things to avoid.>",
+    "",
+    "## Commands",
+    "",
+    "- build: <command>",
+    "- test: <command>",
+    "- run: <command>",
+    "",
+    "## Notes for the agent",
+    "",
+    "- <Domain context, gotchas, or constraints worth stating once.>",
+    "",
+  ].join("\n");
+
+  try {
+    fs.writeFileSync(targetFile, template, "utf8");
+    console.log(`\x1b[32m✓\x1b[0m Created ${targetFile}`);
+    console.log("  Edit it with your project's context — it loads automatically on every turn.");
+    process.exit(0);
+  } catch (err) {
+    console.error(`privateer init: failed to write ${targetFile} — ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// --- `privateer help [command]` / `privateer --help` ------------------------
+else if (sub === "help" || (args.length === 1 && (args[0] === "--help" || args[0] === "-h"))) {
+  const target = sub === "help" ? args[1] : undefined;
+  const cmd = process.env.PRIVATEER_CMD || "privateer";
+  if (target === "init") {
+    console.log(
+      [
+        `${cmd} init — scaffold a starter PRIVATEER.md project-context file.`,
+        "",
+        `Usage: ${cmd} init [directory]`,
+        "",
+        "Options:",
+        "  -h, --help    Show this help message",
+        "",
+        "Creates a starter PRIVATEER.md in the current directory (or the specified directory).",
+        "Privateer loads this file automatically at startup to give the agent project context.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+  if (target === "update") {
+    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);
+  }
+  printPrivateerHelp(cmd);
+  process.exit(0);
+}
+
 // --- `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
@@ -390,6 +523,10 @@ else if (sub === "acp") {
 
 // --- normal launch: resolve the moat, then exec Pi's TUI with it -----------
 else {
+  // Node 22 can reuse compiled code across launches instead of reparsing Pi and every
+  // provider SDK. Set the child env before any Node spawn; children inherit it too.
+  configureCompileCache(PRIVATEER_HOME);
+
   // Windows has no bash out of the box, but Privateer's command tool needs one. If a
   // real bash isn't reachable, stop here with a clear, actionable message — otherwise
   // the user boots fine and only hits a cryptic `'bash' is not recognized` the first
@@ -447,6 +584,7 @@ else {
   // Suppress Pi's upstream update banner (our banner is the startup surface). Disables
   // ONLY the version fetch — fd/rg can still download on first run.
   if (!process.env.PI_SKIP_VERSION_CHECK) process.env.PI_SKIP_VERSION_CHECK = "1";
+  if (!process.env.PI_BG_DISABLE_UPDATE_CHECK) process.env.PI_BG_DISABLE_UPDATE_CHECK = "1";
 
   // Quiet Pi's built-in startup chatter so our banner is the only greeting. Each key is
   // set only when unset, so a user's own settings.json toggle still wins.
@@ -551,8 +689,21 @@ else {
   // 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 isNonInteractive = args.some(
+    (a) =>
+      a === "-p" ||
+      a === "--print" ||
+      a === "--mode" ||
+      a === "--export" ||
+      a === "--list-models" ||
+      a === "--help" ||
+      a === "-h" ||
+      a === "-v" ||
+      a === "-V" ||
+      a === "--version",
+  );
   const splash = path.join(HERE, "privateer-splash.mjs");
-  if (fs.existsSync(splash)) nodeArgs.push("--import", pathToFileURL(splash).href);
+  if (!isNonInteractive && fs.existsSync(splash)) nodeArgs.push("--import", pathToFileURL(splash).href);
 
   runToCompletion(NODE_BIN, [...nodeArgs, CLI, ...modelArgs, ...extArgs, ...skillArgs, ...args]);
 }
@@ -701,6 +852,74 @@ function warnKeylessLaunch() {
   process.stderr.write(lines.join("\n") + "\n");
 }
 
+function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
+  console.log(
+    [
+      "privateer - Terminal & TUI coding agent with verified privacy and local control",
+      "",
+      "Usage:",
+      `  ${cmd} [options] [--] [@files...] [messages...]`,
+      "",
+      "Commands:",
+      `  ${cmd} init [directory]     Create a starter PRIVATEER.md project-context file`,
+      `  ${cmd} update [--all]       Fetch the latest release or newer tool packs`,
+      `  ${cmd} harbor <command>     Manage the resident background Harbor daemon (run/install/uninstall/status)`,
+      `  ${cmd} verify               Check local installation integrity and patch state`,
+      `  ${cmd} acp                  Run as an Agent Client Protocol server (JSON-RPC on stdio)`,
+      `  ${cmd} install <source>     Install extension source and add to settings`,
+      `  ${cmd} remove <source>      Remove extension source from settings`,
+      `  ${cmd} uninstall <source>   Alias for remove`,
+      `  ${cmd} list                 List installed extensions from settings`,
+      `  ${cmd} config               Open TUI to enable/disable package resources`,
+      `  ${cmd} auth <command>       Print credentials or check provider readiness`,
+      `  ${cmd} <command> --help     Show help for a specific command`,
+      "",
+      "Options:",
+      "  --provider <name>              Provider name",
+      '  --model <pattern>              Model pattern or ID (supports "provider/id" and optional ":<thinking>")',
+      "  --api-key <key>                API key (defaults to env vars)",
+      "  --system-prompt <text>         System prompt (default: coding assistant prompt)",
+      "  --append-system-prompt <text>  Append text or file contents to the system prompt",
+      "  --mode <mode>                  Output mode: text (default), json, or rpc",
+      "  --print, -p                    Non-interactive mode: process prompt and exit",
+      "  --continue, -c                 Continue previous session",
+      "  --resume, -r                   Select a session to resume",
+      "  --session <path|id>            Use specific session file or partial UUID",
+      "  --session-id <id>              Use exact project session ID, creating it if missing",
+      "  --fork <path|id>               Fork specific session file or partial UUID into a new session",
+      "  --session-dir <dir>            Directory for session storage and lookup",
+      "  --no-session                   Don't save session (ephemeral)",
+      "  --name, -n <name>              Set session display name",
+      "  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling",
+      "  --no-tools, -nt                Disable all tools by default (built-in and extension)",
+      "  --no-builtin-tools, -nbt       Disable built-in tools by default",
+      "  --tools, -t <tools>            Comma-separated allowlist of tool names to enable",
+      "  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable",
+      "  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max",
+      "  --extension, -e <path>         Load an extension file (can be used multiple times)",
+      "  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)",
+      "  --skill <path>                 Load a skill file or directory (can be used multiple times)",
+      "  --no-skills, -ns               Disable skills discovery and loading",
+      "  --prompt-template <path>       Load a prompt template file or directory",
+      "  --no-prompt-templates, -np     Disable prompt template discovery and loading",
+      "  --theme <path>                 Load a theme file or directory",
+      "  --use-theme <name[/name]>      Set the initial interactive theme for this run",
+      "  --no-themes                    Disable theme discovery and loading",
+      "  --no-context-files, -nc        Disable PRIVATEER.md, AGENTS.md and CLAUDE.md discovery",
+      "  --export <file>                Export session file to HTML and exit",
+      "  --list-models [search]         List available models (with optional fuzzy search)",
+      "  --verbose                      Force verbose startup",
+      "  --tui-mode <mode>              TUI mode: regular (default) or fullscreen",
+      "  --approve, -a                  Trust project-local files for this run",
+      "  --no-approve, -na              Ignore project-local files for this run",
+      "  --offline                      Disable startup network operations",
+      "  --                             End option parsing; treat remaining arguments as messages/files",
+      "  --help, -h                     Show this help",
+      "  --version, -v, -V              Show version number",
+    ].join("\n"),
+  );
+}
+
 function refreshUpdateCache() {
   const cache = path.join(PRIVATEER_HOME, "update-check.json");
   try {

package/bin/privateer-splash.mjs

@@ -64,10 +64,8 @@ const enabled =
 // than privateer.cmd, the console might still be on OEM CP437.
 if (enabled && process.platform === "win32") {
   try {
-    const chcp = process.env.SystemRoot
-      ? path.join(process.env.SystemRoot, "System32", "chcp.com")
-      : "chcp.com";
-    spawnSync(chcp, ["65001"], { stdio: "ignore", windowsHide: true });
+    const comspec = process.env.ComSpec || "cmd.exe";
+    spawnSync(comspec, ["/d", "/s", "/c", "chcp 65001 >nul"], { stdio: "inherit", windowsHide: true });
   } catch {
     /* best effort */
   }

package/bin/privateer-subagent.mjs

@@ -74,6 +74,8 @@ export function buildChildArgs(originalArgs, repoRoot = REPO, env = process.env)
 
 // Run only when invoked directly (not when imported by the test).
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (!process.env.PI_SKIP_VERSION_CHECK) process.env.PI_SKIP_VERSION_CHECK = "1";
+  if (!process.env.PI_BG_DISABLE_UPDATE_CHECK) process.env.PI_BG_DISABLE_UPDATE_CHECK = "1";
   const args = buildChildArgs(process.argv.slice(2));
   const child = spawn(process.execPath, [piCliPath(), ...args], { stdio: "inherit", env: process.env });
   // Propagate the child's exit faithfully so pi-subagents' parent reads the real

package/bin/startup-cache.d.mts

@@ -0,0 +1 @@
+export function configureCompileCache(privateerHome: string, env?: NodeJS.ProcessEnv): void;

package/bin/startup-cache.mjs

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Set this BEFORE spawning Node: enabling it after importing Pi misses the expensive
+// module graph. Node keys bytecode by runtime version and source contents; /reload
+// still evaluates fresh modules. This is not Jiti's in-memory module cache.
+// Keep it outside the install/project (both may be read-only), under the same home
+// as the rest of this Privateer instance. Only code is cached, not session state.
+export function configureCompileCache(privateerHome, env = process.env) {
+  // Respect Node's own override/opt-out, including an explicitly empty cache path.
+  if (env.NODE_COMPILE_CACHE !== undefined || env.NODE_DISABLE_COMPILE_CACHE === "1") return;
+  try {
+    const dir = path.resolve(privateerHome, "cache", "node-compile");
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    env.NODE_COMPILE_CACHE = dir;
+  } catch {
+    // An unavailable cache must never prevent startup (or print on ACP stdout).
+  }
+}

package/extensions/privateer-models.ts

@@ -30,6 +30,7 @@ import {
   accountPosture,
   fetchAccountCatalog,
 } from "../src/providers/account.ts";
+import { writePiDefaultModel } from "../src/providers/defaultModel.ts";
 
 // A minimal view of Pi's theme (passed to the ui.custom factory) — enough to color
 // text without pulling Pi's internal theme types into an extension.
@@ -353,11 +354,7 @@ export default function privateerModels(pi: {
     argumentHint: "[search]",
     handler: async (args: string, ctx: any): Promise<void> => {
       const ui = ctx?.ui;
-      if (!ui?.custom) {
-        ctx?.ui?.notify?.("The model picker needs an interactive terminal.", "warning");
-        return;
-      }
-      const registry = ctx.modelRegistry;
+      const registry = ctx?.modelRegistry;
       // Refresh so a just-fetched account catalog / models.json edit is reflected.
       try {
         registry?.refresh?.();
@@ -376,13 +373,43 @@ export default function privateerModels(pi: {
 
       let available: ModelLike[] = [];
       try {
-        available = (await registry.getAvailable()) as ModelLike[];
+        available = (await registry?.getAvailable?.()) as ModelLike[] ?? [];
       } catch (e) {
-        ui.notify?.(`Couldn't list models: ${(e as Error).message}`, "error");
+        ui?.notify?.(`Couldn't list models: ${(e as Error).message}`, "error");
         return;
       }
       if (!available.length) {
-        ui.notify?.("No models available. Use /login to add a provider.", "warning");
+        ui?.notify?.("No models available. Use /login to add a provider.", "warning");
+        return;
+      }
+
+      const initialQuery = String(args ?? "").trim();
+      if (!ui?.custom) {
+        if (initialQuery) {
+          const match = available.find(
+            (m) => `${m.provider}/${m.id}` === initialQuery || m.id === initialQuery,
+          );
+          if (match) {
+            try {
+              const ok = await pi.setModel!(match);
+              if (ok === false) {
+                ui?.notify?.(`No API key for ${match.provider}/${match.id}.`, "warning");
+                return;
+              }
+              writePiDefaultModel(`${match.provider}/${match.id}`);
+              const tier = baselineTier(match.provider, match.id);
+              ui?.notify?.(
+                `Model: ${match.provider}/${match.id}  ·  ${TIERS[tier].label}`,
+                "info",
+              );
+              return;
+            } catch (e) {
+              ui?.notify?.(`Couldn't switch model: ${(e as Error).message}`, "error");
+              return;
+            }
+          }
+        }
+        ui?.notify?.("The model picker needs an interactive terminal.", "warning");
         return;
       }
 
@@ -394,7 +421,6 @@ export default function privateerModels(pi: {
         tier: baselineTier(m.provider, m.id),
       }));
 
-      const initialQuery = String(args ?? "").trim();
       const chosen: Row | undefined = await ui.custom(
         (tui: TuiLike, theme: ThemeLike, _kb: unknown, close: (result?: Row) => void) => {
           const picker = new ModelsPicker({
@@ -417,6 +443,7 @@ export default function privateerModels(pi: {
           ui.notify?.(`No API key for ${chosen.provider}/${chosen.id}.`, "warning");
           return;
         }
+        writePiDefaultModel(`${chosen.provider}/${chosen.id}`);
         ui.notify?.(
           `Model: ${chosen.provider}/${chosen.id}  ·  ${TIERS[chosen.tier].label}`,
           "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.34",
+  "version": "0.12.35",
   "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",
@@ -90,7 +90,7 @@
     "privateer-workflow": "0.1.0",
     "tinfoil": "1.1.11",
     "tsx": "4.23.0",
-    "typebox": "1.3.4",
+    "typebox": "1.3.7",
     "undici": "7.29.0",
     "ws": "8.21.0",
     "yaml": "2.9.0",

package/patches/@earendil-works+pi-coding-agent+0.84.4.patch

@@ -387,7 +387,23 @@ index bb022d4..382ff2b 100644
  // NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,
  // avoiding a circular dependency. Extensions can import from @earendil-works/pi-coding-agent.
  import * as _bundledPiCodingAgent from "../../index.js";
-@@ -621,9 +621,23 @@ export async function discoverAndLoadExtensions(configuredPaths, cwd, agentDir =
+@@ -419,11 +419,14 @@ async function loadExtensionModule(extensionPath, cacheToken) {
+         // Compiled binaries and the bundled Node distribution use embedded modules.
+         // Source TypeScript reuses host modules and root tsconfig paths. Unbundled
+         // Node builds use dist aliases.
++        // Privateer: reuse the host's Pi/Typebox namespaces in Node builds too.
++        // Otherwise each extension can reload that graph through Jiti. Aliases
++        // remain a fallback for non-virtual imports; extension reload is unchanged.
+         ...(isBunBinary || isNodeSeaBinary || isBundledNode
+             ? { virtualModules: VIRTUAL_MODULES, tryNative: false }
+             : isTypeScriptSourceRuntime
+                 ? { virtualModules: VIRTUAL_MODULES, tsconfigPaths: true }
+-                : { alias: getAliases() }),
++                : { virtualModules: VIRTUAL_MODULES, alias: getAliases() }),
+     });
+     const module = await jiti.import(extensionPath, { default: true });
+     const factory = module;
+@@ -621,9 +624,23 @@ export async function discoverAndLoadExtensions(configuredPaths, cwd, agentDir =
              }
          }
      };

package/patches/pi-background-tasks+2.4.2.patch

@@ -0,0 +1,110 @@
+diff --git a/node_modules/pi-background-tasks/src/core/registry.ts b/node_modules/pi-background-tasks/src/core/registry.ts
+index cfbf133..c632390 100644
+--- a/node_modules/pi-background-tasks/src/core/registry.ts
++++ b/node_modules/pi-background-tasks/src/core/registry.ts
+@@ -1,11 +1,11 @@
+ import { spawn as nodeSpawn, type SpawnOptions } from 'node:child_process';
+-import { randomBytes } from 'node:crypto';
++import { createHash, randomBytes } from 'node:crypto';
+ import { createWriteStream, existsSync } from 'node:fs';
+ import { mkdir, realpath, writeFile } from 'node:fs/promises';
+-import { join } from 'node:path';
++import { join, resolve } from 'node:path';
+ import type { Api, Model } from '@earendil-works/pi-ai';
+ import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+-import { formatSize } from '@earendil-works/pi-coding-agent';
++import { formatSize, getAgentDir } from '@earendil-works/pi-coding-agent';
+ import {
+   boundedRead,
+   deriveTaskNameFromCommand,
+@@ -781,9 +781,29 @@ export class BackgroundTaskRegistry {
+     if (this.runtimeDir) return this.runtimeDir;
+     const sessionId = sanitizePathSegment(ctx.sessionId ?? `session-${String(process.pid)}`);
+     const runId = `${sessionId}-${String(process.pid)}`;
+-    const runtimeDirAbs = join(ctx.cwd, '.pi', 'tasks', runId);
+-    const runtimeDirDisplay = join('.pi', 'tasks', runId);
+-    await mkdir(runtimeDirAbs, { recursive: true });
++    let runtimeDirAbs = join(ctx.cwd, '.pi', 'tasks', runId);
++    let runtimeDirDisplay = join('.pi', 'tasks', runId);
++    try {
++      await mkdir(runtimeDirAbs, { recursive: true });
++    } catch (error) {
++      // Privateer: Git Bash can open in Program Files. Keep the command cwd,
++      // but store task artifacts in the user's agent dir when cwd is protected.
++      const code = (error as NodeJS.ErrnoException).code;
++      if (code !== 'EACCES' && code !== 'EPERM' && code !== 'EROFS') throw error;
++      const projectDir = runtimeDirAbs;
++      const projectId = createHash('sha256').update(resolve(ctx.cwd)).digest('hex').slice(0, 16);
++      runtimeDirAbs = resolve(getAgentDir(), 'tasks', projectId, runId);
++      // Never describe an external artifact as project-relative.
++      runtimeDirDisplay = runtimeDirAbs;
++      try {
++        await mkdir(runtimeDirAbs, { recursive: true, mode: 0o700 });
++      } catch (fallbackError) {
++        throw new Error(
++          `Cannot create background task storage at ${projectDir} (${code}) or ${runtimeDirAbs}: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`,
++          { cause: fallbackError },
++        );
++      }
++    }
+     this.runtimeDir = { abs: runtimeDirAbs, display: runtimeDirDisplay };
+     return this.runtimeDir;
+   }
+diff --git a/node_modules/pi-background-tasks/src/extension.ts b/node_modules/pi-background-tasks/src/extension.ts
+index 3afbd8e..d003a57 100644
+--- a/node_modules/pi-background-tasks/src/extension.ts
++++ b/node_modules/pi-background-tasks/src/extension.ts
+@@ -473,14 +473,15 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+   pi.on('session_start', async (_event, ctx) => {
+     registry.setShuttingDown(false);
+     currentCtx = ctx;
+-    await registry.ensureRuntimeDir(ctx);
++    // Privateer: no project writes just to open a session. Each task-start path
++    // creates its runtime directory on demand, with a per-user fallback.
+     updateUi(ctx);
+     if (statusInterval) clearInterval(statusInterval);
+     statusInterval = setInterval(() => {
+       updateUi();
+     }, STATUS_INTERVAL_MS);
+-    // One-shot, non-blocking: never awaited on the session-start path or the status tick.
+-    void scheduleUpdateCheck(ctx);
++    // Privateer: update check disabled. Privateer manages updates at the distribution
++    // level via `privateer update`; individual tool packs shouldn't check npm or prompt /bg-update.
+   });
+ 
+   pi.on('session_shutdown', async (_event, ctx) => {
+@@ -565,22 +566,11 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+   });
+ 
+   pi.registerCommand('bg-update', {
+-    description: 'Show how to update pi-background-tasks to the latest published version',
++    description: 'Show update guidance for background tasks in Privateer',
+     handler: (_args, ctx) => {
+-      const current = PACKAGE_VERSION ?? 'unknown';
+-      const latest = latestKnownVersion;
+-      const pinnedNpm = latest ? `${PACKAGE_NAME}@${latest}` : `${PACKAGE_NAME}@<version>`;
+       const lines = [
+-        latest
+-          ? `pi-background-tasks ${current} is installed; ${latest} is the latest published version.`
+-          : `pi-background-tasks ${current} is installed.`,
+-        'Update from npm:',
+-        `  pi install npm:${PACKAGE_NAME}@latest`,
+-        `  pi install npm:${pinnedNpm}`,
+-        'Git releases are independent of npm versions; use main only when you want current repository state:',
+-        `  pi install ${GIT_INSTALL_TARGET}@main`,
+-        `For a pinned git release, first verify the tag exists, then use ${GIT_INSTALL_TARGET}@<existing-tag>.`,
+-        'This command only prints update instructions; it does not install or self-update.',
++        'pi-background-tasks is built into Privateer.',
++        'To update Privateer and bundled tools, run: privateer update',
+       ];
+       ctx.ui.notify(lines.join('\n'), 'info');
+       return Promise.resolve();
+@@ -682,7 +672,7 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+   pi.registerTool<typeof BgRunParams, BgRunDetails>({
+     name: 'bg_run',
+     label: 'Background Run',
+-    description: `Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to ${formatSize(MAX_LOG_BYTES)}.`,
++    description: `Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks (or per-user agent storage when the project denies writes); use the returned output path. Model-visible logs are bounded to ${formatSize(MAX_LOG_BYTES)}.`,
+     promptSnippet:
+       'Start a named long-running shell command; default terminal notification wakes a follow-up turn, so yield instead of polling',
+     promptGuidelines: [

package/src/boot.ts

@@ -38,6 +38,13 @@ process.env[PI_AGENT_DIR_ENV] ??= agentDir();
 // (2) Install the attestation dispatcher (idempotent).
 installAttestationDispatcher();
 
+// (3) Suppress upstream update checks: Pi's CLI update banner and pi-background-tasks'
+// update check / footer notice ("bg ⬆ v... /bg-update"). Privateer manages updates
+// at the distribution level via `privateer update` and its own banner; individual
+// bundled tool packs must not query npm or display `/bg-update`.
+process.env.PI_SKIP_VERSION_CHECK ??= "1";
+process.env.PI_BG_DISABLE_UPDATE_CHECK ??= "1";
+
 // Marker other modules can assert on to catch an accidental "imported Pi before
 // boot" regression during development.
 export const BOOTED = true;

package/src/bridge/engineAdapter.ts

@@ -10,9 +10,9 @@
 //   - `finish` carries usage + finishReason,
 //   - compaction / auto-retry / agent-end-error mapped through.
 //
-// Field names for the compaction/retry/error events are best-effort against Pi
-// 0.80 and marked TODO(verify) — Phase 1's test (`tests/engine.test.ts`, ported
-// from tree-cli) asserts the mapping against a real event stream and pins them.
+// Pi's turn_end is ONE model response plus tools, not the user's whole run.
+// agent_end can still be followed by retries/compaction. Only agent_settled
+// (Pi 0.84) is terminal; keeping this distinction preserves the app's busy pill.
 
 import {
   addUsage,
@@ -55,7 +55,7 @@ function textOf(result: unknown): string {
   const parts = (result as any)?.content;
   if (Array.isArray(parts)) return parts.map((p: any) => p.text ?? `[${p.type}]`).join("");
   try {
-    return JSON.stringify(result);
+    return JSON.stringify(result) ?? "";
   } catch {
     return String(result);
   }
@@ -70,9 +70,16 @@ function num(v: unknown, fallback = 0): number {
 // each Pi event; feed each through in `session.subscribe`.
 export function createEngineEventAdapter() {
   let sessionTotal: UsageTotals = emptyUsage();
+  let turnTotal: UsageTotals = emptyUsage();
+  let lastMessage: any;
+  let terminalSent = false;
 
   function toEngineEvents(ev: PiSessionEvent): EngineEvent[] {
     switch (ev.type) {
+      case "agent_start":
+        terminalSent = false;
+        return [];
+
       case "message_update": {
         const a = ev.assistantMessageEvent as any;
         if (a?.type === "text_delta") return [{ type: "text", text: a.delta }];
@@ -90,6 +97,16 @@ export function createEngineEventAdapter() {
           },
         ];
 
+      // Pi partial results are snapshots, NOT deltas. Transports bound these;
+      // cloud redaction must see the full text BEFORE any tail truncation.
+      case "tool_execution_update":
+        return [{
+          type: "tool-progress",
+          id: ev.toolCallId as string,
+          name: ev.toolName as string,
+          output: textOf(ev.partialResult),
+        }];
+
       case "tool_execution_end":
         return ev.isError
           ? [
@@ -113,43 +130,35 @@ export function createEngineEventAdapter() {
         const msg = ev.message as any;
         const turn = normUsage(msg?.usage);
         sessionTotal = addUsage(sessionTotal, turn);
-        const finishReason =
-          (ev.finishReason as string) ?? (msg?.stopReason as string) ?? "stop";
-        const out: EngineEvent[] = [{ type: "usage", usage: sessionTotal, turn }];
-        // A FAILED turn ends here, not by throwing — and this is the only place the
-        // app can learn it failed.
-        //
-        // Pi reports a dead model call as an assistant message with
-        // `stopReason: "error"` and an `errorMessage`; `prompt()` then resolves
-        // NORMALLY, so the desktop's runTurn catch never fires. Our own pi patch
-        // widened that path deliberately (a hard 4xx, and a 429 that outlived the
-        // retry budget, both end the turn instead of re-entering the agent loop),
-        // which is right for the CLI — its TUI reads the assistant message and
-        // prints describeErrorText. The app reads EngineEvents, and this adapter
-        // used to drop `errorMessage` on the floor: the turn arrived as a bare
-        // `finish`, which RemoteDriveContext closes as a green ✓ "done". A signed-in
-        // user whose first turn 401'd or hit their cap saw a tick and no words.
-        //
-        // So say it. Same wording the terminal gets, ahead of the finish so the feed
-        // reads in order, and redacted either way because an unrecognised body goes
-        // out verbatim.
+        turnTotal = addUsage(turnTotal, turn);
+        lastMessage = msg;
+        return [{ type: "usage", usage: sessionTotal, turn: turnTotal }, { type: "step-finish" }];
+      }
+
+      case "agent_settled": {
+        if (terminalSent) return [];
+        terminalSent = true;
+        const msg = lastMessage;
+        lastMessage = undefined;
+        turnTotal = emptyUsage();
+        // Failed model calls often resolve prompt() normally. Delay the error
+        // until retries/overflow recovery are exhausted, but never hide it.
         if (msg?.stopReason === "error") {
           const raw = typeof msg.errorMessage === "string" ? msg.errorMessage : "";
           const described = describeErrorText(raw);
-          out.push({
+          return [{
             type: "error",
             error: described?.message ?? redactText(raw || "The model call failed."),
             ...(described?.hint ? { hint: described.hint } : {}),
             ...(described?.retryable != null ? { retryable: described.retryable } : {}),
-          });
+          }];
         }
-        out.push({ type: "finish", usage: sessionTotal, finishReason });
-        return out;
+        if (msg?.stopReason === "aborted") return [{ type: "aborted" }];
+        return [{ type: "finish", usage: sessionTotal, finishReason: msg?.stopReason ?? "stop" }];
       }
 
-      // Compaction: Pi collapses history to free context. TODO(verify) field
-      // names for before/after token counts against a real compaction event.
       case "compaction_start":
+        return [{ type: "step-finish" }];
       case "compaction_end":
         return [
           {
@@ -173,28 +182,17 @@ export function createEngineEventAdapter() {
           },
         ];
 
-      // Terminal error surfaced at the end of an agent run.
-      //
-      // ⚠️ Pi 0.84's `agent_end` is `{ messages, willRetry }` — there is NO `error`
-      // field, so this branch has been returning [] for every run since the 0.84
-      // refactor. It is kept (harmless, and other Pi versions have carried one)
-      // but it is NOT the error path: a failed model call arrives on `turn_end`
-      // above, which is where the real mapping lives. Do not "restore" error
-      // reporting here and delete it there.
-      case "agent_end": {
-        const err = (ev as any).error;
-        if (!err) return [];
-        return [
-          {
-            type: "error",
-            error: typeof err === "string" ? err : (err.message ?? String(err)),
-            retryable: Boolean((ev as any).retryable),
-          },
-        ];
-      }
+      // agent_end is only a low-level loop boundary. willRetry:false still
+      // permits overflow compaction and queued continuation; never finish here.
+      case "agent_end":
+        return [];
 
       case "abort":
       case "aborted":
+        if (terminalSent) return [];
+        terminalSent = true;
+        lastMessage = undefined;
+        turnTotal = emptyUsage();
         return [{ type: "aborted" }];
 
       default:

package/src/engine/errors.ts

@@ -117,6 +117,30 @@ export function isAccountCapCode(code: string | null | undefined): boolean {
   return typeof code === "string" && CAP_CODE.test(code);
 }
 
+/**
+ * Balance guidance for the signed-in Privateer account channel ONLY. A bare 429
+ * is not evidence of an empty balance; neither is a daily cap or provider quota.
+ * The SDK may retain the JSON body (flat or OpenAI-shaped), or just its message.
+ */
+export function describeAccountBalanceError(text: string): DescribedError | null {
+  if (!/^\s*(?:402|429)\b/.test(text) || /<!doctype html|<html[\s>]/i.test(text)) return null;
+  const bodyStart = text.indexOf("{");
+  const facts = bodyStart < 0 ? {} : extract({ responseBody: text.slice(bodyStart) });
+  const code = facts.code;
+  const message = facts.providerMessage ?? text;
+  const balanceCode = /^(?:INSUFFICIENT_(?:BALANCE|FUNDS|CREDITS?)|(?:BALANCE|CREDITS?)_EXHAUSTED)$/i;
+  const balanceText = /\b(?:insufficient (?:credit(?:s| balance)?|balance|funds)|out of credits?|(?:credit balance|balance|credits?) (?:is |are )?exhausted)\b/i;
+  // If a machine code exists, it decides — don't turn a rate limit whose help
+  // text mentions credits into a billing failure.
+  if (code ? !balanceCode.test(code) : !balanceText.test(message)) return null;
+  return {
+    message: "Your Privateer account has insufficient balance.",
+    // Use our known destination, never a URL copied from an untrusted error body.
+    hint: "Top up at https://privateer.pro/top-up, then try again.",
+    retryable: false,
+  };
+}
+
 // ── Oversized / non-API error bodies ─────────────────────────────────────────
 //
 // An inference endpoint does not always answer as an API. Put a WAF, a proxy or a

package/src/engine/events.ts

@@ -18,6 +18,8 @@ export type EngineEvent =
   | { type: "text"; text: string }
   | { type: "reasoning"; text: string }
   | { type: "tool-call"; id: string; name: string; input: unknown }
+  // Latest output snapshot; transports bound it, without settling the running card.
+  | { type: "tool-progress"; id: string; name: string; output: string }
   | { type: "tool-result"; id: string; name: string; output: unknown }
   | { type: "tool-error"; id: string; name: string; error: string }
   | { type: "step-finish" }
@@ -42,7 +44,7 @@ export type EngineEvent =
   // engine — the engine has no clock and no view of the turn as a whole.
   //
   // It exists because silence is ambiguous and the app cannot resolve it: a tool
-  // call emits at its start and its end and nothing in between, so a fifteen-minute
+  // call may emit at its start and its end with nothing in between, so a fifteen-minute
   // build, a stalled model socket and a dead agent all look identical from the far
   // side of the relay. This is the frame that says which. `tool`/`toolMs` name what
   // is being waited on when something is.

package/src/providers/account.ts

@@ -27,6 +27,8 @@ import { join } from "node:path";
 import { globalDir } from "../config/paths.ts";
 import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts";
 import { installGzipRequestBodies } from "../util/gzipRequestBody.ts";
+import { describeAccountBalanceError } from "../engine/errors.ts";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
 import { ACCOUNT_DEFAULT_MODEL_ID, ACCOUNT_NEAR_MODEL_ID, ensurePiDefaultModel } from "./defaultModel.ts";
 import { visionInput } from "./vision.ts";
@@ -650,7 +652,7 @@ export function registerAccountModels(pi: {
 export function makeAccountProvider() {
   return (pi: {
     registerProvider?: (name: string, config: unknown) => void;
-    on?: (event: string, handler: (e: unknown, ctx: unknown) => void) => void;
+    on?: (event: string, handler: (e: unknown, ctx: unknown) => unknown) => void;
   }): void => {
     if (typeof pi.registerProvider !== "function") return;
     // Compress this channel's inference bodies before anything can send one. The edge
@@ -710,14 +712,22 @@ export function makeAccountProvider() {
       }
     });
 
-    // message_end: an assistant turn that ended in an auth error on the account channel
-    // means our session token is dead server-side. Pi has no reactive-401 refresh, so
-    // replace the session now instead of failing every prompt until `expires`.
-    // See recoverAccountSession.
+    // Replace confirmed balance failures before Pi renders/persists the message.
+    // showError alone misses first-attempt failures (the assistant component renders
+    // those directly). This also covers print mode and the remote event adapter.
     pi.on?.("message_end", (e, ctx) => {
-      const msg = (e as { message?: { role?: string; stopReason?: string; errorMessage?: string } })?.message;
+      const msg = (e as { message?: AssistantMessage })?.message;
       if (msg?.role !== "assistant" || msg.stopReason !== "error" || !msg.errorMessage) return;
-      if ((ctx as SeedContext)?.model?.provider !== "privateer") return;
+      if (msg.provider !== "privateer") return;
+      const balance = hasCredentials() ? describeAccountBalanceError(msg.errorMessage) : null;
+      if (balance) {
+        // Normalize the known billing failure to Payment Required, just as
+        // authedFetch does for cap responses. Keeping a hard status first stops
+        // Pi retrying/compacting into the same exhausted account.
+        return { message: { ...msg, errorMessage: `402 ${balance.message}\n${balance.hint}` } };
+      }
+      // An auth failure, unlike a balance failure, needs a fresh child session.
+      // Pi has no reactive-401 refresh; see recoverAccountSession.
       void recoverAccountSession(ctx, msg.errorMessage);
     });
   };

package/src/providers/defaultModel.ts

@@ -10,7 +10,7 @@
 // never nominated a model. resolveDefaultModel() makes the account channel the default
 // the moment credentials exist, and keeps the legacy BYO behaviour otherwise.
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { hasCredentials } from "../auth/privateer.ts";
 import { agentDir } from "../config/paths.ts";
@@ -282,8 +282,10 @@ export function writePiDefaultModel(spec: string): string | null {
 function writeSettingsDefaultModel(spec: string, onlyIfUnset: boolean): string | null {
   const parts = splitSpec(spec);
   if (!parts) return null;
-  const settingsPath = join(agentDir(), "settings.json");
+  const dir = agentDir();
+  const settingsPath = join(dir, "settings.json");
   try {
+    mkdirSync(dir, { recursive: true });
     let settings: Record<string, unknown> = {};
     if (existsSync(settingsPath)) {
       const raw = readFileSync(settingsPath, "utf8").trim();

package/src/remote/relayClient.ts

@@ -353,6 +353,8 @@ function projectEvent(ev: EngineEvent): Record<string, unknown> {
   switch (ev.type) {
     case "tool-call":
       return { type: "tool-call", id: ev.id, name: ev.name, input: safe(asText(ev.input), 2000) };
+    case "tool-progress":
+      return { type: "tool-progress", id: ev.id, name: ev.name, output: redactSecrets(ev.output).slice(-4000) };
     case "tool-result":
       return { type: "tool-result", id: ev.id, name: ev.name, output: safe(asText(ev.output), 4000) };
     case "tool-error":