privateer-agent 0.12.47 → 0.12.49

package/README.md

@@ -507,6 +507,30 @@ Honest caveat for Buzz: **Buzz currently auto-approves permission prompts**, so
 the tool ceiling *is* the control — which is exactly why the default is read-only. Full
 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).
+
+### One-shot runs (`-p`) and spending
+
+A `privateer -p "…"` run has no screen, so anything that needs approval is **denied**. That
+includes every billed media tool, and the run says so when it starts. Two flags change it,
+and both apply to that one invocation only. Nothing is saved, and an exported environment
+variable can't turn either on.
+
+```bash
+# pre-approve named billed tools, capped by calls and/or estimated dollars
+privateer -p --allow-spend generate_video --max-calls 1 --max-spend 1.00 "make a 6s intro clip"
+
+# or ask on your phone: approvals go to the Privateer app, denied if unanswered in time
+privateer -p --approve-in-app --approval-timeout 300 "make a 6s intro clip"
+```
+
+`--max-spend` is checked before each call against the server's own estimate for that exact
+call. `media_capabilities` shows the same prices. A call that can't be priced is refused
+under a dollar cap rather than let through. `--approve-in-app` reaches the app while it's
+open or running in the background.
+
 ## Connectors — MCP
 
 Privateer is an **MCP client**. Point it at a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -672,7 +696,10 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 
 Shell subcommands: `privateer` (interactive), `privateer update`, `privateer harbor …`,
 `privateer acp` (serve the agent to an ACP host like Buzz or Zed — see
-[`docs/acp.md`](docs/acp.md)), `privateer --no-quarter`, `privateer --version`.
+[`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`.
+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

@@ -0,0 +1,25 @@
+// Types for bin/headless-flags.mjs. Same reason as update-route.d.mts: the
+// implementation is plain .mjs because bin/ runs under a bare `node`, but the tests
+// that pin the grammar are TypeScript.
+
+export const BILLED_TOOLS: string[];
+export const CLI_SPEND_ENV: string;
+export const APPROVE_IN_APP_ENV: string;
+export const PI_SUBCOMMANDS: string[];
+
+export interface CliSpendGrant {
+  tools: string[];
+  maxCalls?: number;
+  maxSpendUsd?: number;
+}
+
+export function isHeadlessRun(args: string[]): boolean;
+
+/** Strips the headless flags out of `args` in place. */
+export function extractHeadlessFlags(args: string[]): {
+  spend?: CliSpendGrant;
+  approveInAppMs?: number;
+  error?: string;
+};
+
+export function authProblem(args: string[], cmd?: string): string | null;

package/bin/headless-flags.mjs

@@ -0,0 +1,166 @@
+// The launcher's argv rules for HEADLESS runs and for Pi's own subcommands.
+//
+// Plain .mjs, like update-route.mjs, because bin/ runs under a bare `node` before any
+// transpiler exists — and separate from the launcher because the launcher runs on
+// import, so nothing inside it can be tested. See tests/headlessFlags.test.ts.
+
+/** Every tool that bills the account — mirrors BILLED_MEDIA_TOOLS in src/permissions/classify.ts. */
+export const BILLED_TOOLS = [
+  "generate_image",
+  "generate_video",
+  "generate_model",
+  "generate_sprite",
+  "generate_speech",
+  "generate_music",
+  "generate_sfx",
+];
+
+/** The env var carrying a `--allow-spend` grant from the launcher to the gate. */
+export const CLI_SPEND_ENV = "PRIVATEER_CLI_SPEND";
+/** The env var carrying `--approve-in-app` (its value is the timeout in ms). */
+export const APPROVE_IN_APP_ENV = "PRIVATEER_APPROVE_IN_APP";
+
+const DEFAULT_APPROVAL_TIMEOUT_SEC = 300;
+
+/** True when these args ask Pi for a one-shot, no-screen run. */
+export function isHeadlessRun(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break;
+    if (a === "-p" || a === "--print") return true;
+    if (a === "--mode" && args[i + 1] === "json") return true;
+    if (a === "--mode=json") return true;
+  }
+  return false;
+}
+
+function toolName(raw) {
+  const t = raw.trim();
+  if (!t) return null;
+  // `video` is accepted for `generate_video`: it is what a person types, and it is
+  // unambiguous. Anything else must be one of the billed tools, spelled out.
+  const full = t.startsWith("generate_") ? t : `generate_${t}`;
+  return BILLED_TOOLS.includes(full) ? full : null;
+}
+
+/**
+ * Pull the headless-run flags out of `args` (in place) and validate them together.
+ *
+ *   --allow-spend <tool[,tool…]>   pre-approve these billed tools for THIS run
+ *   --max-calls <n>                …at most n billed calls in total
+ *   --max-spend <usd>              …at most this much, estimated before each call
+ *   --approve-in-app               send approvals this run can't answer to the app
+ *   --approval-timeout <seconds>   how long to wait for the app (default 300)
+ *
+ * Returns `{ spend, approveInAppMs, error }`. `error` is a message for the user and
+ * means nothing else should be trusted. A spend grant must be capped (calls, dollars
+ * or both) and only exists for `-p` / `--mode json` runs — in the TUI a person
+ * approves each call, so there is nothing to pre-approve.
+ */
+export function extractHeadlessFlags(args) {
+  const tools = [];
+  let maxCalls;
+  let maxSpendUsd;
+  let approveInApp = false;
+  let timeoutSec;
+  let spendFlagSeen = false;
+
+  const take = (i, name) => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith("--")) return { error: `${name} needs a value` };
+    return { value: v };
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") break;
+    const [flag, inline] = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, undefined];
+    if (!["--allow-spend", "--max-calls", "--max-spend", "--approve-in-app", "--approval-timeout"].includes(flag)) continue;
+
+    let value = inline;
+    let consumed = 1;
+    if (flag !== "--approve-in-app" && value === undefined) {
+      const t = take(i, flag);
+      if (t.error) return { error: t.error };
+      value = t.value;
+      consumed = 2;
+    }
+    args.splice(i, consumed);
+    i--;
+
+    if (flag === "--allow-spend") {
+      spendFlagSeen = true;
+      for (const raw of value.split(",")) {
+        const name = toolName(raw);
+        if (!name) {
+          return { error: `--allow-spend: "${raw.trim()}" is not a billed tool. Use one of: ${BILLED_TOOLS.join(", ")}` };
+        }
+        if (!tools.includes(name)) tools.push(name);
+      }
+    } else if (flag === "--max-calls") {
+      spendFlagSeen = true;
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1) return { error: `--max-calls must be a whole number of calls, 1 or more (got "${value}")` };
+      maxCalls = n;
+    } else if (flag === "--max-spend") {
+      spendFlagSeen = true;
+      const n = Number(String(value).replace(/^\$/, ""));
+      if (!Number.isFinite(n) || n <= 0) return { error: `--max-spend must be a dollar amount above 0, e.g. 1.00 (got "${value}")` };
+      maxSpendUsd = n;
+    } else if (flag === "--approve-in-app") {
+      approveInApp = true;
+    } else if (flag === "--approval-timeout") {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n < 10 || n > 3600) return { error: `--approval-timeout must be 10-3600 seconds (got "${value}")` };
+      timeoutSec = n;
+    }
+  }
+
+  const headless = isHeadlessRun(args);
+  if (spendFlagSeen) {
+    if (tools.length === 0) return { error: "--max-calls / --max-spend cap a spend grant — name the tools with --allow-spend <tool>" };
+    if (maxCalls === undefined && maxSpendUsd === undefined) {
+      return { error: "--allow-spend needs a cap: add --max-calls <n>, --max-spend <usd>, or both" };
+    }
+    if (!headless) {
+      return { error: "--allow-spend only applies to a headless run (-p / --print, or --mode json). In the terminal UI you approve each call yourself." };
+    }
+  }
+  if (timeoutSec !== undefined && !approveInApp) return { error: "--approval-timeout only applies with --approve-in-app" };
+  if (approveInApp && !headless) {
+    return { error: "--approve-in-app only applies to a headless run (-p / --print, or --mode json). An interactive terminal can use /remote-access." };
+  }
+
+  return {
+    spend: tools.length ? { tools, ...(maxCalls !== undefined ? { maxCalls } : {}), ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}) } : undefined,
+    approveInAppMs: approveInApp ? Math.round((timeoutSec ?? DEFAULT_APPROVAL_TIMEOUT_SEC) * 1000) : undefined,
+  };
+}
+
+// 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.
+export const PI_SUBCOMMANDS = ["auth", "install", "remove", "uninstall", "list", "config"];
+
+const AUTH_SUBCOMMANDS = ["check", "print-api-key", "print-bearer-token"];
+
+/**
+ * Is `args` an `auth` invocation Pi won't understand? Returns the message to print, or
+ * null. `status` is ours (answered by the launcher), `help`/--help are Pi's.
+ */
+export function authProblem(args, cmd = "privateer") {
+  if (args[0] !== "auth") return null;
+  const sub = args[1];
+  if (sub === undefined || sub === "help" || sub === "status" || args.includes("--help") || args.includes("-h")) return null;
+  if (AUTH_SUBCOMMANDS.includes(sub)) return null;
+  return [
+    `${cmd} auth: unknown command "${sub}".`,
+    "",
+    `  ${cmd} auth status                               is this machine signed in to Privateer?`,
+    `  ${cmd} auth check --provider <name>              are a provider's credentials ready?`,
+    `  ${cmd} auth print-api-key --provider <name>      print a provider's API key`,
+    `  ${cmd} auth print-bearer-token --provider <name> print a provider's bearer token`,
+    "",
+    `Nothing was sent to a model. To sign in, run \`${cmd}\` and type /login.`,
+  ].join("\n");
+}

package/bin/privateer-launch.mjs

@@ -29,6 +29,7 @@ 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 { runToCompletion } from "./run-to-completion.mjs";
 import { configureCompileCache } from "./startup-cache.mjs";
 
@@ -158,11 +159,19 @@ const NO_QUARTER = args.some((a) => a === "--no-quarter");
 if (NO_QUARTER) {
   for (let i = args.length - 1; i >= 0; i--) if (args[i] === "--no-quarter") args.splice(i, 1);
   process.env.PRIVATEER_NO_QUARTER = "1";
+  // No quarter is also `/privacy off` (src/permissions/noQuarter.ts). Marked, unless the
+  // filter was already off, so shift+tab back to the moat restores it.
+  if (process.env.PRIVATEER_PRIVACY_OFF !== "1" && process.env.PI_PRIVACY_OFF !== "1") {
+    process.env.PRIVATEER_PRIVACY_OFF = "1";
+    process.env.PI_PRIVACY_OFF = "1";
+    process.env.PRIVATEER_PRIVACY_OFF_BY_NO_QUARTER = "1";
+  }
   process.stderr.write(
     [
       "",
-      "  ⚓ \x1b[1;31mNo quarter\x1b[0m — permission gate DISABLED for this session.",
-      "     Every action (shell, edits, destructive tools, out-of-cwd) runs WITHOUT a prompt.",
+      "  ⚓ \x1b[1;31mNo quarter\x1b[0m — permission gate AND privacy filter DISABLED for this session.",
+      "     Every action (shell, edits, destructive tools, out-of-cwd) runs WITHOUT a prompt,",
+      "     and outbound requests are not scanned for PII.",
       "     Only use this in a directory and with a task you fully trust.",
       "     shift+tab (or /no-quarter off) raises the moat again.",
       "",
@@ -178,6 +187,7 @@ if (NO_PRIVACY) {
   for (let i = args.length - 1; i >= 0; i--) if (args[i] === "--no-privacy" || args[i] === "--privacy-off") args.splice(i, 1);
   process.env.PRIVATEER_PRIVACY_OFF = "1";
   process.env.PI_PRIVACY_OFF = "1";
+  delete process.env.PRIVATEER_PRIVACY_OFF_BY_NO_QUARTER; // asked for outright — raising the moat keeps it off
   process.stderr.write(
     [
       "",
@@ -219,6 +229,25 @@ if (ALLOW_COMPUTER) {
   );
 }
 
+// Headless-run flags — spend pre-approval and app approvals for `-p` runs. Stripped
+// before Pi sees them, exactly like the flags above; grammar in bin/headless-flags.mjs.
+//
+// THE ENV IS OURS, NEVER THE SHELL'S. The grant reaches the gate as an env var (the only
+// channel into Pi's process), so an inherited value is deleted FIRST: a
+// PRIVATEER_CLI_SPEND left exported in someone's shell must never pre-approve a run
+// they didn't type the flag for. Only this invocation's argv can set it.
+delete process.env[CLI_SPEND_ENV];
+delete process.env[APPROVE_IN_APP_ENV];
+{
+  const headless = extractHeadlessFlags(args);
+  if (headless.error) {
+    process.stderr.write(`privateer: ${headless.error}\n`);
+    process.exit(2);
+  }
+  if (headless.spend) process.env[CLI_SPEND_ENV] = JSON.stringify(headless.spend);
+  if (headless.approveInAppMs) process.env[APPROVE_IN_APP_ENV] = String(headless.approveInAppMs);
+}
+
 const sub = args[0];
 
 // `privateer --version` — report OUR version, not Pi's. Left to Pi's cli.js it would
@@ -541,6 +570,38 @@ else if (sub === "acp") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-acp.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
+// --- Pi's own subcommands: `auth`, and the package commands -------------------
+// Pi matches these only as args[0]. The normal launch below prepends --model, -e and
+// --skill, so every one of them used to fall through as a CHAT MESSAGE — `privateer
+// auth list` was answered by the model, which listed the project folders in the
+// user's home directory. Hand them over bare instead, and refuse an `auth` Pi doesn't
+// know rather than let it become a prompt.
+else if (PI_SUBCOMMANDS.includes(sub)) {
+  const cmd = process.env.PRIVATEER_CMD || "privateer";
+  const problem = authProblem(args, cmd);
+  if (problem) {
+    process.stderr.write(problem + "\n");
+    process.exit(2);
+  }
+  if (sub === "auth" && args[1] === "status") {
+    printAuthStatus(cmd);
+    process.exit(0);
+  }
+  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);
+  }
+  configureCompileCache(PRIVATEER_HOME); // same Pi module graph as a launch — reuse its compiled code
+  ensurePatches(); // project `.privateer/` config dirs are a patch; -l scope needs them
+  process.env.PI_CODING_AGENT_DIR = AGENT_DIR;
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  runToCompletion(NODE_BIN, [...nodeArgs, CLI, ...args]);
+}
+
 // --- 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
@@ -872,6 +933,28 @@ function warnKeylessLaunch() {
   process.stderr.write(lines.join("\n") + "\n");
 }
 
+// `privateer auth status` — the question people (and agents) actually ask, answered
+// from local state only: no network, nothing sent anywhere, and no secret printed.
+function printAuthStatus(cmd) {
+  let creds = null;
+  try {
+    creds = JSON.parse(fs.readFileSync(path.join(PRIVATEER_HOME, "credentials.json"), "utf8"));
+  } catch { /* absent or unreadable → signed out */ }
+  const lines = [];
+  if (creds && typeof creds.accessToken === "string") {
+    const who = creds.user?.email || "your account";
+    lines.push(`Privateer account: signed in as ${who}${creds.serverBaseUrl ? ` (${creds.serverBaseUrl})` : ""}`);
+    lines.push("  This checks the local login only; a session revoked from the app shows up on the next request.");
+  } else {
+    lines.push("Privateer account: not signed in");
+    lines.push(`  Run \`${cmd}\` and type /login, then approve the code in the Privateer app.`);
+  }
+  const keys = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY", "TINFOIL_API_KEY", "PRIVATEER_API_KEY"].filter(haveKey);
+  lines.push(`Provider keys in the environment: ${keys.length ? keys.join(", ") : "none"}`);
+  lines.push(`To check one provider end to end: ${cmd} auth check --provider <name>`);
+  console.log(lines.join("\n"));
+}
+
 function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
   console.log(
     [
@@ -891,7 +974,8 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       `  ${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} auth status          Show whether this machine is signed in`,
+      `  ${cmd} auth <command>       Check provider readiness or print credentials (check, print-api-key, print-bearer-token)`,
       `  ${cmd} <command> --help     Show help for a specific command`,
       "",
       "Options:",
@@ -902,6 +986,12 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       "  --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",
+      "  --allow-spend <tools>          -p only: pre-approve billed tools for this run (e.g. generate_video)",
+      "  --max-calls <n>                …at most n billed calls (a cap is required)",
+      "  --max-spend <usd>              …at most this much, estimated before each call",
+      "  --approve-in-app               -p only: send approvals to the Privateer app instead of denying",
+      "  --approval-timeout <seconds>   How long --approve-in-app waits (default 300)",
+      "  --no-quarter                   Run with NO approval prompts at all (trusted tasks only)",
       "  --continue, -c                 Continue previous session",
       "  --resume, -r                   Select a session to resume",
       "  --session <path|id>            Use specific session file or partial UUID",

package/extensions/privateer-gate.ts

@@ -35,7 +35,14 @@ import { matchesKey } from "@earendil-works/pi-tui";
 import * as priv from "../src/auth/privateer.ts";
 import { paletteFor } from "../src/ui/palette.ts";
 import { noQuarterActive, setNoQuarter } from "../src/permissions/noQuarter.ts";
+import { privacyDisabled } from "../src/config/privacyDisabled.ts";
+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 type { PermissionRequest } from "../src/permissions/gate.ts";
+import { HeadlessAppApprover } from "../src/remote/headlessApproval.ts";
+import { describeErrorText } from "../src/engine/errors.ts";
 import type { PermissionMode } from "../src/config/permissionMode.ts";
 
 const MODES: PermissionMode[] = ["default", "acceptEdits", "bypass", "plan"];
@@ -245,6 +252,10 @@ function advertiseCommands(): { name: string; description?: string }[] {
 // own connect/disconnect callbacks can refresh the indicator, not just the command.
 const REMOTE_STATUS_KEY = "privateer:remote-access";
 let uiRef: any = null;
+// The live model, for repainting the privacy badge when no quarter moves the filter —
+// privateer-posture's own watcher sits on ITS copy of privacyDisabled.ts (see
+// noQuarter.ts on per-extension module copies), so a flip from here never reaches it.
+let modelRef: { provider?: string; id?: string } | undefined;
 // "off" → no indicator; "connecting" → relay starting or reconnecting (yellow);
 // "connected" → socket open, controller reachable (green).
 let remoteState: "off" | "connecting" | "connected" = "off";
@@ -299,12 +310,17 @@ function refreshNoQuarterStatus(): void {
 // Flip the state and tell the user, loudly on the way down. Takes effect from the
 // next gated action — an approval already on screen still needs an answer.
 function applyNoQuarter(on: boolean, ui: any): void {
-  setNoQuarter(on);
+  const privacyWasOff = privacyDisabled();
+  setNoQuarter(on); // also `/privacy off` on the way down, and back on the way up if it did that
   refreshNoQuarterStatus();
+  const privacyMoved = privacyDisabled() !== privacyWasOff;
+  if (privacyMoved) void updatePostureBadge({ ui, model: modelRef });
   ui?.notify?.(
     on
-      ? "⚑ No quarter — the permission gate is OFF for this session. Every action (shell, edits, destructive tools, out-of-cwd, protected files) now runs without asking. shift+tab to raise the moat again."
-      : "⚓ Moat raised — the permission gate is back on.",
+      ? "⚑ No quarter — the permission gate is OFF for this session. Every action (shell, edits, destructive tools, out-of-cwd, protected files) now runs without asking" +
+          (privacyMoved ? ", and the privacy filter is off: outbound requests are not scanned for PII" : "") +
+          ". shift+tab to raise the moat again."
+      : "⚓ Moat raised — the permission gate is back on" + (privacyMoved ? ", and so is the privacy filter." : "."),
     on ? "warning" : "info",
   );
 }
@@ -455,7 +471,78 @@ const bridge = new RemoteBridge({
 // otherwise keep the fail-closed defaultLocalAsk (headless deny). A top-level TUI keeps
 // its own interactive/remote gate.
 const childChannel = isSubagentChild() ? inheritedChannelDir() : undefined;
-const localAsk = childChannel ? makeChildGateAsk(childChannel) : defaultLocalAsk;
+
+// ── headless (`-p` / `--mode json`) runs ─────────────────────────────────────────
+//
+// A top-level headless run has no screen, so the default asker denies. Two launch flags
+// change that, both typed per invocation and neither ever persisted (bin/headless-flags.mjs):
+//   --allow-spend … --max-calls/--max-spend  pre-approves named billing tools, capped
+//                                            (src/permissions/cliSpend.ts)
+//   --approve-in-app                          puts what's left to the Privateer app
+//                                            (src/remote/headlessApproval.ts)
+// Neither applies in a subagent child (its grant comes only from childSpend.ts) nor in
+// the TUI; `headlessRun` is set from Pi's own mode at session_start.
+let headlessRun = false;
+const cliGrant = isSubagentChild() ? null : readCliSpendGrant();
+const approveInAppMs = isSubagentChild() ? 0 : Number(process.env.PRIVATEER_APPROVE_IN_APP) || 0;
+
+// Price a billed call from the server's capability report — the same reservation
+// figure the server holds (tools/media.ts). Loaded on first use: most runs never price
+// anything, and media.ts has no business in the TUI's startup graph.
+async function quoteMediaCall(tool: string, input: unknown, signal?: AbortSignal): Promise<number | null> {
+  const { readMediaCapabilities, quoteMediaCallUsd } = await import("../src/tools/media.ts");
+  const a = (input && typeof input === "object" ? input : {}) as Record<string, unknown>;
+  const model = typeof a.model === "string" && a.model ? a.model : undefined;
+  const query = tool === "generate_video" || tool === "generate_sprite" ? { videoModel: model } : tool === "generate_model" ? { model } : {};
+  const caps = await readMediaCapabilities(query, signal);
+  return caps.ok ? quoteMediaCallUsd(tool, input, caps.data) : null;
+}
+
+const cliLedger = cliGrant ? new CliSpendLedger(cliGrant, quoteMediaCall) : null;
+
+// Why a particular request was denied, for the model. Keyed by the request object the
+// gate builds per call, so parallel calls never read each other's reason.
+const denialNotes = new WeakMap<PermissionRequest, string>();
+// The call's own arguments, seen by the spend check, so an app prompt can be priced
+// for THIS call rather than the dearest one the model could make.
+const requestInputs = new WeakMap<PermissionRequest, unknown>();
+
+const appApprover = approveInAppMs
+  ? new HeadlessAppApprover({
+      timeoutMs: approveInAppMs,
+      log: (line) => process.stderr.write(`${line}\n`),
+      signedIn: () => priv.hasCredentials(),
+      label: "privateer -p",
+      makeRelay: (callbacks) => new RelayClient(callbacks as any, { label: "privateer -p" }) as any,
+    })
+  : null;
+
+async function headlessAsk(req: PermissionRequest, ctx: any) {
+  if (appApprover) {
+    // Put the price on the question — "about $0.50" is what makes a phone approval an
+    // informed one. Best-effort and bounded: a slow quote must not eat the timeout.
+    let note: string | undefined;
+    if (isSpendRequest(req)) {
+      const usd = await Promise.race([
+        quoteMediaCall(req.tool, requestInputs.get(req), ctx?.signal).catch(() => null),
+        new Promise<null>((r) => setTimeout(() => r(null), 5_000)),
+      ]);
+      if (typeof usd === "number") note = `about $${usd.toFixed(2)}`;
+    }
+    const out = await appApprover.ask(req, ctx?.signal, note);
+    if (out === "deny" && !denialNotes.has(req)) {
+      denialNotes.set(req, "It was not approved in the Privateer app. Stop and report this rather than retrying.");
+    }
+    return out;
+  }
+  const out = await defaultLocalAsk(req, ctx);
+  if (out === "deny" && isSpendRequest(req) && !denialNotes.has(req)) denialNotes.set(req, headlessSpendGuidance(req.tool));
+  return out;
+}
+
+const localAsk = childChannel
+  ? makeChildGateAsk(childChannel)
+  : (req: PermissionRequest, ctx: any) => (headlessRun ? headlessAsk(req, ctx) : defaultLocalAsk(req, ctx));
 
 const gate = makePermissionGate({
   getMode: () => mode,
@@ -477,7 +564,28 @@ const gate = makePermissionGate({
   // when pi-subagents has marked us a child), so a terminal keeps asking its human. This
   // is what lets an unattended run delegate a shot to a subagent: without it the child's
   // gate denies every generate_* call, having no one to ask.
-  isSpendPreauthorized: (req) => childSpendAllows(req.tool),
+  //
+  // Plus, in a top-level headless run only, the `--allow-spend` ledger: capped, per
+  // invocation, and priced before each call when there's a --max-spend.
+  isSpendPreauthorized: async (req, input, signal) => {
+    requestInputs.set(req, input);
+    if (childSpendAllows(req.tool)) return true;
+    if (!cliLedger || !headlessRun) return false;
+    const d = await cliLedger.authorize(req.tool, input, signal);
+    if (d.ok) {
+      process.stderr.write(
+        `⚓ --allow-spend: running ${req.tool}${d.usd !== null ? ` (about $${d.usd.toFixed(2)})` : ""} — ${cliLedger.summary()}\n`,
+      );
+      return true;
+    }
+    denialNotes.set(
+      req,
+      `Not covered by this run's spend pre-approval: ${d.reason}. ` +
+        (appApprover ? "" : "Stop and report this to the user rather than retrying."),
+    );
+    return false;
+  },
+  explainDenial: (req) => denialNotes.get(req),
 });
 
 export default function privateerControl(pi: any): void {
@@ -550,6 +658,7 @@ export default function privateerControl(pi: any): void {
     // machine's real catalog and the banner shows the current spec from the start.
     if (ctx?.modelRegistry) modelReg = ctx.modelRegistry;
     if (!currentSpec && ctx?.model) currentSpec = modelSpec(ctx.model);
+    if (ctx?.model) modelRef = ctx.model;
     refreshRemoteStatus();
     // shift+tab → no quarter, and the red footer indicator when it's already on (a
     // `--no-quarter` launch, or a session replacement mid-run). Interactive TUI only:
@@ -561,12 +670,90 @@ export default function privateerControl(pi: any): void {
     if (ctx?.mode && HEADLESS.has(ctx.mode) && (process.env.PRIVATEER_MODE ?? "") === "") {
       mode = "bypass";
     }
+    headlessRun = !isSubagentChild() && (ctx?.mode === "print" || ctx?.mode === "json");
+    if (headlessRun) announceHeadlessSpend();
+  });
+
+  // Say it UP FRONT. An agent driving `privateer -p` used to plan a whole job and only
+  // hit the billing wall at the last step, because nothing said a -p run can't approve a
+  // billed call. Tell the person (stderr, before any work) and the model (its system
+  // prompt, before it plans). Quiet when nothing billable is enabled, or when no quarter
+  // lifts the gate anyway.
+  function uncoveredBilledTools(): string[] {
+    if (noQuarterActive()) return [];
+    const active: string[] = (() => {
+      try {
+        return pi.getActiveTools?.() ?? [];
+      } catch {
+        return [];
+      }
+    })();
+    return active.filter((t) => BILLED_MEDIA_TOOLS.has(t) && !cliGrant?.tools.includes(t));
+  }
+  function announceHeadlessSpend(): void {
+    const cmd = process.env.PRIVATEER_CMD || "privateer";
+    const out: string[] = [];
+    if (cliGrant) {
+      const caps = [
+        cliGrant.maxCalls !== undefined ? `at most ${cliGrant.maxCalls} call(s)` : "",
+        cliGrant.maxSpendUsd !== undefined ? `$${cliGrant.maxSpendUsd.toFixed(2)} estimated` : "",
+      ].filter(Boolean);
+      out.push(`⚓ Spend pre-approved for this run: ${cliGrant.tools.join(", ")} — ${caps.join(", ")}.`);
+    }
+    const uncovered = uncoveredBilledTools();
+    if (uncovered.length) {
+      out.push(
+        appApprover
+          ? `⚓ Billed tools (${uncovered.join(", ")}) will ask for approval in the Privateer app — up to ${Math.round(approveInAppMs / 1000)}s each.`
+          : `⚓ Heads-up: billed tools (${uncovered.join(", ")}) are enabled, but a -p run can't approve them — any call will be denied.\n` +
+              `   To allow them: --allow-spend <tool> --max-calls <n> [--max-spend <usd>], or --approve-in-app, or drive Privateer over ACP (\`${cmd} acp\`).`,
+      );
+    }
+    if (out.length) process.stderr.write(out.join("\n") + "\n");
+  }
+  pi.on("before_agent_start", (event: any) => {
+    if (!headlessRun) return;
+    const uncovered = uncoveredBilledTools();
+    const lines: string[] = [];
+    if (cliGrant) {
+      lines.push(
+        `This run may call ${cliGrant.tools.join(", ")} without further approval, within its caps` +
+          `${cliGrant.maxCalls !== undefined ? ` (at most ${cliGrant.maxCalls} call(s) in total)` : ""}` +
+          `${cliGrant.maxSpendUsd !== undefined ? ` (at most $${cliGrant.maxSpendUsd.toFixed(2)}, estimated before each call — check prices with media_capabilities)` : ""}.`,
+      );
+    }
+    if (uncovered.length) {
+      lines.push(
+        appApprover
+          ? `Calls to ${uncovered.join(", ")} bill the user's account and must be approved by them in the Privateer app; each waits for that approval.`
+          : `This is a non-interactive run with nobody to approve spending: ${uncovered.join(", ")} will be DENIED if called. ` +
+              "Do not plan work that depends on them. If the task needs one, say so up front and tell the user to re-run with " +
+              "--allow-spend <tool> --max-calls <n>, or --approve-in-app.",
+      );
+    }
+    if (!lines.length) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n# Billing in this run\n${lines.join("\n")}` };
+  });
+  pi.on("session_shutdown", () => appApprover?.close());
+
+  // 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;
+    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;
+    const described = describeErrorText(last.errorMessage, { provider: last.provider });
+    if (!described) return;
+    process.stderr.write(`privateer: ${described.message}${described.hint ? `\n  ${described.hint}` : ""}\n`);
   });
 
   // Follow local model switches too (the user picking a model in the TUI): keep
   // currentSpec current and push context so a driving app's banner stays in sync.
   pi.on("model_select", (ev: any) => {
     if (ev?.model) {
+      modelRef = ev.model;
       currentSpec = modelSpec(ev.model);
       relay?.sendContext({ model: currentSpec, cwd: process.cwd(), version: agentVersion() });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.47",
+  "version": "0.12.49",
   "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",