privateer-agent 0.12.47 → 0.12.49

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

@@ -1824,7 +1824,7 @@ index 6d0356c..ca0aa98 100644
          if (content) {
              text += `\n\n${content}`;
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index d82182c..2764952 100644
+index d82182c..08bec2d 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 @@ -10,7 +10,7 @@ import * as TuiLayouts from "@earendil-works/pi-tui";
@@ -1850,7 +1850,7 @@ index d82182c..2764952 100644
      if (!sessionManager.usesDefaultSessionDir()) {
          args.push("--session-dir", quoteIfNeeded(sessionManager.getSessionDir()));
      }
-@@ -192,6 +197,64 @@ function formatLoginProviderCompletionDescription(provider) {
+@@ -192,6 +197,77 @@ function formatLoginProviderCompletionDescription(provider) {
      const authTypes = provider.authTypes.map(formatAuthSelectorProviderType).join("/");
      return provider.name === provider.id ? authTypes : `${provider.name} · ${authTypes}`;
  }
@@ -1893,6 +1893,13 @@ index d82182c..2764952 100644
 +                message: "The provider stopped responding — the connection went idle.",
 +                hint: "No data arrived for the whole idle-timeout window, so the turn was cut off. Send it again, or run /model to switch providers (a slow model can be given longer in /settings → HTTP idle timeout).",
 +            };
++        // Privateer patch: the OpenAI SDK's whole message for a request that never got
++        // a response. Mirrors isConnectionFailureText in src/engine/errors.ts.
++        if (/^\s*(?:connection error\.?|fetch failed|other side closed|socket hang up|(?:read |connect )?(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)\b)/i.test(s))
++            return {
++                message: `Couldn't reach the model provider — the request got no response ("${s.trim().slice(0, 80)}").`,
++                hint: "Check your connection and send it again. If every message fails while a fresh `privateer` works, start a new session with /new.",
++            };
 +        return null;
 +    }
 +    if (status === 429) {
@@ -1905,7 +1912,13 @@ index d82182c..2764952 100644
 +        };
 +    }
 +    if (status === 401 || status === 403)
-+        return { message: s, hint: "Check your credentials — run /login to re-authenticate." };
++        return {
++            // "401 status code (no body)" names neither what was refused nor what to do.
++            message: /\(no body\)\s*$/i.test(s)
++                ? `The model provider ${status === 401 ? "rejected the credential" : "refused access"} this request was sent with (${status}).`
++                : s,
++            hint: "Check your credentials — run /login to re-authenticate.",
++        };
 +    if (status === 404)
 +        return { message: s, hint: "Check the model id — run /model to switch." };
 +    if (status >= 500)
@@ -1915,7 +1928,7 @@ index d82182c..2764952 100644
  export class InteractiveMode {
      runtimeHost;
      renderer;
-@@ -404,9 +467,15 @@ export class InteractiveMode {
+@@ -404,9 +480,15 @@ export class InteractiveMode {
      }
      getBuiltInCommandConflictDiagnostics(extensionRunner) {
          const builtinNames = new Set(BUILTIN_SLASH_COMMANDS.map((command) => command.name));
@@ -1932,7 +1945,7 @@ index d82182c..2764952 100644
              .map((command) => ({
              type: "warning",
              message: command.invocationName === command.name
-@@ -775,20 +844,18 @@ export class InteractiveMode {
+@@ -775,20 +857,18 @@ export class InteractiveMode {
                  this.showNewVersionNotification(newRelease);
              }
          });
@@ -1965,7 +1978,7 @@ index d82182c..2764952 100644
          // Check tmux keyboard setup asynchronously
          this.checkTmuxKeyboardSetup().then((warning) => {
              if (warning) {
-@@ -1568,7 +1635,7 @@ export class InteractiveMode {
+@@ -1568,7 +1648,7 @@ export class InteractiveMode {
          if (this.bugReportHintShown)
              return;
          this.bugReportHintShown = true;
@@ -1974,7 +1987,7 @@ index d82182c..2764952 100644
          this.ui.requestRender();
      }
      renderCurrentSessionState() {
-@@ -2419,7 +2486,17 @@ export class InteractiveMode {
+@@ -2419,7 +2499,17 @@ export class InteractiveMode {
              if (text === "/model" || text.startsWith("/model ")) {
                  const searchTerm = text.startsWith("/model ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -1993,7 +2006,7 @@ index d82182c..2764952 100644
                  return;
              }
              if (text === "/thinking" || text.startsWith("/thinking ")) {
-@@ -2497,12 +2574,42 @@ export class InteractiveMode {
+@@ -2497,12 +2587,42 @@ export class InteractiveMode {
              if (text === "/login" || text.startsWith("/login ")) {
                  const providerRef = text.startsWith("/login ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -2038,7 +2051,7 @@ index d82182c..2764952 100644
                  return;
              }
              if (text === "/new") {
-@@ -2827,9 +2934,19 @@ export class InteractiveMode {
+@@ -2827,9 +2947,19 @@ export class InteractiveMode {
                      if (entries[0]?.type !== "compaction") {
                          throw new Error("Completed compaction is missing from the session context");
                      }
@@ -2061,7 +2074,7 @@ index d82182c..2764952 100644
                      this.addMessageToChat(createCompactionSummaryMessage(event.result.summary, event.result.tokensBefore, new Date().toISOString()));
                      if (event.result.usage) {
                          this.addCompactionCostNotice({
-@@ -3253,7 +3370,7 @@ export class InteractiveMode {
+@@ -3253,7 +3383,7 @@ export class InteractiveMode {
          if (this.chatContainer.children.length > 0) {
              this.chatContainer.addChild(new Spacer(1));
          }
@@ -2070,7 +2083,7 @@ index d82182c..2764952 100644
      }
      async getUserInput() {
          const queuedInput = this.pendingUserInputs.shift();
-@@ -3597,7 +3714,17 @@ export class InteractiveMode {
+@@ -3597,7 +3727,17 @@ export class InteractiveMode {
      }
      showError(errorMessage) {
          this.chatContainer.addChild(new Spacer(1));

package/src/acp/run.ts

@@ -304,7 +304,9 @@ export async function runAcp(): Promise<void> {
     session.subscribe((ev: any) => {
       for (const ee of adapter.toEngineEvents(ev)) {
         if (ee.type === "text") holder.events.onText(ee.text);
-        else if (ee.type === "error") holder.error = ee.error;
+        // With the hint: the host shows this string and nothing else, and "Connection
+        // error." alone says neither what failed nor what to do (engine/errors.ts).
+        else if (ee.type === "error") holder.error = (ee as { hint?: string }).hint ? `${ee.error} ${(ee as { hint?: string }).hint}` : ee.error;
         // Tool activity goes BOTH to the host (rendered as live progress — without
         // it a minute of tool work looks like a hang) and to stderr, where it is
         // the only way to tell a gate denial apart from the model simply choosing

package/src/bridge/engineAdapter.ts

@@ -145,7 +145,7 @@ export function createEngineEventAdapter() {
         // 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);
+          const described = describeErrorText(raw, { provider: typeof msg.provider === "string" ? msg.provider : undefined });
           return [{
             type: "error",
             error: described?.message ?? redactText(raw || "The model call failed."),

package/src/cli/chat.ts

@@ -12,6 +12,7 @@ import "../boot.ts"; // env + attestation dispatcher, before any Pi import
 import { fileURLToPath } from "node:url"; // builtin, safe pre-boot
 import { cliPalette } from "../ui/palette.ts"; // no Pi deps → safe pre-boot
 import { noQuarterActive, setNoQuarter } from "../permissions/noQuarter.ts"; // no Pi deps → safe pre-boot
+import { privacyDisabled } from "../config/privacyDisabled.ts"; // no Pi deps → safe pre-boot
 import type { GateController } from "../ext/permissionGate.ts"; // type-only → erased, safe pre-boot
 import { createUIContext } from "../ext/headlessUi.ts"; // no Pi deps → safe pre-boot
 import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts"; // node:child_process only → safe pre-boot
@@ -419,14 +420,17 @@ async function main() {
   // same key; takes effect from the next gated action, so an approval already on
   // screen still needs an answer.
   function applyNoQuarter(on: boolean): void {
-    setNoQuarter(on);
+    const privacyWasOff = privacyDisabled();
+    setNoQuarter(on); // also `/privacy off` on the way down (src/permissions/noQuarter.ts)
+    const privacyMoved = privacyDisabled() !== privacyWasOff;
     flushOut(); // land streamed output above the notice
     console.log(
       on
         ? `\n${RED}⚑ No quarter — the permission gate is OFF for this session.${RESET}\n` +
           `${DIM}  Every action (shell, edits, destructive tools, out-of-cwd, protected files) runs without asking.\n` +
+          (privacyMoved ? `  The privacy filter is off too: outbound requests are not scanned for PII.\n` : "") +
           `  shift+tab (or /no-quarter off) raises the moat again.${RESET}`
-        : `\n${GREEN}⚓ Moat raised — the permission gate is back on.${RESET}`,
+        : `\n${GREEN}⚓ Moat raised — the permission gate is back on${privacyMoved ? ", and so is the privacy filter" : ""}.${RESET}`,
     );
   }
 

package/src/config/privacyDisabled.ts

@@ -19,6 +19,9 @@
 const ENV = "PRIVATEER_PRIVACY_OFF";
 const ALT_ENV = "PI_PRIVACY_OFF";
 
+/** Set while the filter is off BECAUSE no quarter took it down (src/permissions/noQuarter.ts). */
+export const NO_QUARTER_PRIVACY_MARK = "PRIVATEER_PRIVACY_OFF_BY_NO_QUARTER";
+
 /** True while pi-privacy is completely disabled for this session. Read live, never cached. */
 export function privacyDisabled(): boolean {
   return process.env[ENV] === "1" || process.env[ALT_ENV] === "1";
@@ -41,10 +44,12 @@ export function onPrivacyDisabledChange(fn: (disabled: boolean) => void): () =>
 
 /**
  * Set the disabled state. Modifies process.env so every module copy and child process agrees.
- * Returns the new state.
+ * Returns the new state. Clears the no-quarter mark: an explicit set is the operator's call,
+ * so raising the moat later won't flip it back (noQuarter.ts re-sets the mark after its own call).
  */
 export function setPrivacyDisabled(disabled: boolean): boolean {
   const before = privacyDisabled();
+  delete process.env[NO_QUARTER_PRIVACY_MARK];
   if (disabled) {
     process.env[ENV] = "1";
     process.env[ALT_ENV] = "1";

package/src/config/privacyPolicy.ts

@@ -89,7 +89,9 @@ export function sharedPrivacyOptions() {
     // ZDR-channel models stay at their honest floor. The live verdict still comes from
     // resolveTier above on select — this only lifts the label.
     privateerVerifiedTee: (m: any) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
-    // No quarter = unattended. The PII send-or-redact question would stall a session the
+    // No quarter = unattended. No quarter also takes the whole filter down (noQuarter.ts),
+    // so this only answers when the operator has run `/privacy on` with the moat down.
+    // The PII send-or-redact question would stall a session the
     // operator explicitly stepped away from, so pi-privacy swallows it the SAFE way —
     // redact, then send — and reports what it masked as output instead of asking. A live
     // function, not a boolean: shift+tab / `/no-quarter` flips this mid-session and the

package/src/engine/errors.ts

@@ -505,6 +505,36 @@ export function retryDelayMs(
   return Math.round(backoff * (1 - rand() * 0.25));
 }
 
+/** What the caller of describeErrorText knows about the failing request, if anything. */
+export interface ErrorTextContext {
+  /** Pi's provider id for the model that failed (e.g. "privateer", "openrouter"). */
+  provider?: string;
+}
+
+const PROVIDER_LABELS: Record<string, string> = {
+  privateer: "Privateer",
+  anthropic: "Anthropic",
+  openai: "OpenAI",
+  openrouter: "OpenRouter",
+  google: "Google",
+  tinfoil: "Tinfoil",
+  ollama: "Ollama",
+};
+
+function providerLabel(provider: string | undefined): string {
+  if (!provider) return "the model provider";
+  return PROVIDER_LABELS[provider] ?? provider;
+}
+
+// A request that never got an HTTP response, in the words the SDKs actually use:
+// OpenAI's APIConnectionError is the bare "Connection error.", undici's is "fetch
+// failed" / "other side closed", Node's are the errno names.
+const CONNECTION_FAILURE = /^\s*(?:connection error\.?|fetch failed|other side closed|socket hang up|(?:read |connect )?(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)\b)/i;
+
+export function isConnectionFailureText(text: string | null | undefined): boolean {
+  return CONNECTION_FAILURE.test(typeof text === "string" ? text : "");
+}
+
 /**
  * Describe an error we only have the TEXT of, for the one place that has nothing else.
  *
@@ -515,9 +545,14 @@ export function retryDelayMs(
  * and say the same thing `describeError` would. Returns null when there is no leading
  * status to read, so ordinary messages print unchanged.
  */
-export function describeErrorText(text: string | null | undefined): DescribedError | null {
+export function describeErrorText(
+  text: string | null | undefined,
+  context: ErrorTextContext = {},
+): DescribedError | null {
   const s = typeof text === "string" ? text : "";
   const status = Number(/^\s*(\d{3})\b/.exec(s)?.[1] ?? NaN);
+  const account = context.provider === "privateer";
+  const who = providerLabel(context.provider);
   if (!Number.isFinite(status)) {
     // No leading status: the one message we can still describe with certainty is a
     // transport idle timeout, which undici names exactly. Everything else is printed
@@ -528,6 +563,17 @@ export function describeErrorText(text: string | null | undefined): DescribedErr
         hint: IDLE_TIMEOUT_DESCRIPTION.hint,
       };
     }
+    // The OpenAI SDK's whole message for a request that never got a response. It
+    // says nothing about WHERE, so name the endpoint and the next step.
+    if (isConnectionFailureText(s)) {
+      return {
+        message: redactText(`Couldn't reach ${who} — the request got no response ("${s.trim().slice(0, 80)}").`),
+        hint: account
+          ? "Check this machine's connection. If it started around a sign-in, the session reconnects on your next message; if every message fails while a fresh `privateer` works, start a new session with /new."
+          : "Check your connection and the provider's base URL, then send it again — or run /model to switch providers.",
+        retryable: true,
+      };
+    }
     return null;
   }
 
@@ -542,9 +588,17 @@ export function describeErrorText(text: string | null | undefined): DescribedErr
     };
   }
   if (status === 401 || status === 403) {
+    // "401 status code (no body)" names neither what was refused nor what to do. The
+    // status is enough to say both.
+    const bare = /\(no body\)\s*$/i.test(s) || s.trim() === String(status);
+    const refused = status === 401 ? "rejected the credential" : "refused access";
     return {
-      message: redactText(compactProviderError(s)),
-      hint: "Check your credentials — run /login to re-authenticate.",
+      message: redactText(
+        bare ? `${who} ${refused} this request was sent with (${status}).` : compactProviderError(s),
+      ),
+      hint: account
+        ? "This terminal's Privateer session was refused. It is renewed automatically on your next message; if it keeps failing, run /login (or `privateer auth status` to see whether this machine is signed in)."
+        : `Check the API key for ${who} — run /login, or set the provider's API key env var.`,
     };
   }
   if (status === 404) {

package/src/ext/permissionGate.ts

@@ -57,7 +57,13 @@ export interface GateController {
   // session can spend what it was told it may spend instead of denying every media
   // call for want of a human. Lifts `alwaysAsk` and nothing else — see
   // ModeGate.isSpendPreauthorized for the guards.
-  isSpendPreauthorized?(req: PermissionRequest): boolean;
+  // `input` and `signal` are the call's own, for a grant that prices the call before
+  // answering (the `--max-spend` ledger, permissions/cliSpend.ts).
+  isSpendPreauthorized?(req: PermissionRequest, input?: unknown, signal?: AbortSignal): boolean | Promise<boolean>;
+  // Extra words for the model when the gate denies `req` — WHY, and what would allow it
+  // (e.g. a headless run explaining --allow-spend). Appended to the denial; absent ⇒ the
+  // generic denial text alone.
+  explainDenial?(req: PermissionRequest): string | undefined;
   // Block a tool outright while the turn is remote-driven (only consulted when
   // getRemote() is true). For tools whose own prompts render on the host terminal
   // rather than the relay — e.g. pi-subagents — so a driven turn can't wedge on an
@@ -174,9 +180,22 @@ export async function decideToolCall(
     getNoQuarter: ctrl.getNoQuarter,
     getAutoApprove: ctrl.getAutoApprove,
     getSkipAllPermissions: ctrl.getSkipAllPermissions,
-    isSpendPreauthorized: ctrl.isSpendPreauthorized,
+    isSpendPreauthorized: ctrl.isSpendPreauthorized
+      ? (r: PermissionRequest) => ctrl.isSpendPreauthorized!(r, input, ctx.signal)
+      : undefined,
   });
 
+  // Why, when there is more to say than "denied" — read at denial time, so it reflects
+  // what the ask learned (a spend ledger's refusal reason, say).
+  const why = (): string => {
+    try {
+      const extra = ctrl.explainDenial?.(req);
+      return extra ? ` ${extra}` : "";
+    } catch {
+      return "";
+    }
+  };
+
   let decision: "allow" | "deny";
   try {
     decision = await withTimeout(gate.request(req), ctrl.approvalTimeoutMs, ctx.signal);
@@ -186,13 +205,13 @@ export async function decideToolCall(
     // tell the model to stop retrying and take a different path (or ask the user).
     return {
       block: true,
-      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default. Do not retry the same command; it will be blocked again. Try a different approach or ask the user to run it.`,
+      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default. Do not retry the same command; it will be blocked again. Try a different approach or ask the user to run it.${why()}`,
     };
   }
   if (decision === "deny") {
     return {
       block: true,
-      reason: `${req.title} was denied by the permission gate. Do not retry the same command; it will be denied again. Take a different approach or ask the user to run it themselves.`,
+      reason: `${req.title} was denied by the permission gate. Do not retry the same command; it will be denied again. Take a different approach or ask the user to run it themselves.${why()}`,
     };
   }
   return undefined;

package/src/permissions/cliSpend.ts

@@ -0,0 +1,163 @@
+// SPEND PRE-APPROVAL FOR ONE HEADLESS RUN, typed on the command line.
+//
+//   privateer -p --allow-spend generate_video --max-calls 1 --max-spend 1.00 "…"
+//
+// THE PROBLEM. A `-p` run has no screen, so the gate's local asker has nobody to ask
+// and every billing tool — each one `alwaysAsk` — is denied. An agent driving Privateer
+// from a script could plan a whole film and only discover at the last step that the
+// one call that mattered could never be approved. The routine grant (childSpend.ts)
+// solves this for scheduled runs; this is the same idea for a run a person starts.
+//
+// WHY A FLAG, NOT AN ENV VAR. The grant is typed per invocation, capped, and gone when
+// the process exits. The launcher carries it to the gate in PRIVATEER_CLI_SPEND — the
+// only channel into Pi's process — but deletes any inherited value before parsing argv
+// (bin/privateer-launch.mjs), so an export lingering in someone's shell never counts.
+// And it is honoured only where the flag can apply: a TOP-LEVEL headless session. Not
+// the TUI (a person approves each call there), and not a subagent child (a child's
+// grant comes only from childSpend.ts, whose caps this ledger does not share).
+//
+// WHAT IT LIFTS. Exactly what the routine grant lifts, through the same
+// ModeGate.isSpendPreauthorized hook and under the same guards: `alwaysAsk` must be the
+// only reason to ask, and a call that leaves the working directory or touches a
+// protected file is never covered. On top of that, two caps:
+//
+//   • --max-calls counts calls this ledger ALLOWED, not calls that succeeded — a call
+//     that then fails server-side still used its slot. Over-counting is the safe error.
+//   • --max-spend is checked BEFORE each call against the server's own reservation
+//     figure for that exact call (tools/media.ts quoteMediaCallUsd), which is
+//     worst-case by design. A call that can't be priced is REFUSED under a dollar cap
+//     rather than waved through — a cap that skips what it can't measure isn't one.
+
+import type { PermissionRequest } from "./gate.ts";
+import { BILLED_MEDIA_TOOLS } from "./classify.ts";
+
+/** The env var the launcher writes from `--allow-spend` (mirrors bin/headless-flags.mjs). */
+export const CLI_SPEND_ENV = "PRIVATEER_CLI_SPEND";
+
+export interface CliSpendGrant {
+  tools: string[];
+  maxCalls?: number;
+  maxSpendUsd?: number;
+}
+
+/**
+ * The grant this run was launched with, or null. Defensive: anything malformed, any
+ * tool that isn't a billing tool, or a grant with no cap at all reads as NO grant —
+ * the launcher never writes one of those, so seeing one means it didn't come from it.
+ */
+export function readCliSpendGrant(env: NodeJS.ProcessEnv = process.env): CliSpendGrant | null {
+  const raw = env[CLI_SPEND_ENV];
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const g = parsed as Partial<CliSpendGrant>;
+  if (!g || !Array.isArray(g.tools)) return null;
+  const tools = g.tools.filter((t): t is string => typeof t === "string" && BILLED_MEDIA_TOOLS.has(t));
+  if (tools.length === 0) return null;
+  const maxCalls = Number.isInteger(g.maxCalls) && (g.maxCalls as number) > 0 ? (g.maxCalls as number) : undefined;
+  const maxSpendUsd =
+    typeof g.maxSpendUsd === "number" && Number.isFinite(g.maxSpendUsd) && g.maxSpendUsd > 0 ? g.maxSpendUsd : undefined;
+  if (maxCalls === undefined && maxSpendUsd === undefined) return null;
+  return { tools, ...(maxCalls !== undefined ? { maxCalls } : {}), ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}) };
+}
+
+/** Price one call of `tool` with these arguments, in USD; null when it can't be priced. */
+export type SpendQuote = (tool: string, input: unknown, signal?: AbortSignal) => Promise<number | null>;
+
+export type SpendDecision = { ok: true; usd: number | null } | { ok: false; reason: string };
+
+const money = (n: number): string => `$${n.toFixed(2)}`;
+
+/**
+ * The running tally for one grant. One per process: the caps are for the whole run.
+ */
+export class CliSpendLedger {
+  private calls = 0;
+  private spentUsd = 0;
+
+  constructor(
+    readonly grant: CliSpendGrant,
+    private readonly quote: SpendQuote,
+  ) {}
+
+  /**
+   * May this call spend? Records it when it may. The check and the record happen in
+   * one synchronous step after the (async) quote, so two calls racing in parallel can't
+   * both squeeze under the same remaining budget.
+   */
+  async authorize(tool: string, input: unknown, signal?: AbortSignal): Promise<SpendDecision> {
+    const { tools, maxCalls, maxSpendUsd } = this.grant;
+    if (!tools.includes(tool)) {
+      return { ok: false, reason: `this run's --allow-spend covers ${tools.join(", ")}, not ${tool}` };
+    }
+    if (maxCalls !== undefined && this.calls >= maxCalls) {
+      return { ok: false, reason: `this run's --max-calls ${maxCalls} is used up` };
+    }
+    let usd: number | null = null;
+    if (maxSpendUsd !== undefined) {
+      try {
+        usd = await this.quote(tool, input, signal);
+      } catch {
+        usd = null;
+      }
+      if (usd === null) {
+        return {
+          ok: false,
+          reason:
+            `${tool} can't be priced before it runs, so it can't be checked against --max-spend ${money(maxSpendUsd)}` +
+            (tool === "generate_image" || tool === "generate_sprite"
+              ? " (a call that overrides the image model is one of those — leave `model`/`image_model` unset)"
+              : "") +
+            ". Cap this run with --max-calls instead",
+        };
+      }
+      // Recheck after the await: a parallel call may have spent while we were quoting.
+      if (maxCalls !== undefined && this.calls >= maxCalls) {
+        return { ok: false, reason: `this run's --max-calls ${maxCalls} is used up` };
+      }
+      if (this.spentUsd + usd > maxSpendUsd + 1e-9) {
+        return {
+          ok: false,
+          reason:
+            `this call is estimated at ${money(usd)} and only ${money(Math.max(0, maxSpendUsd - this.spentUsd))} ` +
+            `of this run's --max-spend ${money(maxSpendUsd)} is left`,
+        };
+      }
+      this.spentUsd += usd;
+    }
+    this.calls++;
+    return { ok: true, usd };
+  }
+
+  /** One line for the end of the run / a denial: what the grant has used so far. */
+  summary(): string {
+    const { maxCalls, maxSpendUsd } = this.grant;
+    const parts = [`${this.calls}${maxCalls !== undefined ? `/${maxCalls}` : ""} billed call(s)`];
+    if (maxSpendUsd !== undefined) parts.push(`~${money(this.spentUsd)} of ${money(maxSpendUsd)} estimated`);
+    return parts.join(", ");
+  }
+}
+
+/**
+ * The guidance a headless run gives when a billed call hits the gate with nothing to
+ * approve it — written for the MODEL as much as the person, since the model is the one
+ * that reads a tool denial and decides what to do next. It names every way out.
+ */
+export function headlessSpendGuidance(tool: string, cmd = process.env.PRIVATEER_CMD || "privateer"): string {
+  return (
+    `This is a headless run (-p) with no one at a screen to approve ${tool}, which bills the account. ` +
+    `It can't be approved from inside this run. To allow it, the person running Privateer can re-run with ` +
+    `\`${cmd} -p --allow-spend ${tool} --max-calls 1\` (optionally --max-spend <usd>), add --approve-in-app to ` +
+    `approve it from the Privateer app, or drive Privateer over ACP (\`${cmd} acp\`), where the controlling ` +
+    `program is asked. Stop and report this rather than retrying.`
+  );
+}
+
+/** Is this the request a CLI grant could ever cover? (Billing tool, and billing is the only ask.) */
+export function isSpendRequest(req: PermissionRequest): boolean {
+  return req.alwaysAsk === true && BILLED_MEDIA_TOOLS.has(req.tool);
+}

package/src/permissions/modeGate.ts

@@ -63,7 +63,12 @@ export interface ModeGateDeps {
   // Consulted ONLY to lift `alwaysAsk`, and only under the guards in ModeGate.request.
   // Absent ⇒ nothing is pre-authorized, which is the posture every interactive session
   // keeps: a terminal always asks its human, however cheap the call.
-  isSpendPreauthorized?: (req: PermissionRequest) => boolean;
+  //
+  // May be async: a `--max-spend` grant prices the call before answering (cliSpend.ts).
+  // It is consulted LAST, after every other guard has passed, because a grant with a
+  // budget RECORDS what it allows — asking it about a call the mode would refuse anyway
+  // would spend budget on nothing.
+  isSpendPreauthorized?: (req: PermissionRequest) => boolean | Promise<boolean>;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -129,8 +134,9 @@ export class ModeGate implements PermissionGate {
       req.alwaysAsk &&
       !req.outside &&
       !req.protected &&
-      this.deps.isSpendPreauthorized?.(req) === true &&
-      decideAuto({ ...req, alwaysAsk: false }, this.deps.getMode(), this.deps.allowlist, denylist) === "allow"
+      this.deps.isSpendPreauthorized &&
+      decideAuto({ ...req, alwaysAsk: false }, this.deps.getMode(), this.deps.allowlist, denylist) === "allow" &&
+      (await this.deps.isSpendPreauthorized(req)) === true
     ) {
       return "allow";
     }

package/src/permissions/noQuarter.ts

@@ -27,9 +27,20 @@
 //     process.env is the one thing all those copies share, so the state lives there and
 //     nowhere else: every reader, in every extension, sees every toggle.
 //
+// NO QUARTER ALSO TAKES THE PRIVACY FILTER DOWN. Lowering the moat is the "step away"
+// switch, and a turn that runs to completion unattended must not stall on pi-privacy's
+// PII prompt either — so going to no quarter is also `/privacy off`. Raising the moat
+// puts the filter back, but ONLY if no quarter is what took it down: a session already
+// running with `/privacy off` (or `--no-privacy`) stays off. The marker that records
+// "no quarter did this" lives in the env for the same cross-copy reasons as the flag,
+// and setPrivacyDisabled clears it — so an explicit `/privacy on|off` mid-no-quarter
+// is the operator's word and a later shift+tab doesn't overrule it.
+//
 // IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere,
 // including boot-ordered entrypoints (see boot.ts's ORDERING CONTRACT).
 
+import { NO_QUARTER_PRIVACY_MARK, privacyDisabled, setPrivacyDisabled } from "../config/privacyDisabled.ts";
+
 const ENV = "PRIVATEER_NO_QUARTER";
 
 /** True while the gate is fully lowered for this session. Read live, never cached. */
@@ -39,8 +50,16 @@ export function noQuarterActive(): boolean {
 
 /** Set the state — in the env, so every copy of this module and every child agrees. Returns the new state. */
 export function setNoQuarter(on: boolean): boolean {
-  if (on) process.env[ENV] = "1";
-  else delete process.env[ENV];
+  if (on) {
+    process.env[ENV] = "1";
+    if (!privacyDisabled()) {
+      setPrivacyDisabled(true);
+      process.env[NO_QUARTER_PRIVACY_MARK] = "1";
+    }
+  } else {
+    delete process.env[ENV];
+    if (process.env[NO_QUARTER_PRIVACY_MARK] === "1") setPrivacyDisabled(false); // clears the mark
+  }
   return on;
 }