privateer-agent 0.13.0 → 0.14.1

package/README.md

@@ -54,6 +54,10 @@ Privateer runs in three places, over one account and one config: the **terminal*
 - **Privacy you can verify, not just trust.** Confidential-enclave (TEE) inference is
   cryptographically **attested** — not a policy promise — and an **on-device PII gate**
   warns before structured personal data ever leaves your machine for an unverified model.
+- **A private subagent for your other agents.** Claude Code, Codex, or your own orchestrator
+  can hand Privateer the files it shouldn't read itself: `privateer -p --private "…"` reads
+  them on your machine, reasons over them in an attested enclave, and returns only the
+  answer. See [Hand off sensitive work](#hand-off-sensitive-work-to-privateer).
 - **It's Pi underneath.** Privateer is a distribution of the [Pi](https://pi.dev) coding agent —
   every Pi extension, skill, and command works, and Privateer's own features are just extensions
   you can read, swap, or build on. Nothing to compile. See [Built on Pi](#built-on-pi).
@@ -475,10 +479,30 @@ privateer harbor uninstall
 ```
 
 Installs as a **launchd user agent** on macOS or a **`systemd --user` unit** on Linux — no
-root, no sudo. (There's no Windows service path yet; use `privateer harbor run`.)
+root, no sudo. (There's no Windows service path yet; use `privateer harbor run`.) Logs go to
+`~/.privateer/harbor.log` on macOS (kept under 5 MB, one previous copy as `harbor.log.1`) and
+to the journal on Linux: `journalctl --user -u privateer-harbor`.
 
 Everything the harbor does still runs through the permission gate. Actions needing approval
-surface in the app; routines you approved once run on their own schedule.
+surface in the app; routines you approved once run on their own schedule. Unattended runs
+are confined to their working directory and can't read credential stores (`~/.ssh`,
+`~/.aws`, Privateer's own login and config files), whatever tools they're allowed.
+
+**Chat channels** (Telegram, Slack, Discord, WhatsApp) run beside it, as their own service:
+
+```bash
+privateer channels install    # login service; re-run after changing channels from the app
+privateer channels status     # which platforms are live right now
+privateer channels run        # or in the foreground
+```
+
+**On a VPS:** run both as a dedicated, unprivileged user, never root. A routine you allow
+`bash` runs with that user's full rights. Sign in over SSH with `privateer` and `/login` (it
+prints a code to approve in the app). Nothing needs an inbound port, except WhatsApp's
+webhook. The Linux unit sets `NoNewPrivileges`, `UMask=0077` and a restart limit. It skips
+systemd's namespace sandboxing on purpose, because that fails to start on kernels without
+unprivileged user namespaces. In a container with no systemd, use `privateer harbor run`
+under the container's own restart policy.
 
 ## Workflows
 
@@ -545,6 +569,8 @@ setup, config, and limitations: [`docs/acp.md`](docs/acp.md).
 Driving Privateer from **your own program or agent**? ACP is how that program gets asked:
 every approval arrives as a `session/request_permission` call it answers. The wire format,
 option ids and a minimal client are in [`docs/acp.md`](docs/acp.md#driving-privateer-from-another-agent).
+Handing it data your program shouldn't see? Set `"private": true` in the `acp` block; see
+[Hand off sensitive work](#hand-off-sensitive-work-to-privateer).
 
 ### One-shot runs (`-p`) and spending
 
@@ -566,6 +592,36 @@ call. `media_capabilities` shows the same prices. A call that can't be priced is
 under a dollar cap rather than let through. `--approve-in-app` reaches the app while it's
 open or running in the background.
 
+## Hand off sensitive work to Privateer
+
+Your coding agent's context goes to its provider. When a task touches files that
+shouldn't (patient records, a customer export, payroll, a database dump), the agent can
+hand that part to Privateer instead of reading the files itself:
+
+```bash
+privateer -p --private --model privateer/tinfoil/gemma4-31b \
+  "Read customers/export.csv. Reply with the number of customers per country. No row-level data."
+```
+
+The calling agent passes file *names*. Privateer reads the files on this machine, reasons
+over them on a verified-private model, and prints only the answer. `--private` is what
+makes that a guarantee rather than a hope:
+
+- **No file reaches an unverified model.** Before every tool call the model must be
+  `tee-verified` (an enclave quote Privateer checked itself) or `local`. A ZDR route, a
+  standard provider, or a failed attestation refuses the tool.
+- **Nothing leaves through a tool.** Only on-machine tools run. Web, MCP, media, uploads
+  and network shell commands (`curl`, `ssh`, `git push`, …) are refused.
+- **Nothing lifts it.** It sits above permission modes and approvals, `--no-quarter`
+  included, and subagents inherit it.
+- **The caller sees only the answer.** `-p` prints the reply. `--private --mode json`,
+  which would stream the file contents, is refused.
+
+The reply itself is the one channel left, so ask for aggregates, yes/no answers, or a
+summary, and have Privateer write detail to a file. Setup for Claude Code and other agents,
+the ACP route for your own programs, prompt patterns, and the honest limits are in
+[`docs/private-handoff.md`](docs/private-handoff.md).
+
 ## Connectors — MCP
 
 Privateer is an **MCP client**. Point it at a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -737,7 +793,10 @@ agent is stuck),
 `privateer acp` (serve the agent to an ACP host like Buzz or Zed — see
 [`docs/acp.md`](docs/acp.md)), `privateer auth status` (is this machine signed in?),
 `privateer -p … [--allow-spend …] [--approve-in-app]` (see
-[one-shot runs](#one-shot-runs--p-and-spending)), `privateer --no-quarter`, `privateer --version`.
+[one-shot runs](#one-shot-runs--p-and-spending)), `privateer --private` (tools run only on a
+verified-private model and never reach the network; see
+[Hand off sensitive work](#hand-off-sensitive-work-to-privateer)), `privateer --no-quarter`,
+`privateer --version`.
 An unknown subcommand of `auth` is an error. It is never sent to the model as a prompt.
 
 ## Develop

package/bin/headless-flags.d.mts

@@ -6,6 +6,7 @@ export const BILLED_TOOLS: string[];
 export const CLI_SPEND_ENV: string;
 export const APPROVE_IN_APP_ENV: string;
 export const PI_SUBCOMMANDS: string[];
+export const PRIVATE_ENV: string;
 
 export interface CliSpendGrant {
   tools: string[];
@@ -22,4 +23,10 @@ export function extractHeadlessFlags(args: string[]): {
   error?: string;
 };
 
+/** Strips `--private` out of `args` in place; true when it was there. */
+export function extractPrivateFlag(args: string[]): boolean;
+
+/** Why these args can't run under --private, or null. */
+export function privateProblem(args: string[]): string | null;
+
 export function authProblem(args: string[], cmd?: string): string | null;

package/bin/headless-flags.mjs

@@ -137,6 +137,46 @@ export function extractHeadlessFlags(args) {
   };
 }
 
+/** The env var carrying `--private` (permissions/privateMode.ts) into every gate. */
+export const PRIVATE_ENV = "PRIVATEER_PRIVATE";
+
+/**
+ * Strip `--private` from `args` (in place). Returns true when it was there.
+ *
+ * Valid for any launch — the TUI, `-p`, `acp` — because it only ever makes a run
+ * stricter: tools run only while the model is verified-private, and only tools that
+ * stay on this machine. Unlike the spend env vars, an exported PRIVATEER_PRIVATE is
+ * honoured too, for the same reason.
+ */
+export function extractPrivateFlag(args) {
+  let found = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--") break;
+    if (args[i] === "--private") {
+      args.splice(i, 1);
+      i--;
+      found = true;
+    }
+  }
+  return found;
+}
+
+/**
+ * Why these args can't run in private mode, or null. `--mode json` streams every event
+ * to stdout, tool results included — the contents of every file the run read, handed to
+ * the very caller private mode exists to keep them from. `-p` prints only the answer.
+ */
+export function privateProblem(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break;
+    if ((a === "--mode" && args[i + 1] === "json") || a === "--mode=json") {
+      return "--private can't be combined with --mode json: JSON mode streams every tool result (the files this run reads) to stdout. Use -p, which prints only the answer, or `privateer acp`.";
+    }
+  }
+  return null;
+}
+
 // Pi's own subcommands. Pi recognizes each only as args[0], so the launcher must hand
 // them over with NOTHING in front — the normal launch prepends --model, -e and --skill,
 // which is exactly how `privateer auth check` used to become a chat message.

package/bin/model-args.d.mts

@@ -0,0 +1,9 @@
+// Types for bin/model-args.mjs — plain .mjs because bin/ runs under a bare `node`.
+
+export function modelArgs(o: {
+  launchArgs: string[];
+  envModel?: string;
+  savedDefault?: string | null;
+  signedIn: boolean;
+  computed: string;
+}): string[];

package/bin/model-args.mjs

@@ -0,0 +1,43 @@
+// Which `--model` the launcher hands Pi, if any.
+//
+// Plain .mjs for the same reason as headless-flags.mjs: bin/ runs under a bare `node`,
+// and the launcher runs on import, so the rule lives where a test can reach it.
+// See tests/modelArgs.test.ts.
+//
+// Precedence:
+//   1. a --model the user typed (already in the args) → add nothing
+//   2. PRIVATEER_MODEL → the computed model
+//   3. a saved pick in settings.json → usually add nothing and let Pi resolve it, which
+//      falls back sanely when a BYO model has vanished from the registry. EXCEPT a
+//      `privateer/*` pick on a signed-in machine, which is passed explicitly (below).
+//   4. nothing saved → the computed model
+//
+// Why the exception. Pi resolves a saved default only when that provider HAS AUTH at
+// the moment the session starts (model-resolver.js findInitialModel, step 3), and if not
+// it silently takes the first model that does: with an OPENROUTER_API_KEY around, that
+// is Pi's openrouter default, moonshotai/kimi-k2.6. The account provider's auth is the
+// one `privateer` entry in auth.json, which is machine-global and removed whenever ANY
+// Privateer process exits (it revokes its own account session on the way out). So a
+// launch that happened to follow another process's exit came up on OpenRouter with no
+// message at all, while settings.json still said privateer/near/…. A `-p` run then sent
+// its work to a ZDR provider instead of the enclave the user picked; under --private it
+// refused every tool and said the model was "zdr-policy", which is how this was found.
+//
+// An explicit --model resolves against every REGISTERED model, auth or not
+// (resolveCliModel → getModels()), and the account credential is armed at
+// session_start, before the first prompt. Being signed in is the condition because
+// that is when arming will succeed; signed out, the saved pick couldn't run anyway and
+// Pi's own resolution is no worse.
+
+/**
+ * @param {{ launchArgs: string[], envModel?: string, savedDefault?: string | null, signedIn: boolean, computed: string }} o
+ * @returns {string[]} args to prepend: [] or ["--model", spec]
+ */
+export function modelArgs({ launchArgs, envModel, savedDefault, signedIn, computed }) {
+  if (launchArgs.includes("--model")) return [];
+  if (envModel) return ["--model", computed];
+  if (savedDefault) {
+    return signedIn && savedDefault.startsWith("privateer/") ? ["--model", savedDefault] : [];
+  }
+  return ["--model", computed];
+}

package/bin/privateer-channels.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Launcher for the channels runner (Telegram/Slack/Discord/WhatsApp → agent turns).
+// Mirrors bin/privateer-harbor.mjs: load dev keys from the repo .env WITHOUT changing
+// cwd, register tsx so TS resolves regardless of the invocation cwd, then hand off to
+// the channels CLI dispatcher (whose `run` imports ./boot.ts before any Pi code).
+//
+// Invoked two ways: interactively via the launcher (`privateer channels …`), and by the
+// installed launchd/systemd service (`node privateer-channels.mjs run`). This is what
+// makes channels runnable from an npm install; it used to need a source checkout
+// (`npm run channels`, tsx and a .env).
+import { register } from "tsx/esm/api";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "..");
+
+try {
+  process.loadEnvFile(resolve(repo, ".env"));
+} catch {
+  /* no .env — rely on the ambient environment / ~/.privateer */
+}
+
+// Same reason as the harbor: channel sessions load the moat in code, so subagent
+// children need the moat-injecting wrapper rather than a bare `pi`.
+process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
+
+register();
+const { runChannelsCli } = await import(pathToFileURL(resolve(repo, "src/cli/channelsCli.ts")).href);
+await runChannelsCli(process.argv.slice(2));

package/bin/privateer-launch.mjs

@@ -29,8 +29,9 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 import { routeUpdate } from "./update-route.mjs";
-import { APPROVE_IN_APP_ENV, CLI_SPEND_ENV, PI_SUBCOMMANDS, authProblem, extractHeadlessFlags } from "./headless-flags.mjs";
+import { APPROVE_IN_APP_ENV, CLI_SPEND_ENV, PI_SUBCOMMANDS, PRIVATE_ENV, authProblem, extractHeadlessFlags, extractPrivateFlag, privateProblem } from "./headless-flags.mjs";
 import { runToCompletion } from "./run-to-completion.mjs";
+import { modelArgs } from "./model-args.mjs";
 import { filterRespawnArgs, listTerminals, requestFresh, runSupervised } from "./fresh-supervisor.mjs";
 import { configureCompileCache } from "./startup-cache.mjs";
 
@@ -248,6 +249,16 @@ delete process.env[APPROVE_IN_APP_ENV];
   if (headless.spend) process.env[CLI_SPEND_ENV] = JSON.stringify(headless.spend);
   if (headless.approveInAppMs) process.env[APPROVE_IN_APP_ENV] = String(headless.approveInAppMs);
 }
+// --private: NOT cleared from the inherited env first, unlike the two above — it can only
+// tighten a run, so an orchestrator exporting it for every child is the point.
+if (extractPrivateFlag(args)) process.env[PRIVATE_ENV] = "1";
+if (/^(1|true|yes)$/i.test((process.env[PRIVATE_ENV] ?? "").trim())) {
+  const problem = privateProblem(args);
+  if (problem) {
+    process.stderr.write(`privateer: ${problem}\n`);
+    process.exit(2);
+  }
+}
 
 const sub = args[0];
 
@@ -545,6 +556,16 @@ else if (sub === "harbor" || sub === "daemon") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
+// --- `privateer channels [run|install|uninstall|status]` -------------------
+// The chat-platform bridges (Telegram/Slack/Discord/WhatsApp). Same shape as the
+// harbor: a resident process, its own launcher, its own optional login service.
+else if (sub === "channels") {
+  sweepLegacyShims();
+  sweepBashLogs();
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-channels.mjs"), ...args.slice(1)], { forwardSignals: true });
+}
+
 // --- `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
@@ -807,14 +828,15 @@ else {
   //   1. a --model the user typed on the privateer command line (already in `args`)
   //   2. PRIVATEER_MODEL — deliberate override, folded into MODEL above
   //   3. a saved pick in settings.json → pass NO flag; Pi resolves it itself (and
-  //      falls back sanely if that model has vanished from the registry)
+  //      falls back sanely if that model has vanished from the registry). Except a
+  //      signed-in `privateer/*` pick, passed explicitly — see bin/model-args.mjs for
+  //      the silent OpenRouter fallback that prevents
   //   4. nothing saved (first run / fresh home) → the computed MODEL above
   //
   // A FUNCTION, called per launch: a fresh agent (bin/fresh-supervisor.mjs) re-reads it,
   // so a model picked in the old session boots the new one instead of being stomped by
   // a first-run --model computed before that pick existed.
   const modelArgsFor = (launchArgs) => {
-    const userPassedModel = launchArgs.includes("--model");
     let savedDefault = null;
     try {
       const s = JSON.parse(fs.readFileSync(path.join(AGENT_DIR, "settings.json"), "utf8"));
@@ -825,7 +847,7 @@ else {
         savedDefault = `${s.defaultProvider}/${s.defaultModel}`;
       }
     } catch { /* absent/unreadable → no saved pick */ }
-    return userPassedModel || (savedDefault && !process.env.PRIVATEER_MODEL) ? [] : ["--model", MODEL];
+    return modelArgs({ launchArgs, envModel: process.env.PRIVATEER_MODEL, savedDefault, signedIn, computed: MODEL });
   };
 
   // Dev convenience: load provider keys from the repo's .env if present.
@@ -856,7 +878,9 @@ else {
   // command, or `privateer fresh` from another terminal can swap this agent for a new
   // process with the old tree reaped. Print/export/version runs have nothing to swap.
   const tuiArgs = (launchArgs) => [...nodeArgs, CLI, ...modelArgsFor(launchArgs), ...extArgs, ...skillArgs, ...launchArgs];
-  if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args));
+  // forwardSignals: a `kill` reaches only this launcher, and a -p run left behind keeps
+  // working (and spending) with nobody waiting for its answer.
+  if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args), { forwardSignals: true });
   else runSupervised(NODE_BIN, (first) => tuiArgs(first ? args : filterRespawnArgs(args)), { home: PRIVATEER_HOME });
 }
 
@@ -1037,7 +1061,8 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       "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} harbor <command>     Manage Harbor, the always-on agent behind the app (run/install/uninstall/status)`,
+      `  ${cmd} channels <command>   Run chat channels: Telegram, Slack, Discord, WhatsApp (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} fresh [n]            Replace a running terminal's agent with a new one (stops everything it started)`,

package/extensions/privateer-brand.ts

@@ -281,17 +281,21 @@ function contextLine(p: Palette): string {
 }
 
 // ── "What's New" — a tiny in-banner changelog ────────────────────────────────
-// A hand-curated highlights list (newest first). Not the full changelog — just the two
-// or three things a returning user should notice. `cmd`, when present, is rendered in the
-// accent color so the actionable bit stands out from the prose. Trim this as it ages.
-const WHATS_NEW: Array<{ text: string; cmd?: string }> = [
-  { text: "Open and switch named terminals —", cmd: "/term" },
-  { text: "Voice follows the window you're in" },
-  { text: "Searchable model picker —", cmd: "/models" },
-  { text: "Start over with a new agent —", cmd: "/fresh" },
-];
+// A hand-curated highlights list (newest first), kept in src/config/whatsNew.json so the
+// release guard (scripts/check-whats-new.mjs) can read it without loading the TUI. Not the
+// full changelog — just the two to four things a returning user should notice. `cmd`, when
+// present, is rendered in the accent color so the actionable bit stands out from the prose.
+const WHATS_NEW: Array<{ text: string; cmd?: string }> = (() => {
+  try {
+    const list = JSON.parse(readFileSync(new URL("../src/config/whatsNew.json", import.meta.url), "utf8"));
+    return Array.isArray(list?.items) ? list.items : [];
+  } catch {
+    return []; // a banner without the list beats no banner
+  }
+})();
 
 function whatsNewRows(p: Palette): string[] {
+  if (!WHATS_NEW.length) return [];
   const head = `${p.BOLD}${p.INK}✦ What's new${p.RESET}`;
   const items = WHATS_NEW.map(
     ({ text, cmd }) =>
@@ -322,7 +326,8 @@ function renderBanner(width: number, p: Palette, mark: string[], modelProvider?:
   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));
+  const news = whatsNewRows(p);
+  if (news.length) text.push("", ...news);
 
   // Zip the mark and the text column by row. Rows past the mark's height get a blank
   // gutter of the mark's width, so the text stays in one column throughout.

package/extensions/privateer-gate.ts

@@ -40,6 +40,8 @@ import { updatePostureBadge } from "./privateer-posture.ts";
 import { childSpendAllows } from "../src/permissions/childSpend.ts";
 import { CliSpendLedger, headlessSpendGuidance, isSpendRequest, readCliSpendGrant } from "../src/permissions/cliSpend.ts";
 import { BILLED_MEDIA_TOOLS } from "../src/permissions/classify.ts";
+import { privateModeFromEnv } from "../src/permissions/privateMode.ts";
+import { REPLY_TIMEOUT_ENV, StallWatchdog, replyTimeoutMs } from "../src/engine/stallWatchdog.ts";
 import type { PermissionRequest } from "../src/permissions/gate.ts";
 import { HeadlessAppApprover } from "../src/remote/headlessApproval.ts";
 import { describeErrorText } from "../src/engine/errors.ts";
@@ -694,7 +696,9 @@ export default function privateerControl(pi: any): void {
   // prompt, before it plans). Quiet when nothing billable is enabled, or when no quarter
   // lifts the gate anyway.
   function uncoveredBilledTools(): string[] {
-    if (noQuarterActive()) return [];
+    // Private mode refuses every billed tool outright (they send text off the machine),
+    // so "add --allow-spend" would be advice that cannot work.
+    if (noQuarterActive() || privateModeFromEnv()) return [];
     const active: string[] = (() => {
       try {
         return pi.getActiveTools?.() ?? [];
@@ -750,11 +754,63 @@ export default function privateerControl(pi: any): void {
   });
   pi.on("session_shutdown", () => appApprover?.close());
 
+  // Private mode (src/permissions/privateMode.ts), told to the model before it plans:
+  // otherwise it reaches for web_search, gets refused, and narrates the refusal instead
+  // of doing the local work. And the reply is the one channel the gate can't close, so
+  // the model is asked to keep raw records out of it — a request, not a control.
+  pi.on("before_agent_start", (event: any) => {
+    if (!privateModeFromEnv()) return;
+    return {
+      systemPrompt:
+        `${event.systemPrompt}\n\n# Private mode\n` +
+        "This run handles data that must not leave this machine except through a verified-private model. " +
+        "Only local tools work: read, grep, find, ls, write, edit, and shell commands that don't use the network. " +
+        "Web, MCP, media and upload tools, and network commands, are refused. Every tool is refused if the model " +
+        "can't be verified as private; if that happens, stop and say so.\n" +
+        "Your reply leaves private mode: whoever asked will see it. Answer exactly what was asked. Don't quote raw " +
+        "records, names, emails, identifiers or other personal data from the files unless the task explicitly asks " +
+        "for them. When asked for detail, write it to a file and reply with the path.",
+    };
+  });
+
+  // A headless run must not wait forever on a provider that went silent (see
+  // src/engine/stallWatchdog.ts). Armed per request, re-armed by every streamed event,
+  // off between requests. On a stall: say so on stderr, abort the turn, exit non-zero.
+  let stallCtx: any;
+  const stallMs = replyTimeoutMs();
+  const watchdog = new StallWatchdog(stallMs, () => {
+    const secs = Math.round(stallMs / 1000);
+    process.stderr.write(
+      `privateer: no reply from ${currentSpec || "the model"} for ${secs}s — stopped. The provider accepted the ` +
+        `request and then sent nothing.\n  Re-run, or pick another model with --model. ` +
+        `${REPLY_TIMEOUT_ENV}=<seconds> changes the limit (0 turns it off).\n`,
+    );
+    process.exitCode = 1;
+    try {
+      stallCtx?.abort?.();
+    } catch {
+      /* the turn is already ending */
+    }
+  });
+  pi.on("before_provider_request", (_e: any, ctx: any) => {
+    if (!headlessRun) return;
+    stallCtx = ctx;
+    watchdog.arm();
+  });
+  pi.on("message_start", (ev: any) => {
+    if (headlessRun && ev?.message?.role === "assistant") watchdog.arm();
+  });
+  pi.on("message_update", () => {
+    if (headlessRun) watchdog.arm();
+  });
+  pi.on("message_end", () => watchdog.disarm());
+
   // Print mode prints a failed turn's raw SDK text — "401 status code (no body)",
   // "Connection error." — and exits. Follow it with what that means and what to do,
   // on stderr so stdout stays the answer (or the JSON stream).
   pi.on("agent_end", (ev: any) => {
-    if (!headlessRun) return;
+    watchdog.disarm();
+    if (!headlessRun || watchdog.stalled) return; // a stall already said what happened
     const msgs: any[] = Array.isArray(ev?.messages) ? ev.messages : [];
     const last = [...msgs].reverse().find((m) => m?.role === "assistant");
     if (last?.stopReason !== "error" || typeof last.errorMessage !== "string") return;

package/extensions/privateer-hints.ts

@@ -21,11 +21,12 @@
 // /hints on|off persists { hints: { enabled } } in ~/.privateer/config.json (ours;
 // Pi never reads that file) — read-modify-write, preserving unrelated keys.
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { keyText } from "@earendil-works/pi-coding-agent";
 import { configPath, globalDir } from "../src/config/paths.ts";
 import { desktopAppPath } from "../src/config/desktopApp.ts";
+import { writeFileAtomic } from "../src/util/atomicWrite.ts";
 
 const FIRST_MS = 6_000; // a turn shorter than this never shows a tip
 const EVERY_MS = 12_000;
@@ -120,7 +121,7 @@ function persistEnabled(enabled: boolean): void {
   cfg.hints = { ...(cfg.hints ?? {}), enabled };
   try {
     mkdirSync(globalDir(), { recursive: true });
-    writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n");
+    writeFileAtomic(configPath(), JSON.stringify(cfg, null, 2) + "\n");
   } catch {
     /* best effort — the toggle still holds for this session */
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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",
@@ -64,6 +64,7 @@
     "dev": "node bin/privateer-launch.mjs",
     "dev:fresh": "PRIVATEER_HOME=\"$PWD/.dev-home\" node bin/privateer-launch.mjs",
     "typecheck": "tsc --noEmit",
+    "check:whats-new": "node scripts/check-whats-new.mjs",
     "test": "for f in tests/*.test.ts; do node --import tsx --test \"$f\" || exit 1; done"
   },
   "engines": {

package/src/acp/run.ts

@@ -21,7 +21,8 @@
 //       "model":   "openrouter/openai/gpt-4o-mini",   // optional
 //       "tools":   ["read","grep","find","ls"],        // optional ceiling
 //       "posture": "approve",                          // readonly | approve | auto
-//       "cwd":     "/path/to/project"        // optional; else this process's cwd
+//       "cwd":     "/path/to/project",       // optional; else this process's cwd
+//       "private": true                         // optional; see permissions/privateMode.ts
 //     }
 //   }
 //
@@ -115,6 +116,10 @@ export async function runAcp(): Promise<void> {
     : (web ? [...SAFE_TOOLS, ...WEB_TOOLS] : [...SAFE_TOOLS]);
   const posture: Posture = normalizePosture(block.posture) ?? "approve";
   const baseCwd: string = block.cwd ?? process.cwd();
+  // Private mode: `acp.private`, or `privateer acp --private` / PRIVATEER_PRIVATE (read by
+  // the gate itself). The handoff surface for an agent that must not see the data.
+  const { privateModeFromEnv, modelTier, PRIVATE_TIERS } = await import("../permissions/privateMode.ts");
+  const privateMode: boolean = block.private === true || privateModeFromEnv();
 
   // The gate. Identical posture semantics to the channels runtime: "readonly" maps to
   // plan mode (hard-deny writes), "auto" relaxes non-dangerous actions, and every ask
@@ -129,6 +134,7 @@ export async function runAcp(): Promise<void> {
     confineToCwd: true,
     getRemote: () => true,
     getAutoApprove: () => posture === "auto",
+    getPrivate: () => privateMode,
     async localAsk() {
       return "deny";
     },
@@ -272,8 +278,22 @@ export async function runAcp(): Promise<void> {
   const modelCount = listModels()?.available.length ?? 0;
   log(
     `ready — model ${defaultModel}, ${modelCount} selectable, ` +
-      `ceiling [${tools.join(", ")}], posture ${posture}`,
+      `ceiling [${tools.join(", ")}], posture ${posture}${privateMode ? ", PRIVATE" : ""}`,
   );
+  // Say up front when private mode will refuse every tool, rather than letting the
+  // caller find out from its first denial. The gate re-checks per call regardless.
+  if (privateMode) {
+    try {
+      const tier = await modelTier({ provider: model.provider, id: model.id, baseUrl: model.baseUrl });
+      log(
+        PRIVATE_TIERS.has(tier)
+          ? `private mode: ${defaultModel} is ${tier}`
+          : `private mode: ${defaultModel} is ${tier}, NOT verified-private — every tool will be refused. Pick a TEE or local model.`,
+      );
+    } catch (e) {
+      log(`private mode: could not verify ${defaultModel} (${e instanceof Error ? e.message : String(e)}) — tools will be refused until it verifies`);
+    }
+  }
 
   // One Pi session per ACP session. A single subscription routes streamed text into a
   // mutable holder, which the running turn owns — safe because a session runs at most
@@ -353,7 +373,12 @@ export async function runAcp(): Promise<void> {
           // its own `hasConfiguredAuth` precheck before it emits `before_agent_start`,
           // where providers/account.ts installs the equivalent net.
           await ensureAccountArmed(currentProvider);
-          await session.prompt(text);
+          // Prompt text is the HOST's, so it is never a command: with expansion on, Pi
+          // runs a leading `/name` as an extension command, and anyone who can post to
+          // the host (a Buzz channel, a calling agent) could send `/privacy off` or
+          // `/privacy allow *` — the second persisted to config.json. Text goes to the
+          // model as text.
+          await session.prompt(text, { expandPromptTemplates: false });
         } catch (e) {
           return { ok: false, error: e instanceof Error ? e.message : String(e) };
         } finally {
@@ -371,7 +396,7 @@ export async function runAcp(): Promise<void> {
 
   let agent: InstanceType<typeof PrivateerAcpAgent> | undefined;
   new AgentSideConnection((conn) => {
-    agent = new PrivateerAcpAgent(conn, { createSession, models: listModels, onLog: log });
+    agent = new PrivateerAcpAgent(conn, { createSession, models: listModels, onLog: log, private: privateMode });
     return agent;
   }, stream);