privateer-agent 0.12.14 → 0.12.16

package/src/config/privacyPolicy.ts

@@ -29,7 +29,9 @@
 // buildMoat(), exactly as it does every other Pi-touching import. Extensions load late
 // and import it statically.
 
+import { loadConfig, makePiPrivacyExtension } from "pi-privacy";
 import { noQuarterActive } from "../permissions/noQuarter.ts";
+import { addPiiAllow, piiAllowEntries, removePiiAllow } from "./piiAllow.ts";
 import { cliPalette, detectScheme } from "../ui/palette.ts";
 import { accountPosture, privateerChannel } from "../providers/account.ts";
 import { hasCredentials } from "../auth/privateer.ts";
@@ -38,15 +40,32 @@ import { hasCredentials } from "../auth/privateer.ts";
 // 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.
+// The tail is the point as much as the color is: unattended, nobody was asked, so the
+// only way to disagree with the answer is to know where to say so. `/privacy allow …`
+// is that place, and a notice about a masked filename is exactly when you want to know
+// it exists.
 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}`;
+  return `${p.RED}⚑${p.RESET} ${p.CYAN}${body}${p.RESET} ${p.DIM}· /privacy allow <value> if it shouldn't be masked${p.RESET}`;
 }
 
 /** The pi-privacy options every Privateer session gets, whichever route built it. */
 export function sharedPrivacyOptions() {
+  // pi-privacy's OWN configuration — PI_PRIVACY_* env vars and a pi-privacy.config.json.
+  // We used to build the options object by hand and never call this, so every one of
+  // those settings was silently ignored in Privateer and nowhere else: a user who set
+  // PI_PRIVACY_PII_ALLOW watched it do nothing. Ambient settings go UNDER ours, so the
+  // knobs Privateer has a product reason to hold (the tier resolver, the unattended
+  // signal, the account badge) are still ours, while the ones that are a matter of taste
+  // (piiPolicy, badge sinks, the exfil/downgrade policies) become settable.
+  //
+  // Safe against a repo you just opened: a project-local pi-privacy.config.json is
+  // clamped by pi-privacy itself — it may not weaken a policy below the built-in floor,
+  // and may not add allowlist entries at all.
+  const ambient = loadConfig();
   return {
+    ...ambient,
     // 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
@@ -92,6 +111,64 @@ export function sharedPrivacyOptions() {
     // 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,
+    toolResultPolicy: ambient.toolResultPolicy ?? ("redact" as const),
+    // The operator's own "that is not personal data" list, read LIVE (see
+    // ./piiAllow.ts): `/privacy allow @acme.com` applies on the next turn, not the next
+    // launch. Ambient config entries come first — both lists are additive, since an
+    // allowlist can only ever remove detection and there is no sense in which one of
+    // them should silence the other.
+    piiAllow: () => [...(ambient.piiAllow ?? []), ...piiAllowEntries()],
+  };
+}
+
+// ── /privacy ─────────────────────────────────────────────────────────────────────────
+// The gate's escape hatch, at the point of complaint. Everything else about pi-privacy is
+// glanceable (the badge) or answerable in the moment (the prompt); the allowlist is the
+// only part that needs a place to live, and "edit ~/.privateer/config.json and relaunch"
+// is not a thing anyone does mid-task while the gate masks a filename in front of them.
+//
+// Registered from HERE rather than from the extension file, for the reason this module
+// exists at all: the factory-built sessions and the discovered extension must not drift.
+function registerPrivacyCommand(pi: any): void {
+  pi.registerCommand?.("privacy", {
+    description: "Values the PII gate must not treat as personal data: /privacy [allow <value> | unallow <value>]",
+    handler: (args: string, ctx: any) => {
+      const raw = String(args ?? "").trim();
+      const [verb, ...rest] = raw.split(/\s+/);
+      const value = rest.join(" ").trim();
+      const notify = (msg: string, level: "info" | "warning" = "info") => ctx?.ui?.notify?.(msg, level);
+
+      if (verb === "allow" || verb === "unallow") {
+        if (!value) return notify(`usage: /privacy ${verb} <value>`, "warning");
+        const r = verb === "allow" ? addPiiAllow(value) : removePiiAllow(value);
+        return notify(r.message, r.ok ? "info" : "warning");
+      }
+      if (verb) return notify(`unknown option "${verb}" — usage: /privacy [allow <value> | unallow <value>]`, "warning");
+
+      const mine = piiAllowEntries();
+      notify(
+        [
+          mine.length ? `PII allowlist (~/.privateer/config.json):\n  ${mine.join("\n  ")}` : "PII allowlist: empty",
+          "Reserved shapes (example.com, loopback, noreply@…) are allowed by default and not listed here.",
+          "Add one with /privacy allow <value> — an address (me@acme.com), a domain (@acme.com),",
+          "an IPv4 block (10.0.0.0/8), or any exact/globbed value.",
+        ].join("\n"),
+        "info",
+      );
+    },
+  });
+}
+
+/**
+ * The privacy half of the moat as ONE factory: pi-privacy configured the Privateer way,
+ * plus the `/privacy` command that maintains its allowlist. Both routes into pi-privacy
+ * (src/config/moat.ts and extensions/privateer-privacy.ts) use this, so neither can end
+ * up with the gate but not its escape hatch.
+ */
+export function privacyExtension() {
+  const privacy = makePiPrivacyExtension(sharedPrivacyOptions());
+  return function privateerPrivacyCore(pi: any): void {
+    privacy(pi);
+    registerPrivacyCommand(pi);
   };
 }

package/src/permissions/classify.ts

@@ -270,6 +270,44 @@ export function classifyToolCall(
     };
   }
 
+  // save_cargo (src/tools/cargo.ts) — hand an artifact to the connected app, which
+  // encrypts it and stores it in the user's Cargo.
+  //
+  // Left to the unknown-tool branch this is bash-kind: a "Run save_cargo" prompt over a
+  // JSON blob, and an outright DENY in plan/readonly. Denying it there is the wrong call
+  // twice over — it writes nothing on this machine, and "show me this on my phone" is a
+  // reasonable thing to ask for while planning.
+  //
+  // Classified as a WRITE even though no local file changes, because that is what it is
+  // from the user's side: a new, persistent thing in their account, against their storage
+  // quota. Not alwaysAsk — unlike the generate_* tools it spends no credit, and unlike an
+  // ordinary egress the destination is the user's OWN device, encrypted there before it
+  // is stored, so there is no third party to leak to and nothing irreversible to stop.
+  //
+  // `outside` is about the SOURCE. The content is read off disk and shipped off-machine,
+  // so `path: "~/Documents/notes.md"` discloses a file from outside the working directory
+  // — the same disclosure the media tools flag on their inputs, and the reason `outside`
+  // has to be set here: it forces a prompt even under acceptEdits, which would otherwise
+  // swallow the call as an ordinary in-scope write.
+  if (name === "save_cargo") {
+    const src = str(obj.path);
+    if (!src) return unknownTarget(toolName, "write");
+    const abs = resolveInCwd(scope.cwd, src);
+    const outside = isOutsideScope(scope, abs);
+    const protectedSrc = isProtectedPath(abs);
+    const kindNote = str(obj.kind) ? ` as ${str(obj.kind)}` : "";
+    const titleNote = str(obj.title) ? ` "${str(obj.title)}"` : "";
+    return {
+      tool: toolName,
+      kind: "write",
+      title: protectedSrc ? "Save a protected file to Cargo in the app" : "Save to Cargo in the Privateer app",
+      detail: `${outside || protectedSrc ? abs : src}${kindNote}${titleNote} → the app encrypts it and stores it in Cargo`,
+      protected: protectedSrc,
+      outside,
+      path: abs,
+    };
+  }
+
   // Media generation (src/tools/media.ts) and local composition (videoCompose.ts).
   //
   // Left to the unknown-tool branch at the bottom these classify as bash-kind, which

package/src/permissions/noQuarter.ts

@@ -5,38 +5,46 @@
 //
 // Two ways in, one state:
 //   1. `privateer --no-quarter` at launch → PRIVATEER_NO_QUARTER=1 (see
-//      bin/privateer-launch.mjs), which seeds `active` below.
+//      bin/privateer-launch.mjs), which is what the reader below sees.
 //   2. shift+tab in a live session → toggleNoQuarter(). This is the "step away from
 //      the keyboard" switch: flip it on and the agent runs to completion instead of
 //      stopping on the next approval prompt.
 //
-// Toggling MIRRORS the env var, because that's how the state reaches subagents: a
-// pi-subagents child is a `pi` subprocess that inherits this process's env and reads
-// PRIVATEER_NO_QUARTER in its own gate. Children spawned after a toggle therefore
-// match the parent; ones already running keep the posture they started with.
+// THE ENV VAR IS THE STORE, not a mirror of a module-level flag — and that is
+// load-bearing for two separate reasons:
+//
+//   • ACROSS PROCESSES: a pi-subagents child is a `pi` subprocess that inherits this
+//     process's env and reads PRIVATEER_NO_QUARTER in its own gate. Children spawned
+//     after a toggle therefore match the parent; ones already running keep the posture
+//     they started with.
+//   • ACROSS EXTENSIONS IN THIS PROCESS: Pi loads each extension with its OWN jiti
+//     instance and `moduleCache: false` (pi-coding-agent dist/core/extensions/loader.ts,
+//     loadExtensionModule), so every extension that imports this file gets a SEPARATE
+//     copy of it. A module-level `let` would be per-extension state: shift+tab in
+//     extensions/privateer-gate.ts flipped the gate's copy while the copy inside
+//     extensions/privateer-privacy.ts stayed false, so a no-quarter session still
+//     stopped the turn with pi-privacy's "PII detected — send as-is or redact?" prompt.
+//     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.
 //
 // IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere,
 // including boot-ordered entrypoints (see boot.ts's ORDERING CONTRACT).
 
 const ENV = "PRIVATEER_NO_QUARTER";
 
-// Seeded from the launch flag so `--no-quarter` and the toggle share one state.
-let active = process.env[ENV] === "1";
-
-/** True while the gate is fully lowered for this session. */
+/** True while the gate is fully lowered for this session. Read live, never cached. */
 export function noQuarterActive(): boolean {
-  return active;
+  return process.env[ENV] === "1";
 }
 
-/** Set the state (and mirror it to the env for future subagent children). Returns the new state. */
+/** 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 {
-  active = on;
   if (on) process.env[ENV] = "1";
   else delete process.env[ENV];
-  return active;
+  return on;
 }
 
 /** Flip the state. Returns the new state. */
 export function toggleNoQuarter(): boolean {
-  return setNoQuarter(!active);
+  return setNoQuarter(!noQuarterActive());
 }

package/src/providers/account.ts

@@ -63,6 +63,12 @@ const DEFAULT_MODELS = [
   // account catalog automatically; these seeds just make them resolve at launch).
   "moonshotai/kimi-k3",
   "z-ai/glm-5.2",
+  // Both verified 2026-08-19 against /endpoints/zdr and GET /api/models: ZDR-covered
+  // and servable. Same reason as the line above — the live catalog already carries
+  // them, this only closes the first-launch window where a saved default that isn't
+  // yet in the cache would fall through to a BYO provider.
+  "x-ai/grok-4.6",
+  "openai/gpt-5.6-luna",
 ];
 
 function seedModel(id: string) {

package/src/remote/cargoSave.ts

@@ -0,0 +1,105 @@
+// The wire contract for CLI → app Cargo saves, shared by the three modules that
+// have to agree on it: RelayClient (sends the frames), RemoteBridge (correlates
+// the reply), and the save_cargo tool (validates before either runs).
+//
+// WHY THE ROUND TRIP EXISTS AT ALL. A Cargo row is `encryptedContent` +
+// `encryptedMetadata` — AES-256-GCM, done on the device, under the account master
+// key. The server stores ciphertext and never decrypts (treeview CLAUDE.md §5).
+// The terminal deliberately holds no master key: the device-grant login mints a
+// session token and nothing else, and crypto/accountVerify.ts says so out loud —
+// "the terminal holds no master key and can't derive the real one itself". So a
+// CLI that POSTed /api/cargo by itself could only write a row nothing can open.
+//
+// The app can. It is already signed in, already holds the key, and already has
+// `saveCargo()` — the same function the chat's Save button and the file importer
+// call. So the CLI hands it plaintext over the relay the user already trusts to
+// carry their prompts and approvals, and the app does the encrypting. The master
+// key stays exactly where it was; the artifact takes the same path to storage a
+// model-authored one does. Nothing new reaches the server, and no new endpoint
+// exists.
+//
+// WHAT THAT COSTS. The app has to be attached. A harbor is headless by design and
+// there is no controller to ask, so save_cargo is not registered there — an
+// unattended run still delivers an artifact the way it always has, as a fence in
+// its Inbox result (routines/resultBrief.ts). Don't "fix" that by widening this.
+
+/** Cargo artifact kinds — mirrors client/utils/cargoKinds.ts CargoKind. */
+export const CARGO_KINDS = ["webpage", "slides", "game", "pdf", "docx", "md", "sheet"] as const;
+export type CargoKind = (typeof CARGO_KINDS)[number];
+
+export function isCargoKind(v: unknown): v is CargoKind {
+  return typeof v === "string" && (CARGO_KINDS as readonly string[]).includes(v);
+}
+
+/** Kinds whose stored content is a runnable HTML document. */
+const HTML_KINDS: readonly CargoKind[] = ["webpage", "slides", "game"];
+
+export const isHtmlKind = (k: CargoKind): boolean => HTML_KINDS.includes(k);
+
+// The artifact's `langs` metadata is deliberately NOT computed here. The app stamps it
+// at save time (RemoteDriveContext, the same expression fileImportService uses), because
+// it has to match what extractRunnableCode stamps for a model-authored artifact exactly —
+// and a second copy on this side of the wire is precisely the drift that would make a
+// terminal-authored artifact render differently from an identical one built in chat.
+
+/**
+ * The kind implied by a file extension, for when the caller didn't say. Only the
+ * unambiguous ones map: .html could be a page, a deck or a game and the model is
+ * the one that knows which, so it lands on 'webpage' and is told to say if it
+ * meant otherwise. Returns null when the extension isn't one Cargo can hold —
+ * the tool refuses rather than guessing, because a .png "saved as a webpage" is
+ * a broken artifact the user only discovers when they open it.
+ */
+export function kindForExtension(ext: string): CargoKind | null {
+  switch (ext.toLowerCase()) {
+    case ".html":
+    case ".htm":
+      return "webpage";
+    case ".md":
+    case ".markdown":
+      return "md";
+    case ".csv":
+      return "sheet";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Ceiling on the artifact source, matching the app's own MAX_DOC_BYTES
+ * (client/utils/extractRunnableCode.ts:46). An artifact arriving from the
+ * terminal lands in the same store and the same preview surfaces as a
+ * model-authored one, so anything the app would refuse from the model has to be
+ * refused here too — and refused HERE, where the message can name the file and
+ * its size, rather than as a save failure three frames later.
+ */
+export const MAX_CARGO_BYTES = 512 * 1024;
+
+/**
+ * Characters of artifact text per `cargo_chunk` frame. The relay caps a frame at
+ * 256 KB and an artifact may be twice that, so the content is chunked the same
+ * way sendFile chunks a file. Text, not base64: a Cargo artifact is HTML,
+ * markdown or CSV by definition, so there is nothing binary to encode and the
+ * 4/3 inflation would buy nothing. Splitting mid-surrogate is safe — JSON.stringify
+ * escapes a lone surrogate as \udXXX and JSON.parse restores it, so the halves
+ * rejoin into the original pair on the app side.
+ */
+export const CARGO_CHUNK_CHARS = 120_000;
+
+/** A CLI-initiated Cargo save, relayed to the app to encrypt and store. */
+export interface CargoSaveRequest {
+  /** Artifact source: an HTML document, markdown, or CSV per `kind`. */
+  content: string;
+  kind: CargoKind;
+  /** Title for the artifact. Omitted → the app derives one from the content. */
+  title?: string;
+}
+
+/**
+ * The app's answer. `ok: false` carries a reason written for a person — a locked
+ * vault, full cloud storage, a guest session — because the tool hands it
+ * straight to the model, and "save failed" is not something it can act on.
+ */
+export type CargoSaveResult =
+  | { ok: true; cargoId: string; title: string; storageType: string }
+  | { ok: false; reason: string };

package/src/remote/relayClient.ts

@@ -22,6 +22,7 @@ import { apiRequest, serverBaseUrl } from "../auth/privateer.ts";
 import { MOAT_SHIMS, reservedNames } from "../config/moatManifest.ts";
 import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
+import { CARGO_CHUNK_CHARS, type CargoSaveRequest, type CargoSaveResult } from "./cargoSave.ts";
 
 // Display label for THIS running terminal. Deliberately NON-PII: we do NOT send
 // username@hostname or the working-directory name to the server/controller (the
@@ -134,6 +135,13 @@ export interface RelayCallbacks {
   // The app answered a CLI-initiated text-input prompt (the id from requestInput).
   // A null value means the app dismissed the prompt without submitting.
   onInputResponse?: (id: string, value: string | null) => void;
+  // The app finished a CLI-initiated Cargo save (the id from requestCargoSave):
+  // it encrypted the artifact under the account master key and stored it, or
+  // refused. Optional so callbacks that predate the frame keep compiling — and a
+  // controller too old to understand cargo_begin simply never answers, which the
+  // bridge's bounded wait turns into a clean "this app can't save artifacts yet"
+  // rather than a wedged tool call.
+  onCargoSaved?: (id: string, result: CargoSaveResult) => void;
   // The app's composer is autocompleting an `@file` mention — reply with the cwd
   // files/dirs matching `query` (a sendFileMatches frame, keyed by the same id).
   // Read-only; resolution of the picked path still happens on the prompt turn.
@@ -667,6 +675,11 @@ export class RelayClient {
       query?: string;
       sig?: string;
       ts?: number;
+      // cargo_saved (the app's verdict on a save_cargo round trip)
+      ok?: boolean;
+      cargoId?: string;
+      storageType?: string;
+      reason?: string;
     };
     try {
       frame = JSON.parse(data.toString());
@@ -724,6 +737,24 @@ export class RelayClient {
       case "input_response":
         if (frame.id) this.cb.onInputResponse?.(frame.id, typeof frame.value === "string" ? frame.value : null);
         break;
+      // The app's verdict on a Cargo save we sent up. Everything is re-typed off
+      // the wire rather than trusted: the id keys a pending tool call, and the
+      // rest is quoted back to the model, so a malformed frame must degrade to a
+      // refusal with a reason instead of an `undefined` the tool prints.
+      case "cargo_saved": {
+        if (typeof frame.id !== "string" || !frame.id) break;
+        const result: CargoSaveResult =
+          frame.ok === true && typeof frame.cargoId === "string" && frame.cargoId
+            ? {
+                ok: true,
+                cargoId: frame.cargoId,
+                title: typeof frame.title === "string" ? frame.title : "",
+                storageType: frame.storageType === "local" ? "local" : "cloud",
+              }
+            : { ok: false, reason: typeof frame.reason === "string" && frame.reason ? frame.reason : "the app refused the save without giving a reason" };
+        this.cb.onCargoSaved?.(frame.id, result);
+        break;
+      }
       case "files_search":
         if (typeof frame.id === "string") this.cb.onFilesSearch?.(frame.id, typeof frame.query === "string" ? frame.query : "");
         break;
@@ -1358,6 +1389,34 @@ export class RelayClient {
     });
   }
 
+  // Ask the app to save an artifact as Cargo: it encrypts under the account
+  // master key (which this process does not have — see cargoSave.ts) and stores
+  // it, then answers with a cargo_saved keyed by `id`.
+  //
+  // Chunked like sendFile, and for the same reason: the relay caps a frame at
+  // 256 KB and an artifact may be 512 KB. Ordering is the WS's, so the app can
+  // reject a seq gap as a dropped transfer rather than silently storing a
+  // half-artifact.
+  //
+  // NOT run through `safe()`. That redacts secrets, and redaction inside an
+  // artifact is corruption — it would store a document with `[redacted]` where
+  // the model wrote an API shape, and the user would find out on Preview. Same
+  // call sendFile makes about its bytes; the tool decides what is safe to send.
+  requestCargoSave(id: string, req: CargoSaveRequest): void {
+    this.flushDeltas(); // land the save in order relative to buffered text
+    this.rawSend({
+      type: "cargo_begin",
+      id,
+      kind: req.kind,
+      title: req.title ? clip(req.title, 200) : undefined,
+      size: Buffer.byteLength(req.content, "utf8"),
+    });
+    for (let off = 0, seq = 0; off < req.content.length; off += CARGO_CHUNK_CHARS, seq++) {
+      this.rawSend({ type: "cargo_chunk", id, seq, data: req.content.slice(off, off + CARGO_CHUNK_CHARS) });
+    }
+    this.rawSend({ type: "cargo_end", id });
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/remote/remoteBridge.ts

@@ -15,12 +15,20 @@ import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
 import type { AskOutcome } from "../permissions/modeGate.ts";
 import type { RelayCallbacks } from "./relayClient.ts";
+import type { CargoSaveRequest, CargoSaveResult } from "./cargoSave.ts";
 
 // How much of a driven turn's reply we hold for possible outbox delivery. The
 // sealed item is capped at 45k plaintext anyway; this just stops a pathological
 // turn from growing the buffer without bound.
 const MAX_TURN_CAPTURE = 60_000;
 
+// How long the app gets to encrypt an artifact and store it before the save_cargo tool
+// gives up. Generous because the app end is a real round trip — encrypt, POST /api/cargo,
+// wait on the network — and a phone on a slow link is the normal case, not the edge one.
+// Read per call rather than at module load so a test can set it without re-importing the
+// module (and so the env is read in the process that actually runs the save).
+const cargoSaveTimeoutMs = (): number => Number(process.env.PRIVATEER_CARGO_TIMEOUT_MS) || 60_000;
+
 // The outbound surface the bridge needs; RelayClient implements all of it.
 export interface RelayLike {
   requestApproval(id: string, req: PermissionRequest): void;
@@ -39,6 +47,7 @@ export interface RelayLike {
   sendFileMatches(id: string, matches: { path: string; isDir: boolean }[]): void;
   sendExtensions(payload: ExtensionsPayload): void;
   sendSkills(payload: SkillsPayload): void;
+  requestCargoSave(id: string, req: CargoSaveRequest): void;
 }
 
 // The installed-extensions snapshot relayed to the app's extensions manager.
@@ -139,6 +148,7 @@ export class RemoteBridge {
   private readonly pending = new Map<string, (d: AskOutcome) => void>();
   private readonly pendingSelects = new Map<string, (v: string | null) => void>();
   private readonly pendingInputs = new Map<string, (v: string | null) => void>();
+  private readonly pendingCargo = new Map<string, (r: CargoSaveResult) => void>();
   private pendingAttachments: RemoteAttachment[] = [];
   // The driven turn in flight, kept only so it can be delivered to the outbox if it
   // turns out nobody was watching (see settleTurn). Bounded: the outbox truncates at
@@ -230,6 +240,10 @@ export class RemoteBridge {
       const resolve = this.pendingInputs.get(id);
       if (resolve) resolve(value);
     },
+    onCargoSaved: (id, result) => {
+      const resolve = this.pendingCargo.get(id);
+      if (resolve) resolve(result);
+    },
     onFilesSearch: (id, query) => this.cfg.onFilesSearch?.(id, query),
     onNoQuarter: (on) => {
       this.noQuarter = on;
@@ -402,6 +416,57 @@ export class RemoteBridge {
     return this.relay.sendFile(file);
   }
 
+  // Hand an artifact to the app to encrypt and store as Cargo (the save_cargo tool),
+  // and wait for its verdict. The app owns the master key; this process never has one,
+  // so this round trip IS the feature rather than a convenience — see cargoSave.ts.
+  //
+  // Three ways this ends without a stored artifact, each with its own message, because
+  // the model gets the reason verbatim and they call for different next moves:
+  //
+  //  - No controller. Unlike sendFile, "handed to an open socket" is not good enough
+  //    here: the caller is promised an artifact id, and with nobody attached the server
+  //    drops the frames and we would wait out the full timeout to learn it. hasController()
+  //    is checked up front so the failure is immediate and says what to do about it.
+  //  - The app answered a refusal (locked vault, storage full, guest session). Passed
+  //    through as written — those messages already exist for a person to read.
+  //  - Nothing came back inside the deadline. Nothing else wraps this in a timeout the
+  //    way the gate wraps remoteAsk, so a silent or too-old app would wedge the turn
+  //    forever without one.
+  saveCargoRemote = (req: CargoSaveRequest, signal?: AbortSignal): Promise<CargoSaveResult> => {
+    if (!this.relay) return Promise.resolve({ ok: false, reason: "remote access is not enabled — run /remote-access on and drive this terminal from the Privateer app" });
+    if (!this.relay.isConnected()) return Promise.resolve({ ok: false, reason: "the relay is not connected" });
+    // hasController is optional on RelayLike; a transport that can't tell is treated as
+    // attached, matching how the rest of the bridge reads it.
+    if (this.relay.hasController && !this.relay.hasController()) {
+      return Promise.resolve({ ok: false, reason: "the Privateer app is not attached to this terminal — only the app holds the key that encrypts an artifact, so open it and attach before saving" });
+    }
+    const id = randomUUID();
+    return new Promise<CargoSaveResult>((resolve) => {
+      const settle = (r: CargoSaveResult) => {
+        if (!this.pendingCargo.has(id)) return; // already settled (abort raced the reply)
+        this.pendingCargo.delete(id);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(r);
+      };
+      const onAbort = () => settle({ ok: false, reason: "the turn was interrupted before the app confirmed the save" });
+      const deadline = cargoSaveTimeoutMs();
+      const timer = setTimeout(
+        () => settle({ ok: false, reason: `the app did not answer within ${Math.round(deadline / 1000)}s — it may be an older version that cannot save artifacts from a terminal` }),
+        deadline,
+      );
+      // Don't hold the process open on this timer alone; an exiting CLI shouldn't
+      // linger for a save the app is never going to answer.
+      timer.unref?.();
+      this.pendingCargo.set(id, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      this.relay!.requestCargoSave(id, req);
+    });
+  };
+
   private rejectAllPending(): void {
     for (const resolve of this.pending.values()) resolve("deny");
     this.pending.clear();
@@ -411,5 +476,15 @@ export class RemoteBridge {
     // Same for a relayed text prompt: a gone controller resolves to "no input".
     for (const resolve of this.pendingInputs.values()) resolve(null);
     this.pendingInputs.clear();
+    // A save whose controller vanished mid-flight is NOT reported as failed-and-done:
+    // the app may have encrypted and stored the artifact before its socket dropped, and
+    // the frame carrying the id is what we lost. Saying "it didn't save" would send the
+    // model round again and leave the user with two copies of the same artifact, so the
+    // reason says plainly that the outcome is unknown and names Cargo as the place to
+    // look before retrying.
+    for (const resolve of this.pendingCargo.values()) {
+      resolve({ ok: false, reason: "the app disconnected before confirming the save — it may or may not have stored the artifact; check Cargo in the app before saving again" });
+    }
+    this.pendingCargo.clear();
   }
 }