privateer-agent 0.14.2 → 0.14.4

package/extensions/privateer-gate.ts

@@ -640,10 +640,10 @@ 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).
+  // save_cargo belongs with them: it tries this bridge's attached app first, which hands
+  // the app PLAINTEXT to encrypt — the terminal has no master key (cargoSave.ts). With no
+  // app attached (remote access off, or nobody driving) it queues the artifact sealed to
+  // the account instead, and the next app to open files it.
   pi.registerTool?.(makeSaveCargoTool(bridge));
   // The chart tools, for the same reasons and one more. Same: this bridge, the same
   // "needs a connected app" precondition, the same plaintext-out/app-encrypts round trip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "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",

package/src/auth/accountSessions.ts

@@ -21,21 +21,50 @@
 // RECYCLED pid makes a dead owner look alive, so we skip a reclaimable session and
 // spawn a fresh one — the old behaviour, no harm. The dangerous direction (a live
 // process reported dead) can't happen: a running pid never reports ESRCH.
+//
+// LAYOUT — one file per owning pid (`<pid>.json` in accountSessionsDir), and an orphan
+// is CLAIMED by renaming its file before anyone rotates it. This used to be a single
+// JSON file that every process read, modified and wrote back whole, and that was a real
+// outage under concurrency (an agent firing several `privateer -p` one-shots at once):
+//
+//   A reads {orphan: R}  ·  B reads {orphan: R}  ·  B adopts the orphan (R → R′) and
+//   writes it out  ·  A writes ITS stale copy back, orphan entry and all.
+//
+// The resurrected entry names a refresh token that was already rotated. The next launch
+// "reclaims" it, the server sees a spent token replayed past its 30s grace window, calls
+// it theft, and revokes the whole lineage — which is the session B (or whoever adopted
+// down the chain) is using right now, and possibly the one in the shared auth.json that
+// other running terminals read. They all 401 mid-run, and a one-shot run has no next
+// message to recover on, so the user is told to /login while signed in.
+//
+// Per-pid files mean no process ever writes another's entry, and rename is atomic on
+// every platform we ship on, so exactly one claimer wins an orphan and the rest get
+// ENOENT and move on. A claim whose claimant died is deleted rather than released: its
+// token may already have been rotated, and offering it again is the same hazard.
 
-import { existsSync, mkdirSync, readFileSync, rmSync, renameSync, writeFileSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
-import { accountSessionsPath, globalDir } from "../config/paths.ts";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { accountSessionsDir, accountSessionsPath, globalDir } from "../config/paths.ts";
 
-// One spawned session, keyed in the file by the pid of its owning terminal. `refresh`
-// is what lets a later launch adopt or revoke it; `expires` is its access token's exp
-// (see jwtExpMs), used only to prune entries that are dead server-side anyway.
+// One spawned session, keyed by the pid of its owning terminal. `refresh` is what lets
+// a later launch adopt or revoke it; `expires` is its access token's exp (see
+// jwtExpMs), used only to prune entries that are dead server-side anyway.
 export interface OwnedSession {
   pid: number;
   refresh: string;
   expires: number;
 }
 
-type Registry = Record<string, { refresh?: unknown; expires?: unknown }>;
+const ENTRY = /^(\d+)\.json$/;
+const CLAIM = /^(\d+)\.claim-(\d+)$/;
+
+function entryPath(pid: number): string {
+  return join(accountSessionsDir(), `${pid}.json`);
+}
+
+function claimPath(pid: number, claimant = process.pid): string {
+  return join(accountSessionsDir(), `${pid}.claim-${claimant}`);
+}
 
 function tryChmod(path: string, mode: number): void {
   try {
@@ -45,31 +74,21 @@ function tryChmod(path: string, mode: number): void {
   }
 }
 
-function readRegistry(): Registry {
-  const path = accountSessionsPath();
-  if (!existsSync(path)) return {};
+function tryRm(path: string): void {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Registry) : {};
+    rmSync(path, { force: true });
   } catch {
-    return {}; // corrupt/truncated — start clean rather than wedging every launch
+    /* already gone, or unremovable — nothing more to do */
   }
 }
 
-// Write via temp + rename so a concurrent reader never sees a half-written file. Two
-// terminals racing can still lose one entry (last writer wins); the cost is one
-// unreclaimable orphan, not a broken launch, so a lock file isn't worth it here.
-function writeRegistry(reg: Registry): void {
-  const path = accountSessionsPath();
+function readEntry(path: string, pid: number): OwnedSession | null {
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    tryChmod(globalDir(), 0o700);
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(reg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    tryChmod(tmp, 0o600);
-    renameSync(tmp, path);
+    const raw = JSON.parse(readFileSync(path, "utf8")) as { refresh?: unknown; expires?: unknown };
+    if (typeof raw?.refresh !== "string" || !raw.refresh) return null;
+    return { pid, refresh: raw.refresh, expires: typeof raw.expires === "number" ? raw.expires : 0 };
   } catch {
-    /* best effort — losing the registry costs reclamation, never correctness */
+    return null; // corrupt/truncated — treated as malformed and pruned
   }
 }
 
@@ -86,72 +105,109 @@ function isAlive(pid: number): boolean {
   }
 }
 
-function parseEntry(pid: string, raw: { refresh?: unknown; expires?: unknown }): OwnedSession | null {
-  const n = Number(pid);
-  if (!Number.isInteger(n) || typeof raw?.refresh !== "string" || !raw.refresh) return null;
-  return { pid: n, refresh: raw.refresh, expires: typeof raw.expires === "number" ? raw.expires : 0 };
-}
-
 // Claim (or re-claim) a session for THIS process. Called wherever the account
 // credential is minted or rotated — spawnAccountCredentials and
 // refreshAccountCredentials — so the registry always holds the token that would
-// actually work, including the rotations Pi drives on its own.
+// actually work, including the rotations Pi drives on its own. Written via temp +
+// rename so a concurrent reader never sees a half-written file.
 export function recordOwnedSession(cred: { refresh: string; expires: number }): void {
-  const reg = readRegistry();
-  reg[String(process.pid)] = { refresh: cred.refresh, expires: cred.expires };
-  writeRegistry(reg);
+  try {
+    mkdirSync(accountSessionsDir(), { recursive: true });
+    tryChmod(globalDir(), 0o700);
+    tryChmod(accountSessionsDir(), 0o700);
+    const path = entryPath(process.pid);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ refresh: cred.refresh, expires: cred.expires }) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    tryChmod(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch {
+    /* best effort — losing the registry costs reclamation, never correctness */
+  }
 }
 
 // Drop this process's entry — the session is being revoked (clean exit, /signout), so
 // it is about to stop existing server-side. Leaving it behind would advertise a dead
 // session as a reclaimable orphan to the next launch.
 export function forgetOwnedSession(): void {
-  const reg = readRegistry();
-  if (!(String(process.pid) in reg)) return;
-  delete reg[String(process.pid)];
-  writeRegistry(reg);
+  tryRm(entryPath(process.pid));
 }
 
-// Sessions whose owning terminal is gone: candidates to adopt or revoke. Prunes
-// entries that are unusable anyway (malformed, or past their expiry) as a side
-// effect, so the file can't grow without bound. Our own pid is never a candidate.
+// Sessions whose owning terminal is gone: candidates to adopt or revoke. Listing is NOT
+// claiming — call claimOrphan before rotating one. Prunes entries that are unusable
+// anyway (malformed, or past their expiry) and claims left by a dead claimant, so the
+// directory can't grow without bound. Our own pid is never a candidate.
 export function orphanedSessions(now = Date.now()): OwnedSession[] {
-  const reg = readRegistry();
+  let names: string[];
+  try {
+    names = readdirSync(accountSessionsDir());
+  } catch {
+    return []; // no registry yet
+  }
   const orphans: OwnedSession[] = [];
-  let pruned = false;
-
-  for (const [pid, raw] of Object.entries(reg)) {
-    const entry = parseEntry(pid, raw);
+  for (const name of names) {
+    const path = join(accountSessionsDir(), name);
+    const claim = CLAIM.exec(name);
+    if (claim) {
+      // Mid-adoption by a live process: theirs. Claimant died: its token may already
+      // be rotated, so it is junk — never put back up for reclamation.
+      if (!isAlive(Number(claim[2]))) tryRm(path);
+      continue;
+    }
+    const m = ENTRY.exec(name);
+    if (!m) continue; // a temp file mid-write, or something that isn't ours
+    const pid = Number(m[1]);
+    if (pid === process.pid || isAlive(pid)) continue; // ours, or a live terminal's
+    const entry = readEntry(path, pid);
     if (!entry || (entry.expires > 0 && entry.expires <= now)) {
-      delete reg[pid]; // malformed, or dead server-side — nothing to reclaim
-      pruned = true;
+      tryRm(path); // malformed, or dead server-side — nothing to reclaim
       continue;
     }
-    if (entry.pid === process.pid || isAlive(entry.pid)) continue; // ours, or a live terminal's
     orphans.push(entry);
   }
-
-  if (pruned) writeRegistry(reg);
   return orphans;
 }
 
+// Take an orphan for THIS process, atomically. True only for the one caller whose rename
+// landed; everyone else racing for the same orphan gets false and must leave it alone.
+// Pair with dropOwnedSession (handled) or releaseOrphan (couldn't reach the server).
+export function claimOrphan(pid: number): boolean {
+  try {
+    renameSync(entryPath(pid), claimPath(pid));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Put back an orphan we claimed but couldn't settle: its refresh never reached the
+// server, so the token is still the live one and the row is still worth reclaiming.
+export function releaseOrphan(pid: number): void {
+  try {
+    renameSync(claimPath(pid), entryPath(pid));
+  } catch {
+    tryRm(claimPath(pid));
+  }
+}
+
 // Forget one orphan, once it has been definitively handled (adopted, or confirmed dead
-// server-side). A entry whose refresh merely FAILED TO REACH the server is deliberately
-// kept: dropping it on a network blip would leak that row until its TTL.
+// server-side). An entry whose refresh merely FAILED TO REACH the server goes back via
+// releaseOrphan instead: dropping it on a network blip would leak that row until its TTL.
 export function dropOwnedSession(pid: number): void {
-  const reg = readRegistry();
-  if (!(String(pid) in reg)) return;
-  delete reg[String(pid)];
-  writeRegistry(reg);
+  tryRm(claimPath(pid));
+  if (pid !== process.pid) tryRm(entryPath(pid));
 }
 
 // Wipe the registry. Used by logout(), where the server has just revoked this
 // machine's whole token family: every entry now names a dead session, and leaving
 // them behind would offer the next login a list of orphans to "reclaim" that can
-// only fail. Also a test seam.
+// only fail. Also removes the legacy single-file registry. Also a test seam.
 export function clearOwnedSessions(): void {
+  tryRm(accountSessionsPath());
   try {
-    rmSync(accountSessionsPath(), { force: true });
+    if (existsSync(accountSessionsDir())) rmSync(accountSessionsDir(), { recursive: true, force: true });
   } catch {
     /* nothing to remove */
   }

package/src/auth/privateer.ts

@@ -20,6 +20,8 @@ import {
   recordOwnedSession,
   forgetOwnedSession,
   orphanedSessions,
+  claimOrphan,
+  releaseOrphan,
   dropOwnedSession,
   clearOwnedSessions,
 } from "./accountSessions.ts";
@@ -811,13 +813,17 @@ export async function acquireAccountCredential(): Promise<AccountCredential> {
 
   while (attempted < orphans.length && !adopted) {
     const orphan = orphans[attempted++];
+    // Another launch racing us may already have it. Rotating it anyway would replay a
+    // token that launch just spent — reuse detection, and its session revoked mid-run.
+    if (!claimOrphan(orphan.pid)) continue;
     try {
       adopted = await refreshAccountCredentials(orphan.refresh);
       dropOwnedSession(orphan.pid); // the rotation above re-recorded it under OUR pid
     } catch (e) {
-      // Refused → the session is gone; stop tracking it. Unreachable → keep it, so a
-      // network blip doesn't strand a live row we could have reclaimed next launch.
+      // Refused → the session is gone; stop tracking it. Unreachable → put it back, so
+      // a network blip doesn't strand a live row we could have reclaimed next launch.
       if (isRefreshRejection(e)) dropOwnedSession(orphan.pid);
+      else releaseOrphan(orphan.pid);
     }
   }
 
@@ -836,12 +842,14 @@ export async function acquireAccountCredential(): Promise<AccountCredential> {
 // overwrite the entry for the credential this terminal is actually using.
 async function revokeOrphanedSessions(orphans: OwnedSession[], timeoutMs = 1500): Promise<void> {
   for (const orphan of orphans) {
+    if (!claimOrphan(orphan.pid)) continue; // another launch got there first
     try {
       const cred = await rotateSession(orphan.refresh);
       await deleteSession(cred.access, timeoutMs);
       dropOwnedSession(orphan.pid);
     } catch (e) {
       if (isRefreshRejection(e)) dropOwnedSession(orphan.pid);
+      else releaseOrphan(orphan.pid);
     }
   }
 }

package/src/config/moat.ts

@@ -306,6 +306,18 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
   if (opts.relayFiles) {
     const { makeRelayFileTools } = await import("../tools/relayFileTools.ts");
     factories.push(makeRelayFileTools(opts.relayFiles.bridge, opts.relayFiles.attachments));
+  } else {
+    // No relay of its own — a harbor run, a channels or ACP session — so no app can ever
+    // be attached. save_cargo still exists here, QUEUE-ONLY: it seals the artifact to the
+    // account and the next app to open files it (remote/cargoSave.ts). Signed-in only,
+    // because the queue is the account's; a signed-out session gets no tool rather than
+    // one that refuses every call. The rest of the relay set stays out: send_file needs
+    // a live app to receive bytes, and the chart tools READ decrypted content back.
+    const { hasCredentials } = await import("../auth/privateer.ts");
+    if (hasCredentials()) {
+      const { makeSaveCargoTool } = await import("../tools/cargo.ts");
+      factories.push((pi: any) => { pi.registerTool?.(makeSaveCargoTool()); });
+    }
   }
 
   if (opts.resultMedia) {

package/src/config/paths.ts

@@ -45,6 +45,18 @@ export function configPath(): string {
 // session belonging to a STILL-RUNNING terminal from one orphaned by a crash, so it
 // can reclaim the orphan instead of spawning another and walking into the server's
 // per-device terminal cap. Holds refresh tokens — written 0600, like credentials.json.
+//
+// One file per owning pid in a directory, not one shared JSON file: concurrent launches
+// (an agent firing several `privateer -p` runs at once) each read-modify-wrote the whole
+// file, so one could write back an orphan another had already adopted (see
+// auth/accountSessions.ts).
+export function accountSessionsDir(): string {
+  return join(globalDir(), "account-sessions");
+}
+
+// The pre-directory single-file registry. Only ever deleted now (clearOwnedSessions);
+// its entries are never offered for reclamation, because a stale one is exactly the
+// token that trips the server's reuse detection.
 export function accountSessionsPath(): string {
   return join(globalDir(), "account-sessions.json");
 }

package/src/config/whatsNew.json

@@ -1,10 +1,10 @@
 {
   "$comment": "The banner's What's New list, newest first: the two to four things a returning user should notice, not a changelog. `reviewedFor` is the release this list was last looked at for. A release can't ship until it equals package.json's version (scripts/check-whats-new.mjs, run by `npm test` and by release.yml before anything builds), so every release, patches included, is a deliberate look at this list. If nothing new is worth a line, bumping `reviewedFor` alone is the answer. `since` is the release an entry arrived in. `cmd` is shown in the accent colour.",
-  "reviewedFor": "0.14.2",
+  "reviewedFor": "0.14.4",
   "items": [
+    { "text": "Save to Cargo with no app attached — it lands on your next app open", "since": "0.14.4" },
+    { "text": "Several privateer -p runs at once no longer sign each other out", "since": "0.14.3" },
     { "text": "A reply cut off at the output limit picks back up on its own", "since": "0.14.2" },
-    { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" },
-    { "text": "Hand off sensitive files: privateer --private", "since": "0.14.0" },
-    { "text": "Open and switch named terminals —", "cmd": "/term", "since": "0.13.0" }
+    { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" }
   ]
 }

package/src/engine/errors.ts

@@ -597,7 +597,7 @@ export function describeErrorText(
         bare ? `${who} ${refused} this request was sent with (${status}).` : compactProviderError(s),
       ),
       hint: account
-        ? "This terminal's Privateer session was refused. It is renewed automatically on your next message; if it keeps failing, run /login (or `privateer auth status` to see whether this machine is signed in)."
+        ? "This run's Privateer session was refused. A fresh one is opened automatically — send the message again, or re-run a one-shot (`-p`) command. Only if it keeps failing, check `privateer auth status`."
         : `Check the API key for ${who} — run /login, or set the provider's API key env var.`,
     };
   }

package/src/outbox/cloudOutbox.ts

@@ -26,12 +26,13 @@
 // per-instance caches this replaced.
 
 import { readFileSync, existsSync, statSync } from "node:fs";
-import { apiRequest, defaultDeviceLabel } from "../auth/privateer.ts";
+import { apiRequest, defaultDeviceLabel, hasCredentials } from "../auth/privateer.ts";
 import { loadAccountSignKey } from "../crypto/accountTrust.ts";
 import { verifyOutboxKey } from "../crypto/accountVerify.ts";
 import { sealJson, seal, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { routineRelayId, type OutboxKind } from "../routines/store.ts";
 import { MAX_ATTACHMENT_BYTES, type MediaClass, type StagedMedia } from "../routines/resultMedia.ts";
+import type { CargoSaveRequest } from "../remote/cargoSave.ts";
 
 export type { OutboxKind };
 
@@ -337,3 +338,77 @@ export async function postOutbox(
     return false;
   }
 }
+
+// ── Queued Cargo saves ───────────────────────────────────────────────────────
+//
+// `save_cargo` with no app attached (remote/cargoSave.ts has the why). Its own mailbox,
+// /api/outbox/cargo, not an outbox item: every shipped app acks every item it fetches,
+// so an artifact sent as one would be eaten — acked and never filed — by any device
+// still on an older build, and filing has to happen once per account, which needs the
+// server-side claim that mailbox has and this one doesn't.
+
+/** Ceiling on the sealed artifact, matching the server's MAX_CARGO_SEALED_BYTES. */
+export const MAX_QUEUED_CARGO_SEALED_BYTES = 2 * 1024 * 1024;
+
+/**
+ * The plaintext the app opens — treeview client/utils/queuedCargoParse.ts reads exactly
+ * this. `type` (not `kind`) names the envelope: `kind` is the artifact's, and the app's
+ * reader refuses anything that isn't a cargo envelope rather than guessing.
+ */
+export function queuedCargoEnvelope(req: CargoSaveRequest, at: Date, origin: { id: string; label: string }) {
+  return {
+    v: 1,
+    type: "cargo",
+    kind: req.kind,
+    ...(req.title ? { title: req.title } : {}),
+    content: req.content,
+    at: at.toISOString(),
+    origin,
+  };
+}
+
+export type QueuedCargoResult = { ok: true; id: string } | { ok: false; reason: string };
+
+/**
+ * Seal one artifact to the account and park it for the app to file. Never throws;
+ * every failure comes back as a reason written for the model to repeat.
+ */
+export async function postQueuedCargo(req: CargoSaveRequest): Promise<QueuedCargoResult> {
+  if (!hasCredentials()) {
+    return { ok: false, reason: "this terminal is not signed in to a Privateer account — run /signin, then save again" };
+  }
+  const pub = await ensureOutboxPub();
+  if (!pub) {
+    // No pinned account key, or one the published key doesn't verify against. Either way
+    // sealing would be to a key nobody has shown belongs to this account — fail closed.
+    return {
+      ok: false,
+      reason:
+        "the account's encryption key could not be verified from this terminal — open the Privateer app once (it publishes the key), " +
+        "or re-link this terminal from the app, then save again",
+    };
+  }
+  const sealed = sealJson(pub, queuedCargoEnvelope(req, new Date(), machineOrigin()));
+  if (Math.floor((sealed.length * 3) / 4) > MAX_QUEUED_CARGO_SEALED_BYTES) {
+    return { ok: false, reason: "the artifact is too large to queue — trim it below 512 KB" };
+  }
+  try {
+    const res = await apiRequest("/api/outbox/cargo", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ sealed }),
+    });
+    if (res.ok) {
+      const data = (await res.json().catch(() => ({}))) as { id?: unknown };
+      return { ok: true, id: typeof data.id === "string" ? data.id : "" };
+    }
+    if (res.status === 404) {
+      return { ok: false, reason: "the Privateer server does not accept queued artifacts yet — attach the app to this terminal and save again" };
+    }
+    const err = (await res.json().catch(() => ({}))) as { message?: unknown };
+    const message = typeof err.message === "string" && err.message ? err.message : `the server answered ${res.status}`;
+    return { ok: false, reason: `the server refused to queue it: ${message}` };
+  } catch (e) {
+    return { ok: false, reason: `the server could not be reached (${(e as Error).message})` };
+  }
+}

package/src/permissions/classify.ts

@@ -374,7 +374,7 @@ export function classifyToolCall(
       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`,
+      detail: `${outside || protectedSrc ? abs : src}${kindNote}${titleNote} → the app encrypts it and stores it in Cargo (queued, sealed, if no app is attached)`,
       protected: protectedSrc,
       outside,
       path: abs,

package/src/remote/cargoSave.ts

@@ -18,10 +18,21 @@
 // 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.
+// WHEN NO APP IS ATTACHED. The live round trip needs an app on the other end, and
+// requiring one made save_cargo useless exactly where it was wanted most: a terminal
+// nobody is driving, and every harbor. So with no app attached the artifact is QUEUED
+// instead (outbox/cloudOutbox.ts postQueuedCargo): sealed to the account's X25519
+// outbox public key — the same write-only sealed box Inbox results use, verified
+// against the account signing key pinned at link — and parked at /api/outbox/cargo.
+// The next app to sync opens it and files it through the very same saveCargo()
+// (treeview client/services/queuedCargoService.ts). The master key still never
+// leaves the app, the server still holds only ciphertext, and the stored row is the
+// one the live path would have made. What the queue cannot do is confirm: there is no
+// cargoId until an app files it, and the tool says exactly that.
+//
+// Only an UNATTACHED failure falls back (`unattached: true` below). An app that
+// refused, timed out, or dropped mid-transfer may already have stored the artifact,
+// and queueing it as well is how a user ends up with two copies.
 
 /** Cargo artifact kinds — mirrors client/utils/cargoKinds.ts CargoKind. */
 export const CARGO_KINDS = ["webpage", "slides", "game", "pdf", "docx", "md", "sheet"] as const;
@@ -102,4 +113,7 @@ export interface CargoSaveRequest {
  */
 export type CargoSaveResult =
   | { ok: true; cargoId: string; title: string; storageType: string }
-  | { ok: false; reason: string };
+  | { ok: false; reason: string; unattached?: true };
+
+/** Is this failure "there was no app to ask" — the one a queued save may follow? */
+export const isUnattached = (r: CargoSaveResult): boolean => !r.ok && r.unattached === true;

package/src/remote/remoteBridge.ts

@@ -522,12 +522,15 @@ export class RemoteBridge {
   //    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" });
+    // The three "nobody to ask" answers carry `unattached`, which is what lets the tool
+    // queue the artifact for the app instead (cargoSave.ts). Nothing was sent, so there is
+    // no chance a queued copy duplicates one the app stored.
+    if (!this.relay) return Promise.resolve({ ok: false, unattached: true, 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, unattached: true, 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" });
+      return Promise.resolve({ ok: false, unattached: true, reason: "the Privateer app is not attached to this terminal" });
     }
     const id = randomUUID();
     return new Promise<CargoSaveResult>((resolve) => {

package/src/tools/cargo.ts

@@ -2,10 +2,12 @@
 // 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:
+// The interesting part is not this file, it's why the save goes 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). Two routes follow from it: with an
+// app attached, a live round trip that comes back with the stored row's id; with
+// none, the artifact is sealed to the account and QUEUED for the next app to file.
+// What matters here is the shape that follows:
 //
 // 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
@@ -28,6 +30,11 @@
 // 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.
+//
+// AND WHAT HASN'T HAPPENED YET. A queued save is not a saved one: it is in no
+// Cargo list until an app opens and files it. The queued line says so in as many
+// words, because "saved" would send the user to look for something that isn't
+// there yet.
 
 import { Type } from "typebox";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -39,9 +46,11 @@ import {
   isHtmlKind,
   kindForExtension,
   type CargoKind,
+  isUnattached,
   type CargoSaveRequest,
   type CargoSaveResult,
 } from "../remote/cargoSave.ts";
+import { postQueuedCargo, type QueuedCargoResult } from "../outbox/cloudOutbox.ts";
 
 function text(t: string) {
   return { content: [{ type: "text", text: t }], details: {} };
@@ -52,6 +61,9 @@ export interface CargoSaveBridge {
   saveCargoRemote(req: CargoSaveRequest, signal?: AbortSignal): Promise<CargoSaveResult>;
 }
 
+/** Where an artifact goes when no app is attached. Injectable for tests. */
+export type CargoQueue = (req: CargoSaveRequest) => Promise<QueuedCargoResult>;
+
 export const CARGO_TOOL_NAMES = ["save_cargo"] as const;
 
 /**
@@ -71,7 +83,11 @@ function kindMatchesExtension(kind: CargoKind, ext: string): boolean {
   return implied === "md" && (kind === "md" || kind === "pdf" || kind === "docx");
 }
 
-export function makeSaveCargoTool(bridge: CargoSaveBridge) {
+/**
+ * `bridge` is the live route — absent in a session with no relay of its own (a harbor
+ * run, a channels session), which then only ever queues. `queue` is the other route.
+ */
+export function makeSaveCargoTool(bridge?: CargoSaveBridge, queue: CargoQueue = postQueuedCargo) {
   return {
     name: "save_cargo",
     label: "Save to Cargo",
@@ -85,9 +101,11 @@ export function makeSaveCargoTool(bridge: CargoSaveBridge) {
       "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.",
+      "Works whether or not the Privateer app is attached. Attached: the app encrypts and stores it now. " +
+      "Not attached: the artifact is sealed to the user's account key and queued, and the app files it the " +
+      "next time it opens — it is NOT in Cargo until then, so say that rather than that it is saved. Either " +
+      "way only the user's app can read it; the server holds ciphertext. 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').",
@@ -165,11 +183,27 @@ export function makeSaveCargoTool(bridge: CargoSaveBridge) {
       }
       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,
-      );
+      const req: CargoSaveRequest = { content, kind, title: params.title?.trim() || undefined };
+      const res: CargoSaveResult = bridge
+        ? await bridge.saveCargoRemote(req, signal)
+        : { ok: false, unattached: true, reason: "no app is attached to this session" };
 
+      if (!res.ok && isUnattached(res)) {
+        const queued = await queue(req);
+        if (!queued.ok) {
+          return text(
+            `Couldn't save ${basename(target)} to Cargo. No Privateer app is attached (${res.reason}), ` +
+              `and queueing it for the app failed: ${queued.reason}.`,
+          );
+        }
+        const label = req.title ? `"${req.title}"` : basename(target);
+        return text(
+          `Queued ${label} for Cargo (${kind}, ${(stat.size / 1024).toFixed(0)} KB). No Privateer app is attached right now, ` +
+            `so it was sealed to the user's account key and parked on the server as ciphertext only their app can open. ` +
+            `It will appear in Cargo the next time the Privateer app opens on any of their devices — it is not there yet, ` +
+            `so tell the user that rather than that it is saved.`,
+        );
+      }
       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}). ` +

package/src/tools/media.ts

@@ -227,12 +227,22 @@ async function callAccount<T>(
   if (res.status === 402 || /INSUFFICIENT|QUOTA|TOP_?UP/i.test(code)) {
     return { ok: false, status: res.status, message: serverMessage || "the account is out of credit for media generation — top up or upgrade to continue" };
   }
-  if (res.status === 401 || res.status === 403) {
+  // Same split as callRag (tools/web.ts): a 401 survived authedFetch's retry, a 403 is
+  // a refusal that signing in again won't change.
+  if (res.status === 401) {
     return {
       ok: false, status: res.status,
       message:
         serverMessage ||
-        "this agent is not signed in to a Privateer account (or the plan doesn't include this), so it cannot generate media",
+        "Privateer refused this agent's session (401) — running the command again opens a fresh one; if it keeps failing, check `privateer auth status`",
+    };
+  }
+  if (res.status === 403) {
+    return {
+      ok: false, status: res.status,
+      message:
+        serverMessage ||
+        "Privateer refused this media request (403) — the plan may not include it; this is not a sign-in problem",
     };
   }
   if (res.status === 400 || res.status === 413) {

package/src/tools/relayFileTools.ts

@@ -18,18 +18,18 @@ import { makeChartTools, type ChartOpBridge } from "./charts.ts";
 import { makeSaveToLibraryTool, type LibrarySaveBridge } from "./saveToLibrary.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
-// 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.
-// save_to_library rides here for save_cargo's reason exactly — it needs a CONNECTED
+// save_cargo rides with the file pair because, in a session that HAS a relay, it should
+// try the attached app first: that path comes back with the stored row. With no app
+// attached it queues the artifact for the next app to file instead (remote/cargoSave.ts),
+// which is also how a session with no relay at all gets it — config/moat.ts registers a
+// queue-only copy there.
+// save_to_library rides here because it needs a CONNECTED
 // APP rather than a signed-in account, because only the app holds the master key that
 // a Library row's ciphertext is under. Putting it in the moat's media block would give
 // it to every harbor and channels session, where there is no controller and every call
 // would fail; an unattended run already delivers a file a different way, as a sealed
 // attachment on its Inbox result (routines/resultMedia.ts).
-// The chart tools ride here too, for the same reason save_cargo does and one more of
+// The chart tools ride here too, for save_to_library's reason and one more of
 // their own. Same reason: they need a CONNECTED APP, not a signed-in account, so the
 // moat's media block would put them in every harbor and channels session where there is
 // no controller and every call would fail. Their own reason: unlike cargo they also READ

package/src/tools/web.ts

@@ -129,8 +129,23 @@ export async function callRag<T>(path: string, body: unknown): Promise<({ ok: tr
   if (res.status === 402 || /CAP|QUOTA|INSUFFICIENT|TOP_?UP/i.test(code)) {
     return { ok: false, message: serverMessage || "the account is out of credit for web access — top up or upgrade to continue" };
   }
-  if (res.status === 401 || res.status === 403) {
-    return { ok: false, message: "this agent is not signed in to a Privateer account, so it has no web access" };
+  // A 401 here has already survived authedFetch's refresh-and-retry, so the session
+  // really couldn't be renewed. A 403 is NOT a sign-in problem — a plan or account
+  // refusal, or the edge firewall in front of the API — and calling it "not signed in"
+  // had models telling signed-in users to log in. Pass the server's reason through.
+  if (res.status === 401) {
+    return {
+      ok: false,
+      message:
+        serverMessage ||
+        "Privateer refused this agent's session for web access (401) — running the command again opens a fresh one; if it keeps failing, check `privateer auth status`",
+    };
+  }
+  if (res.status === 403) {
+    return {
+      ok: false,
+      message: serverMessage || "Privateer refused this web request (403) — not a sign-in problem, so logging in again won't change it",
+    };
   }
   if (res.status === 400) {
     return { ok: false, message: serverMessage || `Privateer rejected the request${code ? ` (${code})` : ""}` };