privateer-agent 0.14.3 → 0.14.5

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.3",
+  "version": "0.14.5",
   "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/bridge/engineAdapter.ts

@@ -73,11 +73,17 @@ export function createEngineEventAdapter() {
   let turnTotal: UsageTotals = emptyUsage();
   let lastMessage: any;
   let terminalSent = false;
+  // Between agent_start and agent_settled. Compaction maps to `step-finish` to keep
+  // the app's busy pill lit through an auto-compaction INSIDE a run — but a manual
+  // `/compact` runs with no run around it, and a `step-finish` there opened a turn
+  // in the app that no `finish` would ever close: the pill spun until Stop.
+  let inRun = false;
 
   function toEngineEvents(ev: PiSessionEvent): EngineEvent[] {
     switch (ev.type) {
       case "agent_start":
         terminalSent = false;
+        inRun = true;
         return [];
 
       case "message_update": {
@@ -136,6 +142,7 @@ export function createEngineEventAdapter() {
       }
 
       case "agent_settled": {
+        inRun = false;
         if (terminalSent) return [];
         terminalSent = true;
         const msg = lastMessage;
@@ -158,7 +165,7 @@ export function createEngineEventAdapter() {
       }
 
       case "compaction_start":
-        return [{ type: "step-finish" }];
+        return inRun ? [{ type: "step-finish" }] : [];
       case "compaction_end":
         return [
           {

package/src/cli/chat.ts

@@ -349,6 +349,7 @@ async function main() {
       return;
     }
     turnActive = true;
+    let failure: string | undefined;
     if (remote && echo) console.log(`\n${DIM}⟿ [app] ${text.slice(0, 80)}${RESET}`);
     try {
       // Re-arm the account channel BEFORE the prompt, because nothing downstream can.
@@ -375,10 +376,13 @@ async function main() {
       }
       await session.prompt(mentions.text, mentions.images.length ? { images: mentions.images } : undefined);
     } catch (e) {
-      console.log(`\n${RED}${(e as Error).message}${RESET}`);
+      failure = (e as Error).message || "The turn failed.";
+      console.log(`\n${RED}${failure}${RESET}`);
     } finally {
       turnActive = false;
-      if (remote) bridge.settleTurn();
+      // The failure goes to the app too: a throw here (no model, no key, auth
+      // precheck) used to print on this console only while the app's pill spun on.
+      if (remote) bridge.settleTurn(failure);
     }
   }
 

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/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.3",
+  "reviewedFor": "0.14.5",
   "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": "Chat channels as a login service: privateer channels install", "since": "0.14.1" }
   ]
 }

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/liveTaskSession.ts

@@ -140,6 +140,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   const runTurn = async (text: string): Promise<void> => {
     if (turnActive || stopped) return;
     turnActive = true;
+    let failure: string | undefined;
     lastAnswer = "";   // keep the CLOSING answer, not the whole session
     turnErrored = false;
     try {
@@ -161,10 +162,11 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
       await session.prompt(text + note);
     } catch (e) {
       turnErrored = true;
-      deps.log(`live task ${termId} turn error: ${(e as Error).message}`);
+      failure = (e as Error).message || "The turn failed.";
+      deps.log(`live task ${termId} turn error: ${failure}`);
     } finally {
       turnActive = false;
-      bridge.settleTurn();
+      bridge.settleTurn(failure);
     }
   };
 

package/src/remote/remoteBridge.ts

@@ -15,7 +15,8 @@ import { noQuarterActive, setNoQuarter } from "../permissions/noQuarter.ts";
 // Pure env-var accessors (see config/privacyDisabled.ts) — no Pi, no node builtins,
 // so this stays safe to import from the bridge, which boot-ordered code reaches.
 import { onPrivacyDisabledChange, privacyDisabled, setPrivacyDisabled } from "../config/privacyDisabled.ts";
-import type { EngineEvent } from "../engine/events.ts";
+import { emptyUsage, type EngineEvent } from "../engine/events.ts";
+import { redactText } from "../util/redact.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
 import type { AskOutcome } from "../permissions/modeGate.ts";
 import type { RelayCallbacks } from "./relayClient.ts";
@@ -196,6 +197,14 @@ export class RemoteBridge {
   private turnDriven = false;
   private turnPrompt = "";
   private turnText = "";
+  // Did this turn already put finish/aborted/error on the wire? The app lights its
+  // working pill the moment it SENDS a prompt and only ever puts it out on one of
+  // those three, but Pi's prompt() has paths that never run the agent at all — an
+  // extension command or input hook that handles the text, a throw on the
+  // no-model / no-key / auth precheck, "compaction in progress". Each returned (or
+  // threw into a catch that only printed locally) with no terminal event, and the
+  // driver watched a spinner nothing would ever clear. settleTurn closes the gap.
+  private turnTerminalSent = false;
 
   // Unsubscribes the privacy watcher below. Held so a bridge that outlives its window
   // (the desktop builds one per window, in one process) stops writing to a transport
@@ -232,6 +241,7 @@ export class RemoteBridge {
       this.turnDriven = true;
       this.turnPrompt = text;
       this.turnText = "";
+      this.turnTerminalSent = false;
       const attachments = this.pendingAttachments;
       this.pendingAttachments = [];
       this.cfg.onPrompt(text, attachments);
@@ -460,20 +470,33 @@ export class RemoteBridge {
   // ── turn lifecycle + event forwarding ───────────────────────────────────────
 
   // Mark the end of a turn so the next (possibly local) turn isn't treated as
-  // remote. Call after each driven turn completes.
+  // remote. Call after each driven turn completes, passing the rejection message
+  // if prompt() threw.
+  //
+  // A DRIVEN turn always leaves here with exactly one terminal event on the wire
+  // (see turnTerminalSent): if the session never sent one, this sends it — `error`
+  // carrying the throw, or a plain `finish` for a prompt Pi handled without
+  // running the agent. Desktop's turnSupervisor emits its own terminal before it
+  // settles, so it is seen here and never doubled.
   //
   // Also the one moment we can tell whether the turn had an audience. If the app
   // drove it and is now gone, everything the turn streamed up was dropped by the
   // relay — so hand the answer to the owner for durable delivery rather than letting
   // a completed piece of work evaporate because someone closed their phone.
-  settleTurn(): void {
+  settleTurn(error?: string): void {
     const driven = this.turnDriven;
     const prompt = this.turnPrompt;
     const content = this.turnText.trim();
+    if (driven && !this.turnTerminalSent) {
+      this.forwardEvent(error
+        ? { type: "error", error: redactText(error) }
+        : { type: "finish", usage: emptyUsage(), finishReason: "stop" });
+    }
     this.remote = false;
     this.turnDriven = false;
     this.turnPrompt = "";
     this.turnText = "";
+    this.turnTerminalSent = false;
     if (!driven || !content) return;
     // Unknown (a relay that can't report presence) counts as watched: better to skip
     // delivery than to duplicate something the app already showed in its feed.
@@ -488,6 +511,7 @@ export class RemoteBridge {
     // Keep the driven turn's reply as it streams, in case settleTurn finds nobody
     // was there to read it. Text only: the outbox item is the answer, not a
     // transcript of every tool call.
+    if (ev.type === "finish" || ev.type === "aborted" || ev.type === "error") this.turnTerminalSent = true;
     if (this.turnDriven && ev.type === "text" && this.turnText.length < MAX_TURN_CAPTURE) {
       this.turnText += String(ev.text ?? "");
     }
@@ -522,12 +546,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/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