privateer-agent 0.12.12 → 0.12.14

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

@@ -14,12 +14,12 @@
     { "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" },
-    { "name": "rpiv-web-tools", "dep": ["@juicesharp/rpiv-web-tools", "index.ts"], "note": "private web tools (user's own provider key)" },
+    { "name": "privateer-web", "entry": "extensions/privateer-web.ts", "note": "web_search/web_fetch — account search when signed in, else the user's own provider (rpiv-web-tools)" },
     { "name": "rpiv-ask-user-question", "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "note": "ask_user_question" },
     { "name": "pi-mcp-adapter", "dep": ["pi-mcp-adapter", "index.ts"], "note": "MCP servers as first-class tools" },
     { "name": "pi-subagents", "dep": ["pi-subagents", "src", "extension", "index.ts"], "note": "bounded parallel sub-agents" }
   ],
-  "retired": ["pi-privacy", "pi-web-access", "pi-hypa"],
+  "retired": ["pi-privacy", "pi-web-access", "pi-hypa", "rpiv-web-tools"],
   "reservedAliases": [
     "@juicesharp/rpiv-web-tools",
     "@juicesharp/rpiv-ask-user-question"

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 });
               }
             })();
           },

package/src/outbox/cloudOutbox.ts

@@ -68,6 +68,62 @@ export interface OutboxMedia {
   blobId?: string;
 }
 
+/**
+ * What the run was ASKED to do, carried beside what it answered.
+ *
+ * A result on its own is a dead end: the app can show it, read it aloud and file
+ * it, but "now book the top one" needs the standing instruction the run was given,
+ * and the directory it ran in, or the follow-up starts from a summary with no idea
+ * what produced it. That context is the routine — it lives on this machine and the
+ * app has never seen it — so it rides inside the SEALED envelope (the server holds
+ * ciphertext either way, exactly like `origin`).
+ *
+ * Every field is optional and clipped: this travels on every result, and a routine
+ * prompt can be arbitrarily long. Absent → the app falls back to the result body
+ * alone, which is what results from older CLIs carry.
+ */
+export interface OutboxSource {
+  /** The saved routine's id, when one produced this. Absent for ad-hoc tasks. */
+  routineId?: string;
+  /** The instruction the run was given (a routine's `prompt`, a task's spec). */
+  prompt?: string;
+  /** Where the run executed — a follow-up belongs in the same directory. */
+  cwd?: string;
+  /** The "provider:model" the run resolved to. */
+  model?: string;
+  /** The trigger verbatim: a cron expression, or a one-off ISO datetime. */
+  schedule?: string;
+}
+
+/** Clip bounds for `source`. The prompt is the only field that can be long. */
+export const MAX_SOURCE_PROMPT = 2_000;
+const SOURCE_FIELD_CAPS: Record<keyof OutboxSource, number> = {
+  routineId: 200,
+  prompt: MAX_SOURCE_PROMPT,
+  cwd: 500,
+  model: 200,
+  schedule: 100,
+};
+
+/**
+ * Normalize a source for the envelope: trim, clip, drop empties — and return
+ * undefined when nothing survives, so a workflow (or an empty-prompt live spawn)
+ * doesn't ship an empty object and bump the envelope version for nothing.
+ * Exported for the round-trip test.
+ */
+export function packSource(source?: OutboxSource): OutboxSource | undefined {
+  if (!source) return undefined;
+  const out: OutboxSource = {};
+  for (const [key, cap] of Object.entries(SOURCE_FIELD_CAPS) as [keyof OutboxSource, number][]) {
+    const raw = source[key];
+    if (typeof raw !== "string") continue;
+    const value = raw.trim();
+    if (!value) continue;
+    out[key] = value.length > cap ? value.slice(0, cap) + "…" : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 let outboxPub: Uint8Array | undefined;
 let originCache: { id: string; label: string } | undefined;
 
@@ -216,6 +272,9 @@ function undeliveredNote(names: string[]): string {
  * BEFORE the message, so a message that lands always references bytes that exist;
  * if the message then fails, the blobs are dropped again and the caller's queued
  * retry re-uploads from the same paths on disk.
+ *
+ * `source` is what the run was asked to do (see OutboxSource) — the context a
+ * follow-up needs, sealed alongside the answer.
  */
 export async function postOutbox(
   name: string,
@@ -224,20 +283,28 @@ export async function postOutbox(
   content: string,
   kind: OutboxKind = "routine",
   staged: StagedMedia[] = [],
+  source?: OutboxSource,
 ): Promise<boolean> {
   const pub = await ensureOutboxPub();
   if (!pub) return false;
   let body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
 
+  // Packed before the media budget is struck, because it spends the same envelope:
+  // attachments must not be sized against room the source has already taken.
+  const packedSource = packSource(source);
+  const sourceCost = packedSource ? JSON.stringify(packedSource).length : 0;
+
   const { media, blobIds, undelivered } = staged.length
-    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - 2_000)
+    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - sourceCost - 2_000)
     : { media: [] as OutboxMedia[], blobIds: [] as string[], undelivered: [] as string[] };
   body += undeliveredNote(undelivered);
 
-  // v2 adds `media`. Older apps ignore the field and still render the body, which is
-  // why the note above names undelivered files in prose rather than only in metadata.
+  // v2 adds `media`, v3 `source`. Both are additive: an older app ignores the field
+  // and still renders the body, which is why the note above names undelivered files
+  // in prose rather than only in metadata, and why a follow-up degrades to "the
+  // result text alone" rather than failing when `source` is missing.
   const envelope: Record<string, unknown> = {
-    v: media.length > 0 ? 2 : 1,
+    v: packedSource ? 3 : media.length > 0 ? 2 : 1,
     kind,
     name,
     status,
@@ -245,6 +312,7 @@ export async function postOutbox(
     content: body,
     origin: machineOrigin(),
     ...(media.length > 0 ? { media } : {}),
+    ...(packedSource ? { source: packedSource } : {}),
   };
 
   let sealed = sealJson(pub, envelope);