privateer-agent 0.12.13 → 0.12.15

package/src/config/desktopApp.ts

@@ -0,0 +1,138 @@
+// Where the Privateer DESKTOP app lives on this machine, and how to bring it up.
+//
+// The desktop app and this terminal are two front ends over one home: both read
+// ~/.privateer, so they share the account login, the model config, the MCP catalog
+// and the per-folder spawn defaults (config/spawns.ts). That makes "open the app"
+// a genuinely useful thing for a terminal to offer — nothing is handed over, the
+// state is already common — which is what /desktop (extensions/privateer-desktop.ts)
+// does, and what the working-line tip in privateer-hints.ts points at.
+//
+// WHY DETECTION AND NOT JUST A DOWNLOAD LINK. A tip that advertises software the
+// user hasn't got is an ad; one that names a command for software they HAVE is
+// discoverability. So both consumers ask this module first, and the hint stays
+// silent on a machine with no app installed.
+//
+// NO FOLDER HANDOFF. The app takes no path argument today — its second-instance
+// handler just focuses the running window (desktop/src/main/main.mjs) — so /desktop
+// opens the app, and the user picks this folder from File ▸ Spawn Privateer at…,
+// where the spawn record this terminal already shares makes it start on the same
+// model and connectors. If the app ever learns a folder argv, this is the one place
+// that has to change.
+//
+// IMPORT-SAFETY: node builtins only, no Pi imports, no side effects — safe from an
+// extension under jiti and from a pre-boot entry alike.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/** Per-platform download pages (README ▸ Desktop app). No Linux build exists. */
+const DOWNLOAD_MAC = "https://privateer.pro/download/mac";
+const DOWNLOAD_MAC_INTEL = "https://privateer.pro/download/mac-intel";
+const DOWNLOAD_WINDOWS = "https://privateer.pro/download/windows";
+
+/**
+ * The download page to lead with on THIS machine, or null where we ship no desktop
+ * build. macOS is split by CPU family — the arm64 dmg won't run on an Intel Mac —
+ * and process.arch is the interpreter's answer, not the machine's: an Apple-silicon
+ * Mac running a Rosetta node reports x64 and would be led to the Intel build. That
+ * is survivable rather than solved (detecting the translation means shelling out to
+ * `sysctl sysctl.proc_translated` for one link) because the OTHER build is offered
+ * alongside it — see desktopDownloadAltUrl.
+ */
+export function desktopDownloadUrl(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | null {
+  if (platform === "darwin") return arch === "x64" ? DOWNLOAD_MAC_INTEL : DOWNLOAD_MAC;
+  if (platform === "win32") return DOWNLOAD_WINDOWS;
+  return null; // electron-builder.yml targets mac + win only
+}
+
+/**
+ * The macOS build for the OTHER CPU family, so a Mac user is never one wrong arch
+ * away from a download that won't launch. Null everywhere else: Windows ships one
+ * x64 installer and there is no Linux build at all.
+ */
+export function desktopDownloadAltUrl(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | null {
+  if (platform !== "darwin") return null;
+  return arch === "x64" ? DOWNLOAD_MAC : DOWNLOAD_MAC_INTEL;
+}
+
+/**
+ * The installed app, or null. Ordered by confidence:
+ *
+ *  1. OUR OWN interpreter, when the terminal is running on the app's bundled Node.
+ *     The desktop's CLI shim runs `privateer` through the app binary itself with
+ *     ELECTRON_RUN_AS_NODE=1 (desktop/src/main/cliShim.mjs), so process.execPath IS
+ *     the app — and it's the copy the user actually installed, wherever they put it.
+ *  2. The standard install locations. macOS drag-install goes to /Applications or
+ *     ~/Applications; the Windows installer is per-user NSIS (perMachine: false) so
+ *     %LOCALAPPDATA%\Programs\Privateer is the default, with Program Files covered
+ *     for an install that chose it (allowToChangeInstallationDirectory: true).
+ *
+ * A user who installed somewhere else entirely reads as "not installed" — which
+ * costs them a download link they don't need, and never a wrong app launched.
+ */
+export function desktopAppPath(
+  platform: NodeJS.Platform = process.platform,
+  env: Record<string, string | undefined> = process.env,
+  execPath: string = process.execPath,
+): string | null {
+  const hit = (p: string): string | null => (p && existsSync(p) ? p : null);
+
+  if (platform === "darwin") {
+    // …/Privateer.app/Contents/MacOS/Privateer → …/Privateer.app
+    const marker = "/Privateer.app/";
+    const at = execPath.indexOf(marker);
+    if (at >= 0) {
+      const bundle = hit(execPath.slice(0, at + marker.length - 1));
+      if (bundle) return bundle;
+    }
+    return hit("/Applications/Privateer.app") ?? hit(join(homedir(), "Applications", "Privateer.app"));
+  }
+
+  if (platform === "win32") {
+    if (/^privateer\.exe$/i.test(basename(execPath))) {
+      const self = hit(execPath);
+      if (self) return self;
+    }
+    const local = env.LOCALAPPDATA;
+    const files = env.ProgramFiles;
+    return (
+      (local ? hit(join(local, "Programs", "Privateer", "Privateer.exe")) : null) ??
+      (files ? hit(join(files, "Privateer", "Privateer.exe")) : null)
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Launch (or focus) the desktop app. Best-effort and never throws — the caller
+ * reports the failure as text, the way openBrowser.ts does.
+ *
+ * ELECTRON_RUN_AS_NODE IS STRIPPED, and that is load-bearing rather than tidy: when
+ * this terminal was itself started by the desktop's CLI shim, that variable is set
+ * in our environment, and a child inheriting it starts the app binary as a bare Node
+ * that exits without ever drawing a window. `open` goes through LaunchServices and
+ * wouldn't pass it on anyway; the Windows path spawns the exe directly and would.
+ */
+export function openDesktopApp(appPath: string, platform: NodeJS.Platform = process.platform): boolean {
+  const { ELECTRON_RUN_AS_NODE: _drop, ...env } = process.env;
+  try {
+    const child =
+      platform === "darwin"
+        ? spawn("open", ["-a", appPath], { detached: true, stdio: "ignore", env })
+        : spawn(appPath, [], { detached: true, stdio: "ignore", env });
+    child.on("error", () => {}); // a spawn failure must not raise on the event loop
+    child.unref(); // never hold the CLI's exit open
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/config/moat.ts

@@ -177,36 +177,16 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
 
   const { makePermissionGate } = await import("../ext/permissionGate.ts");
   const { makePiPrivacyExtension } = await import("pi-privacy");
-  const { makeAccountProvider, privateerChannel } = await import("../providers/account.ts");
-  const { hasCredentials } = await import("../auth/privateer.ts");
+  const { makeAccountProvider } = await import("../providers/account.ts");
   const { webEnabled, mediaEnabled } = await import("./hosted.ts");
-  const { noQuarterActive } = await import("../permissions/noQuarter.ts");
-  const { cliPalette, detectScheme } = await import("../ui/palette.ts");
+  const { sharedPrivacyOptions } = await import("./privacyPolicy.ts");
 
   const factories: ExtensionFactory[] = [makePermissionGate(opts.gate)];
 
-  // Per-model verified-TEE capability for pi-privacy's /models picker: show Privateer's
-  // TEE-channel models (near/tinfoil/phala) as "◆ Verifiable TEE" when logged in, while
-  // ZDR-channel models stay at their honest floor. The live verdict still comes from
-  // accountPosture on select — this only lifts the label.
-  factories.push(
-    makePiPrivacyExtension({
-      privateerVerifiedTee: (m: any) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
-      // No quarter = unattended: the PII send-or-redact question would block a session
-      // the operator explicitly stepped away from, so it's swallowed the safe way —
-      // auto-redact + send — and what was masked surfaces as output instead. A live
-      // function, not a boolean: shift+tab / /no-quarter flips this mid-session.
-      piiUnattended: noQuarterActive,
-      // Color-coat that notice as the moat acting on your behalf: the red no-quarter
-      // flag (same glyph/color as the no-quarter banner in chat.ts), body in the
-      // accent color — distinct from yellow warnings and red errors.
-      renderPiiAutoRedact: (notice: string) => {
-        const p = cliPalette(detectScheme());
-        const body = notice.startsWith("⚑ ") ? notice.slice(2) : notice;
-        return `${p.RED}⚑${p.RESET} ${p.CYAN}${body}${p.RESET}`;
-      },
-    }),
-  );
+  // pi-privacy is configured in exactly ONE place, shared with the DISCOVERED copy of this
+  // extension (the TUI's, and every subagent child's) — see ./privacyPolicy.ts for the two
+  // bugs that came of configuring it in two.
+  factories.push(makePiPrivacyExtension(sharedPrivacyOptions()));
   factories.push(makeAccountProvider()); // must follow pi-privacy — see header
 
   if (opts.relayFiles) {

package/src/config/moatManifest.json

@@ -11,6 +11,7 @@
     { "name": "privateer-privacy", "entry": "extensions/privateer-privacy.ts", "note": "pi-privacy + account tier resolver" },
     { "name": "privateer-connect", "entry": "extensions/privateer-connect.ts", "note": "/connect — MCP connector manager" },
     { "name": "privateer-media", "entry": "extensions/privateer-media.ts", "note": "image/video/speech/music + ffmpeg compose" },
+    { "name": "privateer-desktop", "entry": "extensions/privateer-desktop.ts", "note": "/desktop — open the Privateer desktop app" },
     { "name": "privateer-hints", "entry": "extensions/privateer-hints.ts", "note": "rotating tips in the working line + /hints" },
     { "name": "privateer-update", "entry": "extensions/privateer-update.ts", "note": "tool pack updates in place — banner flag + /update" },
     { "name": "privateer-speak", "entry": "extensions/privateer-speak.ts", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },

package/src/config/moatManifest.ts

@@ -27,6 +27,11 @@ import { readFileSync } from "node:fs";
  * `dep` is a node_modules specifier as [packageName, ...pathSegments], resolved through
  * the node_modules chain at launch (npm hoists, so a fixed path would miss). Exactly one
  * of the two is set.
+ *
+ * `note` is USER-VISIBLE: relayClient.sendExtensions ships it to the app, which lists it
+ * under each built-in in the Extensions manager. Write it as a one-line description of
+ * what the extension gives the user (English only — the app renders it verbatim, as it
+ * already does for the agent's status messages), not as a code comment.
  */
 export interface MoatShim {
   name: string;

package/src/config/privacyPolicy.ts

@@ -0,0 +1,97 @@
+// The pi-privacy options that must be the SAME however a session reaches pi-privacy.
+//
+// There are two call sites, and they are genuinely separate routes — not one path with a
+// fallback:
+//
+//   - src/config/moat.ts builds the extension from FACTORIES: the harbor's sessions,
+//     live tasks, the channels runner, ACP, the lean REPL.
+//   - extensions/privateer-privacy.ts is what Pi DISCOVERS for the interactive TUI, and
+//     what bin/privateer-subagent.mjs injects (`-e`) into every subagent child.
+//
+// They drifted, and the drift was the bug this module exists to make impossible: the
+// factory side wired the unattended signal and the discovered side didn't, so in the
+// terminal `--no-quarter` (and shift+tab) lowered the permission moat while pi-privacy
+// still stopped the turn with "PII detected — send as-is or redact?". No quarter means no
+// prompts, from every gate in the session, not just ours.
+//
+// EVERYTHING pi-privacy is configured with lives here — there is no "and each side adds
+// its own bit" left, because that arrangement is what produced both bugs. The other one:
+// c2ee0fa added `resolveTier` to the discovered extension to stop the PII gate
+// over-warning on the account channel (pi-privacy's own catalog only knows Privateer's
+// PUBLIC developer key, which floors to zdr-policy, so a session on an ATTESTED account
+// TEE model was judged unverified and asked about PII on every turn). The factory-built
+// sessions never got it, and they never got the badge right either. Symmetrically, they
+// had `privateerVerifiedTee` and the discovered copy didn't.
+//
+// IMPORT-SAFETY: this module reaches the account channel, so it pulls Pi-touching code
+// and node builtins — it is NOT safe to import from a boot-ordered entrypoint (see
+// boot.ts's ORDERING CONTRACT). moat.ts therefore imports it DYNAMICALLY, inside
+// buildMoat(), exactly as it does every other Pi-touching import. Extensions load late
+// and import it statically.
+
+import { noQuarterActive } from "../permissions/noQuarter.ts";
+import { cliPalette, detectScheme } from "../ui/palette.ts";
+import { accountPosture, privateerChannel } from "../providers/account.ts";
+import { hasCredentials } from "../auth/privateer.ts";
+
+// Color-coat pi-privacy's auto-redact notice as the moat acting on your behalf: the red
+// no-quarter flag (same glyph and color as the no-quarter banner in chat.ts and the gate
+// extension's status line), body in the accent color — distinct from a yellow warning and
+// from a red error, because this is neither: it's the answer we gave for you.
+function renderPiiAutoRedact(notice: string): string {
+  const p = cliPalette(detectScheme());
+  const body = notice.startsWith("⚑ ") ? notice.slice(2) : notice;
+  return `${p.RED}⚑${p.RESET} ${p.CYAN}${body}${p.RESET}`;
+}
+
+/** The pi-privacy options every Privateer session gets, whichever route built it. */
+export function sharedPrivacyOptions() {
+  return {
+    // The account channel's real posture. pi-privacy ships a `privateer` provider, but it
+    // is the PUBLIC developer-key channel (sk-priv-…, server-proxied and unverifiable
+    // end-to-end), so from the package alone every privateer/* model floors to
+    // zdr-policy. The in-app ACCOUNT channel is a different thing — its own OAuth
+    // session, account server and sealed relay — and only the host can say what it
+    // resolves to: tee-verified for a quote WE checked over the sealed path,
+    // tee-unverified for a proxied enclave we can't bind to this connection, zdr-policy
+    // for the ZDR-channel models. Without this hook a session running an ATTESTED TEE
+    // model is judged unverified, so the badge lies and the PII gate asks about every
+    // turn — the over-warning c2ee0fa fixed for the terminal and nowhere else.
+    resolveTier: async (provider: string, modelId: string) => {
+      if (provider !== "privateer") return undefined; // pi-privacy handles its own providers
+      return (await accountPosture(modelId)).tier;
+    },
+    // Per-model verified-TEE capability for pi-privacy's /models picker: show Privateer's
+    // TEE-channel models (near/tinfoil/phala) as "◆ Verifiable TEE" when logged in, while
+    // 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
+    // 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
+    // gate re-reads it on every request.
+    piiUnattended: noQuarterActive,
+    renderPiiAutoRedact,
+    // pi-privacy's INGEST gate: credentials arriving in a tool result are masked before
+    // they enter context (otherwise they're re-sent every turn and written to the session
+    // file on disk). We already redact tool output in src/ext/permissionGate.ts, so its
+    // default "warn" would put an interactive prompt in front of something this app has
+    // always handled silently — "redact" keeps our UX and still takes the added coverage.
+    //
+    // The two redactors are COMPLEMENTARY, not duplicative, which is why we run both:
+    // ours masks the configured provider keys by exact value (from env/config) plus the
+    // provider-specific shapes (sk-/AIza/xai-/gsk_/csk-/vapi_/fw_/Z.ai, auth headers);
+    // pi-privacy's catches what shows up in USER code and shell output — AWS AKIA/ASIA,
+    // GitHub gh[pousr]_, JWTs, PEM private-key blocks, Slack, Stripe — none of which our
+    // patterns match.
+    //
+    // Order between the two is NOT guaranteed: pi discovers extensions with a bare
+    // readdirSync and never sorts, so it's filesystem-dependent (alphabetical on this box
+    // today, not by contract). "redact" makes that moot — both handlers run
+    // unconditionally and each masks its own patterns, so the surviving content is the
+    // same either way. Under "warn" the order WOULD matter, since it decides whether the
+    // prompt is raised on a raw key or one we already masked.
+    toolResultPolicy: "redact" as const,
+  };
+}

package/src/engine/errors.ts

@@ -117,6 +117,99 @@ export function isAccountCapCode(code: string | null | undefined): boolean {
   return typeof code === "string" && CAP_CODE.test(code);
 }
 
+// ── Oversized / non-API error bodies ─────────────────────────────────────────
+//
+// An inference endpoint does not always answer as an API. Put a WAF, a proxy or a
+// captive portal in front of one and a rejected request comes back as an HTML page,
+// which the provider SDK folds whole into `error.message` — status first, body after.
+//
+// The incident this exists for: the account channel's edge WAF answered a turn with a
+// 403 block page carrying three inline base64 web fonts, so `errorMessage` was 221 KB.
+// Pi printed it into the terminal in full, appended it to the session file on every
+// attempt (a 1.8 MB session), and ran its transient-error regex over it — and a
+// megabyte of base64 reliably contains "429", "500", "502", so a permanent 403 looked
+// retryable and burned the whole retry budget before the user saw anything.
+//
+// Both halves are fixed where Pi reads the message (see the patch in
+// patches/@earendil-works+pi-coding-agent+*.patch, which mirrors these two helpers):
+// squeeze the page down to the line a person can act on, and let the STATUS decide
+// retryability rather than a substring of the body.
+
+/** Hard cap on an error message we display, persist, or classify. */
+export const MAX_ERROR_CHARS = 2_000;
+
+/** How much of an HTML page's visible text is worth keeping. */
+const MAX_PAGE_TEXT_CHARS = 600;
+
+const HTML_DOC = /<!doctype html|<html[\s>]/i;
+
+/** Tags whose contents are never prose: markup, styling, or a logo. */
+const NON_PROSE = /<(script|style|svg|head|noscript)\b[\s\S]*?<\/\1\s*>/gi;
+
+const ENTITIES: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", "#39": "'", "#x27": "'",
+};
+
+function plainText(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (m, code: string) => {
+      const key = code.toLowerCase();
+      if (ENTITIES[key] !== undefined) return ENTITIES[key];
+      if (key.startsWith("#x")) return String.fromCodePoint(parseInt(key.slice(2), 16) || 0) || m;
+      if (key.startsWith("#")) return String.fromCodePoint(parseInt(key.slice(1), 10) || 0) || m;
+      return m;
+    })
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Reduce a provider error message to something worth showing, storing and classifying.
+ *
+ * An HTML page collapses to its status, its <title> and its visible text — which is
+ * where a WAF puts the one detail the user needs to report ("Request ID: …"). Anything
+ * else over the cap is truncated. Text already short and non-HTML is returned unchanged,
+ * so ordinary provider errors pass through untouched.
+ */
+export function compactProviderError(raw: string): string {
+  const text = typeof raw === "string" ? raw : String(raw ?? "");
+  if (!HTML_DOC.test(text)) {
+    if (text.length <= MAX_ERROR_CHARS) return text;
+    return `${text.slice(0, MAX_ERROR_CHARS)}… [dropped ${text.length - MAX_ERROR_CHARS} chars]`;
+  }
+
+  const status = /^\s*(\d{3})\b/.exec(text)?.[1];
+  const title = plainText(/<title[^>]*>([\s\S]*?)<\/title>/i.exec(text)?.[1] ?? "");
+  const body = plainText(text.replace(NON_PROSE, " "));
+  const visible = [title, body].filter(Boolean).join(" — ").slice(0, MAX_PAGE_TEXT_CHARS);
+
+  return (
+    `${status ?? "HTTP error"} — an HTML page, not an API response (something in front of ` +
+    `the provider answered: a WAF, a proxy, or a captive portal): ` +
+    `${visible || "(no readable text)"} [dropped ${text.length} chars of HTML]`
+  );
+}
+
+// Client-error statuses that CAN clear on their own: a timeout, a lock conflict, an
+// early-data replay, a throttle. Every other 4xx is the request itself being wrong.
+const TRANSIENT_CLIENT_STATUS = new Set([408, 409, 425, 429]);
+
+/**
+ * True when the message opens with an HTTP status that retrying cannot clear.
+ *
+ * Both provider paths put the status first — the OpenAI-shaped SDK builds
+ * `"403 <body>"`, pi-messages builds `"403 Forbidden: <body>"` — so the status is a
+ * fact we can read, where a substring of the body is only a guess. 5xx and messages
+ * with no leading status are left to the caller's own classifier.
+ */
+export function isHardHttpFailure(text: string | null | undefined): boolean {
+  const m = /^\s*(\d{3})\b/.exec(typeof text === "string" ? text : "");
+  if (!m) return false;
+  const status = Number(m[1]);
+  return status >= 400 && status < 500 && !TRANSIENT_CLIENT_STATUS.has(status);
+}
+
 function rawMessage(err: unknown): string {
   if (err instanceof Error) return err.message;
   if (typeof err === "string") return err;
@@ -243,5 +336,8 @@ export function describeError(err: unknown): DescribedError {
     });
   }
 
-  return out({ message: text });
+  // Unrecognized: show the provider's own words rather than swallow them — but an
+  // unrecognized error is exactly where a WAF block page or a megabyte of markup
+  // arrives, so it goes through the compactor first.
+  return out({ message: compactProviderError(text) });
 }

package/src/ext/permissionGate.ts

@@ -53,6 +53,11 @@ export interface GateController {
   // launch flag (env PRIVATEER_NO_QUARTER); when true the gate auto-allows every
   // action with no prompt.
   getSkipAllPermissions?(): boolean;
+  // Billing tools the operator authorized before this run started, so an unattended
+  // 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;
   // 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
@@ -144,6 +149,7 @@ export async function decideToolCall(
     getNoQuarter: ctrl.getNoQuarter,
     getAutoApprove: ctrl.getAutoApprove,
     getSkipAllPermissions: ctrl.getSkipAllPermissions,
+    isSpendPreauthorized: ctrl.isSpendPreauthorized,
   });
 
   let decision: "allow" | "deny";

package/src/harbor/index.ts

@@ -60,7 +60,7 @@ import { deliver, type RelayPusher, type CloudPusher } from "../routines/deliver
 import { ResultMedia, type StagedMedia } from "../routines/resultMedia.ts";
 import { withBrief } from "../routines/resultBrief.ts";
 import { ATTACH_RESULT_TOOL } from "../tools/attachResult.ts";
-import { postOutbox as sealToOutbox } from "../outbox/cloudOutbox.ts";
+import { postOutbox as sealToOutbox, type OutboxSource } from "../outbox/cloudOutbox.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
 import { serializeBuild } from "./buildLock.ts";
@@ -68,6 +68,8 @@ import { isHosted, publishRelayPub, webEnabled, mediaEnabled } from "../config/h
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
 import { MEDIA_TOOL_NAMES } from "../tools/media.ts";
 import { COMPOSE_TOOL_NAMES } from "../tools/videoCompose.ts";
+import { BILLED_MEDIA_TOOLS } from "../permissions/classify.ts";
+import { grantChildSpend } from "../permissions/childSpend.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
 // write/edit/bash, so a routine firing with nobody watching can't mutate the
@@ -130,6 +132,11 @@ const GATE_TIMEOUT_MS = 5 * 60_000;
 const WARM_TIMEOUT_MS = Number(process.env.PRIVATEER_MCP_WARM_MS) || 30_000;
 const WARM_POLL_MS = 250;
 
+// Distinguishes concurrent runs in the child-spend registry. A counter rather than a
+// timestamp: two runs starting in the same millisecond would share a key, and the second
+// to finish would release a grant the first still holds.
+let runSeq = 0;
+
 interface HarborConfig {
   defaultModel: string;
   webhooks?: Record<string, { url: string; secret?: string; headers?: Record<string, string> }>;
@@ -212,6 +219,22 @@ function formatWorkflowResult(name: string, result: { status: string; output: Re
   return `${head}${body}${reason}`.trimEnd() + "\n";
 }
 
+// What a routine ASKED for, sealed into the outbox envelope beside what it answered.
+//
+// The app can then act on a finished run — "now do X with this" — with the routine's
+// own standing instruction and working directory in hand, instead of guessing from a
+// summary. The routine never leaves this machine except inside the sealed blob (the
+// server holds ciphertext), and cloudOutbox clips every field.
+function routineSource(routine: Routine): OutboxSource {
+  return {
+    routineId: routine.id,
+    prompt: routine.prompt,
+    cwd: routine.cwd,
+    model: routine.model,
+    schedule: routine.cron ?? routine.at,
+  };
+}
+
 // Canonical control-envelope args for a task_submit / task_spawn signature. MUST match
 // the app's signer (client/services/accountSign.ts) byte-for-byte: the SAME key set with
 // undefined → null, so the recursive-key-sorted JSON both sides sign is identical. A
@@ -292,12 +315,13 @@ export class Harbor {
 
   private readonly pushCloud: CloudPusher = async (routine, content, status, media = []) => {
     const at = new Date().toISOString();
-    if (await this.postOutbox(routine.name, at, status, content, "routine", media)) return "sent";
+    const source = routineSource(routine);
+    if (await this.postOutbox(routine.name, at, status, content, "routine", media, source)) return "sent";
     // The queued copy keeps the attachment RECORDS, not the bytes: the files are
     // still on this disk, so a flush hours later re-reads them (and says so in the
     // body for any that have since gone). Buffering megabytes into a JSON queue
     // would be the same content twice, on a box that already has it.
-    addPendingCloud({ routine: routine.name, at, status, content, ...(media.length ? { media } : {}) });
+    addPendingCloud({ routine: routine.name, at, status, content, source, ...(media.length ? { media } : {}) });
     return "queued";
   };
 
@@ -594,8 +618,9 @@ export class Harbor {
     content: string,
     kind: OutboxKind = "routine",
     media: StagedMedia[] = [],
+    source?: OutboxSource,
   ): Promise<boolean> {
-    return sealToOutbox(name, at, status, content, kind, media);
+    return sealToOutbox(name, at, status, content, kind, media, source);
   }
 
   private async flushPendingCloud(): Promise<void> {
@@ -606,7 +631,7 @@ export class Harbor {
     for (const p of queue) {
       if (
         remaining.length === 0 &&
-        (await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? []))
+        (await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? [], p.source))
       ) continue;
       remaining.push(p);
     }
@@ -771,8 +796,14 @@ export class Harbor {
   // activation, so the build is serialized (serializeBuild) and the previous value is
   // restored. "__none__" is its sentinel for "register none": an unattended run with
   // no connector selectors gets no direct tools, whatever a shared mcp.json says.
-  private buildSessionServices(cwd: string, directTools: string[], media?: ResultMedia): Promise<any> {
+  private buildSessionServices(
+    cwd: string,
+    directTools: string[],
+    media?: ResultMedia,
+    spendGrant: readonly string[] = [],
+  ): Promise<any> {
     return serializeBuild(async () => {
+      const granted = new Set(spendGrant);
       const gate: GateController = {
         getMode: () => "bypass",
         setMode: () => {},
@@ -783,6 +814,14 @@ export class Harbor {
         async localAsk() {
           return "deny";
         },
+        // The billing media tools THIS run was granted. Without this the run below is a
+        // contradiction: a routine may name generate_video (naming it is the operator's
+        // decision — see MEDIA_GEN_TOOLS above), the tool registers, and then every call
+        // is denied, because `alwaysAsk` outranks bypass and localAsk has nobody to ask.
+        // Scoped to this session's gate rather than a process-wide switch, so two
+        // concurrent runs can hold different grants. The gate still refuses to let a
+        // grant cover a call that leaves cwd or reads a protected file.
+        isSpendPreauthorized: (req) => granted.has(req.tool),
       };
       // Every extension this session gets, in the one canonical order — including the MCP
       // adapter (Phase 5), the web/media capability shaping, and the filter that ignores
@@ -927,8 +966,14 @@ export class Harbor {
     // is going to the user's own mailbox, which `delivery: cloud` already chose.
     const allowedTools = spec.media ? [...resolved.tools, ATTACH_RESULT_TOOL] : resolved.tools;
     const { directToolsEnv, notes } = resolved;
+    // The billing tools this run may use: the ones its own allow-list names, and no
+    // others. Authorizes the run's own calls (the gate, below) and its subagents' —
+    // children are a separate process and read the grant from the environment, released
+    // in the finally so it can never outlive the run that holds it.
+    const spendGrant = allowedTools.filter((t) => BILLED_MEDIA_TOOLS.has(t));
+    const releaseChildSpend = grantChildSpend(`run:${++runSeq}`, spendGrant);
     try {
-      const services = await this.buildSessionServices(spec.cwd, directToolsEnv, spec.media);
+      const services = await this.buildSessionServices(spec.cwd, directToolsEnv, spec.media, spendGrant);
 
       const { provider, modelId } = parseSpec(spec.model);
       if (provider === "privateer") {
@@ -978,6 +1023,9 @@ export class Harbor {
         // and its entry must survive a harbor run's teardown (see providers/account.ts).
         try { await dropPersistedAccountCredential(); } catch { /* nothing persisted */ }
       }
+      // Drop this run's child grant. Unconditional and last: a grant left behind would
+      // authorize the NEXT run's subagents for tools that run never named.
+      releaseChildSpend();
     }
     return { out, status, error, notes };
   }
@@ -1014,10 +1062,13 @@ export class Harbor {
       const content = redactText(formatTaskResult(title, out, status, error, modelSpec, notes), collectSecrets(config.providers));
       const at = new Date().toISOString();
       const staged = media.list();
+      // What was asked, carried with what came back — a submitted task is followed up
+      // on exactly like a routine run (the app's Inbox is the only place either is read).
+      const source: OutboxSource = { prompt: spec.prompt, cwd, model: modelSpec };
       // Durable delivery: seal to the outbox. If we can't seal yet (no verified pubkey /
       // offline), queue it with kind:"task" so the flush re-seals it correctly later.
-      const sealed = await this.postOutbox(title, at, status, content, "task", staged);
-      if (!sealed) addPendingCloud({ routine: title, at, status, content, kind: "task", ...(staged.length ? { media: staged } : {}) });
+      const sealed = await this.postOutbox(title, at, status, content, "task", staged, source);
+      if (!sealed) addPendingCloud({ routine: title, at, status, content, kind: "task", source, ...(staged.length ? { media: staged } : {}) });
       // Live mirror if a controller is attached (the outbox copy is the source of truth).
       if (this.controllerAttached) this.relay?.sendTaskResult(title, content);
       log(`  task "${title}" ${status}; ${sealed ? "sealed to outbox" : "queued for outbox"}`);
@@ -1046,8 +1097,11 @@ export class Harbor {
             void (async () => {
               const at = new Date().toISOString();
               const body = redactText(content, collectSecrets(loadHarborConfig().providers));
-              if (!(await this.postOutbox(title, at, status, body, "task"))) {
-                addPendingCloud({ routine: title, at, status, content: body, kind: "task" });
+              // An empty-prompt spawn (a bare agent to drive) packs to no source at all
+              // — cloudOutbox drops it rather than shipping an empty object.
+              const source: OutboxSource = { prompt: spec.prompt, cwd: spec.cwd, model: spec.model };
+              if (!(await this.postOutbox(title, at, status, body, "task", [], source))) {
+                addPendingCloud({ routine: title, at, status, content: body, kind: "task", source });
               }
             })();
           },