privateer-agent 0.12.15 → 0.12.16

package/README.md

@@ -296,6 +296,20 @@ skipped entirely on an attested TEE or on-device channel, which provably can't r
 prompt anyway. It's best-effort structured-PII detection, labeled as such — a safety net, not
 a guarantee.
 
+Pattern detection fires on anything email-*shaped*, so some of what it finds isn't personal
+data at all. **`/privacy allow <value>`** is where you say so — an address
+(`me@acme.com`), a domain (`@acme.com`), an IPv4 block (`10.0.0.0/8`), or any exact or
+globbed value. Entries live in `privacy.piiAllow` in `~/.privateer/config.json`, apply from
+the next turn (no relaunch), and persist across sessions; `/privacy` on its own lists them
+and `/privacy unallow <value>` puts one back under the gate. Reserved shapes —
+`example.com`, loopback, `noreply@…`, `@users.noreply.github.com` — are allowed out of the
+box. `PI_PRIVACY_*` env vars and a `pi-privacy.config.json` are honoured too (a
+project-local file can only ever make the gate *stricter*).
+
+Under **no quarter** the gate doesn't ask — there's nobody to ask — so it redacts and sends,
+and prints what it masked. That's the one case where a false positive changes what the model
+sees without you seeing it first, which is why the notice tells you `/privacy allow` exists.
+
 ## Privateer account (billed inference)
 
 Instead of bringing your own key, run **`/signin`** to sign into a Privateer account. Your

package/extensions/privateer-gate.ts

@@ -21,6 +21,7 @@ import {
 } from "../src/remote/subagentRelay.ts";
 import { RelayClient } from "../src/remote/relayClient.ts";
 import { makeSendFileTool } from "../src/tools/sendFile.ts";
+import { makeSaveCargoTool } from "../src/tools/cargo.ts";
 import { makeSaveAttachmentTool } from "../src/tools/saveAttachment.ts";
 import { AttachmentStore, type StoredAttachment } from "../src/util/attachmentStore.ts";
 import { makeExtensionsControl } from "../src/remote/extensionsControl.ts";
@@ -474,6 +475,11 @@ export default function privateerControl(pi: any): void {
   // driving. The daemon no longer loads this file, so there is nothing to shadow.
   pi.registerTool?.(makeSendFileTool(bridge));
   pi.registerTool?.(makeSaveAttachmentTool(attachments));
+  // save_cargo belongs with them: it is the same bridge, the same "needs a connected
+  // app" precondition, and the same failure mode if it were registered anywhere the
+  // relay isn't this file's. Unlike the pair it hands the app PLAINTEXT to encrypt —
+  // the terminal has no master key, so the round trip is the feature (cargoSave.ts).
+  pi.registerTool?.(makeSaveCargoTool(bridge));
 
   // Subagents (and print/rpc) run as headless child `pi` processes with no UI. There
   // no one can approve, so a "default" gate would fail-closed on every tool and the

package/extensions/privateer-privacy.ts

@@ -23,9 +23,8 @@
 // win regardless of the order pi discovers extensions in. This is purely a
 // display/resolution + routing list — posture and attestation are dispatcher-bound and
 // unaffected by the model set.
-import { makePiPrivacyExtension } from "pi-privacy";
 import { registerAccountModels } from "../src/providers/account.ts";
-import { sharedPrivacyOptions } from "../src/config/privacyPolicy.ts";
+import { privacyExtension } from "../src/config/privacyPolicy.ts";
 
 // Tinfoil's live chat models (inference.tinfoil.sh/v1/models), kimi-k2-6 first — the
 // launcher's default. Non-chat endpoints (embeddings, tts, whisper, websearch,
@@ -55,9 +54,10 @@ function tinfoilModel(id: string) {
 
 // One configuration, shared with the factory-built copy in src/config/moat.ts — the tier
 // resolver for the private ACCOUNT channel, the unattended/no-quarter handling, the ingest
-// policy. Adding an option HERE rather than there is how this file and the moat drifted
-// twice; src/config/privacyPolicy.ts records what that cost.
-const privacy = makePiPrivacyExtension(sharedPrivacyOptions());
+// policy, the operator's PII allowlist and the `/privacy` command that maintains it.
+// Adding an option HERE rather than there is how this file and the moat drifted twice;
+// src/config/privacyPolicy.ts records what that cost.
+const privacy = privacyExtension();
 
 export default function privateerPrivacy(pi: any): void {
   privacy(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.15",
+  "version": "0.12.16",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",
@@ -81,7 +81,7 @@
     "@zed-industries/agent-client-protocol": "0.4.5",
     "patch-package": "8.0.1",
     "pi-mcp-adapter": "2.11.0",
-    "pi-privacy": "0.11.0",
+    "pi-privacy": "0.13.0",
     "pi-subagents": "0.34.0",
     "picomatch": "4.0.5",
     "privateer-speak": "0.2.2",

package/src/cli/chat.ts

@@ -14,6 +14,7 @@ import { cliPalette } from "../ui/palette.ts"; // no Pi deps → safe pre-boot
 import { noQuarterActive, setNoQuarter } from "../permissions/noQuarter.ts"; // no Pi deps → safe pre-boot
 import type { GateController } from "../ext/permissionGate.ts"; // type-only → erased, safe pre-boot
 import { createUIContext } from "../ext/headlessUi.ts"; // no Pi deps → safe pre-boot
+import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts"; // node:child_process only → safe pre-boot
 
 // This lean REPL has no Pi TUI (and so no Theme), so it detects the terminal background
 // itself (COLORFGBG) and picks a palette — on a light terminal the standard "\x1b[33m"
@@ -47,6 +48,7 @@ async function main() {
     persistAccountCredential,
     dropPersistedAccountCredential,
     ensureAccountArmed,
+    verificationLink,
   } = await import("../providers/account.ts");
   const { modelRegistryOf } = await import("../providers/piAuthStore.ts");
   const { agentVersion } = await import("../config/version.ts");
@@ -637,9 +639,24 @@ async function main() {
     try {
       const user = await priv.runDeviceLogin({
         onCode: (code: any) => {
-          console.log(`\n${CYAN}Approve this terminal in the Privateer app:${RESET}`);
-          console.log(`  code: ${YELLOW}${code.user_code}${RESET}`);
-          if (code.verification_uri_complete) console.log(`  or open: ${DIM}${code.verification_uri_complete}${RESET}`);
+          // Browser-first, the same deal the TUI's /login widget makes: the URL carries
+          // the code, so the page lands straight on Authorize and the user clicks
+          // rather than types. verificationLink makes the server's scheme-less value
+          // absolute; canOpenBrowser decides the wording SYNCHRONOUSLY (SSH or a
+          // headless box keeps the old app-approve copy, because a launcher there
+          // would open on the wrong machine); and the link is printed either way, so
+          // an open that silently fails costs nothing.
+          const uri = verificationLink(code.verification_uri_complete ?? code.verification_uri);
+          const opening = Boolean(uri) && canOpenBrowser();
+          if (opening) void openInBrowser(uri);
+          console.log(
+            opening
+              ? `\n${CYAN}Authorize this terminal in the browser window that just opened:${RESET}`
+              : `\n${CYAN}Approve this terminal in the Privateer app:${RESET}`,
+          );
+          const match = opening ? `${DIM} — check it matches the one in your browser${RESET}` : "";
+          console.log(`  code: ${YELLOW}${code.user_code}${RESET}${match}`);
+          if (uri) console.log(`  ${opening ? "no browser? open" : "or open"}: ${DIM}${uri}${RESET}`);
           console.log(`${DIM}  waiting for approval…${RESET}`);
         },
       });

package/src/config/moat.ts

@@ -34,6 +34,7 @@ import { basename } from "node:path";
 import { managedNames } from "./moatManifest.ts";
 import type { GateController } from "../ext/permissionGate.ts";
 import type { SendFileBridge } from "../tools/sendFile.ts";
+import type { CargoSaveBridge } from "../tools/cargo.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
 /** A Pi extension factory, as DefaultResourceLoader takes them. */
@@ -61,7 +62,7 @@ export interface MoatOptions {
    * its module-level bridge and stands them down inside the daemon, so a live spawn's own
    * pair is what the model gets (see tools/relayFileTools.ts).
    */
-  relayFiles?: { bridge: SendFileBridge; attachments: AttachmentStore };
+  relayFiles?: { bridge: SendFileBridge & CargoSaveBridge; attachments: AttachmentStore };
   /**
    * THIS run's inbox-attachment staging area (routines/resultMedia.ts). Passed only by
    * a path whose result reaches the app's Inbox — a scheduled routine, a submitted
@@ -176,17 +177,16 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
   if (!caps) throw new Error(`buildMoat: unknown kind "${opts.kind}"`);
 
   const { makePermissionGate } = await import("../ext/permissionGate.ts");
-  const { makePiPrivacyExtension } = await import("pi-privacy");
   const { makeAccountProvider } = await import("../providers/account.ts");
   const { webEnabled, mediaEnabled } = await import("./hosted.ts");
-  const { sharedPrivacyOptions } = await import("./privacyPolicy.ts");
+  const { privacyExtension } = await import("./privacyPolicy.ts");
 
   const factories: ExtensionFactory[] = [makePermissionGate(opts.gate)];
 
   // 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(privacyExtension());
   factories.push(makeAccountProvider()); // must follow pi-privacy — see header
 
   if (opts.relayFiles) {

package/src/config/piiAllow.ts

@@ -0,0 +1,117 @@
+// The PII allowlist the OPERATOR controls — "that string is not personal data, stop
+// masking it."
+//
+// WHY THIS EXISTS. pi-privacy's detection is pattern-based and honest about it: it fires
+// on anything email-SHAPED or address-SHAPED. It refuses the shapes that are impossible
+// for a type (see its precision guards), but plenty of real-world strings are genuinely
+// ambiguous — a bare `8.0.0.0` is a version quad AND a valid address, an internal
+// hostname list is a list of addresses, a fixture mailbox is an address nobody reads. For
+// those the only correct answer comes from the person, and until now Privateer gave them
+// nowhere to put it: sharedPrivacyOptions() hand-built pi-privacy's options and never
+// called its config loader, so `PI_PRIVACY_PII_ALLOW` and pi-privacy.config.json were
+// silently ignored in every Privateer session. The only lever was "Send + remember for
+// session", which is all-or-nothing and forgotten at exit.
+//
+// This matters more since the gate learned to answer itself: under no quarter the
+// question is swallowed and the payload is auto-redacted, so a false positive is no
+// longer a prompt you dismiss — it is a silent rewrite the model then reads.
+//
+// WHERE IT LIVES. `privacy.piiAllow` in ~/.privateer/config.json (the same file the
+// harbor, channels and webhooks read). Entry forms are pi-privacy's — `me@acme.com`
+// (exact, `*` globs), `@acme.com` (that domain and its subdomains), `10.0.0.0/8` (an
+// IPv4 block), or any exact/globbed value.
+//
+// LIVE, NOT LATCHED. entries() is handed to pi-privacy as a function, so `/privacy allow
+// …` applies on the next turn instead of the next launch. It is called once per matched
+// value during a scan, so it must stay cheap: the JSON is re-parsed only when the file
+// changes (stamp = mtime + size), which leaves a stat per call and nothing else. An edit
+// made in an editor is picked up on the next scan, exactly like one made through the
+// command — there is no "restart to apply" step to explain.
+
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { configPath } from "./paths.ts";
+
+let cached: string[] = [];
+let cachedStamp = "";
+
+function parse(raw: unknown): string[] {
+  const list = (raw as any)?.privacy?.piiAllow;
+  if (!Array.isArray(list)) return [];
+  return list.filter((e): e is string => typeof e === "string" && e.trim() !== "").map((e) => e.trim());
+}
+
+/**
+ * The operator's allowlist, live. Missing file, unreadable file and malformed JSON all
+ * mean "no entries" — a config typo must not take the PII gate down with it, and the
+ * gate erring toward MORE detection is the safe direction.
+ */
+export function piiAllowEntries(): readonly string[] {
+  try {
+    const st = statSync(configPath());
+    const stamp = `${st.mtimeMs}:${st.size}`;
+    if (stamp === cachedStamp) return cached;
+    cachedStamp = stamp;
+    cached = parse(JSON.parse(readFileSync(configPath(), "utf8")));
+  } catch {
+    cachedStamp = "";
+    cached = [];
+  }
+  return cached;
+}
+
+/** Drop the cache — after our own write, so the stamp is never mistaken for unchanged. */
+function invalidate(): void {
+  cachedStamp = "";
+}
+
+// A bare `*` allows every value of every type: that is `piiPolicy: off` wearing a
+// different hat, and pi-privacy refuses it at compile time anyway. Refusing it HERE means
+// the person who typed it is told, rather than watching an entry land in their config and
+// do nothing.
+function invalidReason(entry: string): string | undefined {
+  if (!entry) return "an empty entry matches nothing";
+  if (/^\*+$/.test(entry)) return "a bare `*` would allowlist everything — turn the gate off explicitly if that's what you mean";
+  return undefined;
+}
+
+export interface AllowEdit {
+  ok: boolean;
+  /** Why it was refused, or what already stood. Always safe to show the user. */
+  message: string;
+  entries: readonly string[];
+}
+
+function write(entries: string[]): void {
+  let cfg: Record<string, unknown> = {};
+  try {
+    cfg = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    /* new or unreadable — a fresh object, so one bad file doesn't lose the edit */
+  }
+  const privacy = { ...((cfg.privacy as Record<string, unknown>) ?? {}), piiAllow: entries };
+  writeFileSync(configPath(), JSON.stringify({ ...cfg, privacy }, null, 2) + "\n");
+  invalidate();
+}
+
+/** Add one entry. Idempotent — adding what's already there is reported, not duplicated. */
+export function addPiiAllow(raw: string): AllowEdit {
+  const entry = raw.trim();
+  const bad = invalidReason(entry);
+  if (bad) return { ok: false, message: bad, entries: piiAllowEntries() };
+  const entries = [...piiAllowEntries()];
+  if (entries.includes(entry)) return { ok: true, message: `${entry} is already allowlisted`, entries };
+  entries.push(entry);
+  write(entries);
+  return { ok: true, message: `${entry} is no longer treated as PII in this and future sessions`, entries };
+}
+
+/** Remove one entry, exactly as written. */
+export function removePiiAllow(raw: string): AllowEdit {
+  const entry = raw.trim();
+  const entries = [...piiAllowEntries()];
+  const i = entries.indexOf(entry);
+  if (i < 0) return { ok: false, message: `${entry || "(empty)"} is not in the allowlist`, entries };
+  entries.splice(i, 1);
+  write(entries);
+  return { ok: true, message: `${entry} is gated again`, entries };
+}

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

package/src/tools/cargo.ts

@@ -0,0 +1,181 @@
+// The `save_cargo` tool — save a file from disk into the user's Privateer app as
+// Cargo: a titled, runnable artifact they can open, edit, download and share
+// from any of their devices, not a path that only exists on this machine.
+//
+// The interesting part is not this file, it's why the save is a round trip
+// through the app at all — src/remote/cargoSave.ts has that (short version: the
+// terminal holds no master key, and a Cargo row is ciphertext). What matters
+// here is the shape that follows from it:
+//
+// TAKES A PATH, NOT CONTENT. An artifact runs to half a megabyte. Inlining that
+// into a tool call would spend the whole thing in tokens, twice — once when the
+// model writes it, once when the call is echoed back into context — to move
+// bytes that are already sitting on disk. So the model WRITES the file with its
+// ordinary file tools, looks at it, and passes the path. The same reason the
+// media tools all name an output path instead of returning bytes, and it makes
+// the two compose: generate_model writes a .glb, the model writes a viewer .html
+// that loads it, save_cargo puts the viewer in the user's pocket.
+//
+// REFUSES RATHER THAN GUESSES. A kind that doesn't match the content is an
+// artifact that opens broken, and the user finds out later, on their phone,
+// with no way to tell what went wrong. So an unmappable extension is an error
+// with the mappable ones named, and a kind that contradicts the extension
+// (`kind: 'sheet'` on a .html) is refused rather than quietly honoured.
+//
+// SAYS WHAT DID AND DIDN'T TRAVEL. Saving is the one media-adjacent thing here
+// that is genuinely end-to-end encrypted — the app encrypts before the POST and
+// the server stores ciphertext it cannot read — which is the exact opposite of
+// generation's posture (media.ts's header is blunt about that). A model that
+// can't tell the two apart will describe one with the other's guarantees, so the
+// description states this one plainly and the success line repeats it.
+
+import { Type } from "typebox";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, resolve } from "node:path";
+import {
+  CARGO_KINDS,
+  MAX_CARGO_BYTES,
+  isCargoKind,
+  isHtmlKind,
+  kindForExtension,
+  type CargoKind,
+  type CargoSaveRequest,
+  type CargoSaveResult,
+} from "../remote/cargoSave.ts";
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+/** The bridge surface this tool needs; RemoteBridge implements it. */
+export interface CargoSaveBridge {
+  saveCargoRemote(req: CargoSaveRequest, signal?: AbortSignal): Promise<CargoSaveResult>;
+}
+
+export const CARGO_TOOL_NAMES = ["save_cargo"] as const;
+
+/**
+ * Is `kind` a sane claim about a file called `ext`? An HTML kind needs an HTML
+ * file and vice versa; the source kinds have to match their own family. Checked
+ * because the failure is silent and late — the app stores whatever it is told
+ * and only shows the mismatch when the user opens the artifact.
+ */
+function kindMatchesExtension(kind: CargoKind, ext: string): boolean {
+  const implied = kindForExtension(ext);
+  if (!implied) return false;
+  // .html implies 'webpage', but slides and games are HTML documents too — the
+  // extension can't tell them apart and the model can, so any HTML kind is fine
+  // over an HTML file. The source kinds are exact.
+  if (isHtmlKind(kind)) return isHtmlKind(implied);
+  if (implied === "sheet") return kind === "sheet";
+  return implied === "md" && (kind === "md" || kind === "pdf" || kind === "docx");
+}
+
+export function makeSaveCargoTool(bridge: CargoSaveBridge) {
+  return {
+    name: "save_cargo",
+    label: "Save to Cargo",
+    description:
+      "Save a file from disk into the user's Privateer app as Cargo — a titled artifact they can open, " +
+      "preview, edit, download and share from any of their signed-in devices. Use when the user asks for " +
+      "something they want to KEEP or open away from this machine (a page, a slide deck, a playable game, " +
+      "a report, a spreadsheet), rather than a file that only exists in this working directory. " +
+      "Write the file first with your normal file tools and pass its path.\n" +
+      "Accepts .html/.htm (kind webpage, slides or game — one self-contained document, all CSS and JS " +
+      "inlined, since it opens with no network and no sibling files), .md (kind md, pdf or docx — the " +
+      "kind picks what Download produces) and .csv (kind sheet). Max 512 KB; other file types cannot be " +
+      "Cargo — use send_file_to_client to hand the user an image, video or PDF instead.\n" +
+      "Needs the Privateer app attached to this terminal: the app holds the key, and it encrypts the " +
+      "artifact on the device before storing it, so the content is never readable by the server. That is " +
+      "a stronger guarantee than the generate_* tools have — do not describe those the same way.",
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path of the file to save, relative to cwd or absolute (e.g. 'build/tower-defence.html').",
+      }),
+      kind: Type.Optional(
+        Type.String({
+          description:
+            "What the artifact IS, which decides its label and what Download produces. " +
+            "'webpage' | 'slides' | 'game' for an HTML document — pick the one that matches what you " +
+            "built, they are not interchangeable to the user. 'pdf' | 'docx' | 'md' for markdown source. " +
+            "'sheet' for CSV. Defaults from the file extension ('webpage' for .html), so set it whenever " +
+            "you built a deck or a game.",
+        }),
+      ),
+      title: Type.Optional(
+        Type.String({
+          description:
+            "Title shown in the app's Cargo list. Say what the thing is, the way the user would name it " +
+            "('Tower Defence', 'Q3 Expenses') — not the filename. Omitted → the app derives one from the content.",
+        }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { path: string; kind?: string; title?: string },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd?: string },
+    ) {
+      if (!params.path) return text("Error: path is required — say which file to save.");
+      const cwd = ctx?.cwd ?? process.cwd();
+      const target = isAbsolute(params.path) ? params.path : resolve(cwd, params.path);
+
+      if (!existsSync(target)) return text(`File not found: ${params.path}`);
+      const stat = statSync(target);
+      if (stat.isDirectory()) return text(`${params.path} is a directory — save a single file.`);
+      if (stat.size === 0) return text(`${params.path} is empty — nothing to save.`);
+      if (stat.size > MAX_CARGO_BYTES) {
+        return text(
+          `${params.path} is ${(stat.size / 1024).toFixed(0)} KB; a Cargo artifact caps at ${MAX_CARGO_BYTES / 1024} KB. ` +
+            `Trim it, or send it as a file with send_file_to_client instead.`,
+        );
+      }
+
+      const ext = extname(target);
+      const implied = kindForExtension(ext);
+      if (!implied) {
+        return text(
+          `${params.path} can't be Cargo: ${ext || "a file with no extension"} isn't an artifact format. ` +
+            `Cargo holds .html/.htm (a self-contained page, deck or game), .md, or .csv. ` +
+            `To put any other file on the user's device, use send_file_to_client.`,
+        );
+      }
+      const kind = params.kind ?? implied;
+      if (!isCargoKind(kind)) {
+        return text(`Unknown kind '${String(params.kind)}'. Valid kinds: ${CARGO_KINDS.join(", ")}.`);
+      }
+      if (!kindMatchesExtension(kind, ext)) {
+        return text(
+          `kind '${kind}' doesn't match ${ext} — the artifact would open broken in the app. ` +
+            `${ext} holds ${implied === "md" ? "markdown (kind md, pdf or docx)" : implied === "sheet" ? "CSV (kind sheet)" : "an HTML document (kind webpage, slides or game)"}. ` +
+            `Either drop the kind and let the extension decide, or write the content the kind actually needs.`,
+        );
+      }
+
+      // Read as UTF-8: every Cargo kind is text. A binary file that happened to be
+      // named .html would arrive as replacement characters rather than as an error,
+      // but it would also not be an artifact anyone could open, and the size/extension
+      // checks above are what actually keep that case out.
+      let content: string;
+      try {
+        content = readFileSync(target, "utf8");
+      } catch (e) {
+        return text(`Couldn't read ${params.path}: ${(e as Error).message}`);
+      }
+      if (!content.trim()) return text(`${params.path} has no content to save.`);
+
+      const res = await bridge.saveCargoRemote(
+        { content, kind, title: params.title?.trim() || undefined },
+        signal,
+      );
+
+      if (!res.ok) return text(`Couldn't save ${basename(target)} to Cargo: ${res.reason}`);
+      return text(
+        `Saved "${res.title}" to Cargo (${kind}, ${(stat.size / 1024).toFixed(0)} KB, ${res.storageType} storage, id ${res.cargoId}). ` +
+          `The user can open, edit, download and share it from Cargo in the Privateer app. ` +
+          `It was encrypted on their device before it was stored — the server holds only ciphertext.`,
+      );
+    },
+  };
+}

package/src/tools/relayFileTools.ts

@@ -13,11 +13,18 @@
 // moat is no longer discoverable (src/config/moat.ts), so there is only ever one pair.
 import { makeSendFileTool, type SendFileBridge } from "./sendFile.ts";
 import { makeSaveAttachmentTool } from "./saveAttachment.ts";
+import { makeSaveCargoTool, type CargoSaveBridge } from "./cargo.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
-export function makeRelayFileTools(bridge: SendFileBridge, attachments: AttachmentStore) {
+// save_cargo rides with the file pair rather than with the media tools, because it
+// shares their precondition and not media's: it needs a CONNECTED APP, not a signed-in
+// account. Registering it in the moat's media block would put it in every harbor and
+// channels session, where there is no controller and every call would fail — see
+// remote/cargoSave.ts on why unattended runs deliver an artifact a different way.
+export function makeRelayFileTools(bridge: SendFileBridge & CargoSaveBridge, attachments: AttachmentStore) {
   return function relayFileTools(pi: any): void {
     pi.registerTool?.(makeSendFileTool(bridge));
     pi.registerTool?.(makeSaveAttachmentTool(attachments));
+    pi.registerTool?.(makeSaveCargoTool(bridge));
   };
 }