privateer-agent 0.15.4 → 0.15.6

package/patches/pi-background-tasks+2.6.10.patch

@@ -22,7 +22,7 @@ index 2a4d905..3a689f5 100644
  type HostForwardingStream = AssistantMessageEventStreamLike & HostAssistantMessageEventStream;
  
 diff --git a/node_modules/pi-background-tasks/src/core/registry.ts b/node_modules/pi-background-tasks/src/core/registry.ts
-index df6e6f4..cbab9f2 100644
+index df6e6f4..8cbbec2 100644
 --- a/node_modules/pi-background-tasks/src/core/registry.ts
 +++ b/node_modules/pi-background-tasks/src/core/registry.ts
 @@ -1,11 +1,11 @@
@@ -32,7 +32,7 @@ index df6e6f4..cbab9f2 100644
  import { createWriteStream, existsSync } from 'node:fs';
  import { mkdir, realpath, rm, writeFile } from 'node:fs/promises';
 -import { join } from 'node:path';
-+import { join, resolve } from 'node:path';
++import { delimiter, join, resolve } from 'node:path';
  import type { Api, Model } from '@earendil-works/pi-ai';
  import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 -import { formatSize } from '@earendil-works/pi-coding-agent';
@@ -40,7 +40,23 @@ index df6e6f4..cbab9f2 100644
  import {
    boundedRead,
    deriveTaskNameFromCommand,
-@@ -1263,9 +1263,29 @@ export class BackgroundTaskRegistry {
+@@ -791,6 +791,15 @@ function writeDelegateStdin(
+   });
+ }
+ 
++// Privateer: a background shell must see the machine's PATH, not Privateer's private Node.
++function withoutPrivateRuntime(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
++  const hidden = env['PRIVATEER_PRIVATE_RUNTIME_DIR'];
++  if (!hidden) return env;
++  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path') ?? 'PATH';
++  const visible = (env[key] ?? '').split(delimiter).filter((entry) => entry !== hidden);
++  return { ...env, [key]: visible.join(delimiter) };
++}
++
+ export class BackgroundTaskRegistry {
+   private readonly tasks = new Map<string, BgTask>();
+   private runtimeDir: RuntimeDir | undefined;
+@@ -1263,9 +1272,29 @@ export class BackgroundTaskRegistry {
      if (this.runtimeDir) return this.runtimeDir;
      const sessionId = sanitizePathSegment(ctx.sessionId ?? `session-${String(process.pid)}`);
      const runId = `${sessionId}-${String(process.pid)}`;
@@ -73,11 +89,50 @@ index df6e6f4..cbab9f2 100644
      this.runtimeDir = { abs: runtimeDirAbs, display: runtimeDirDisplay };
      return this.runtimeDir;
    }
+@@ -1514,7 +1543,7 @@ export class BackgroundTaskRegistry {
+         killProcess: this.killProcess,
+         killTree: this.killTree,
+         platform: this.platform,
+-        env: this.env,
++        env: withoutPrivateRuntime(this.env),
+         maxOutputBytes: this.maxOutputBytes,
+         killGraceMs: this.killGraceMs,
+         stopWaitMs: this.stopWaitMs,
+@@ -1739,7 +1768,7 @@ export class BackgroundTaskRegistry {
+         cwd: ctx.cwd,
+         detached: this.platform !== 'win32',
+         stdio: ['ignore', 'pipe', 'pipe'],
+-        env: this.env,
++        env: withoutPrivateRuntime(this.env),
+         windowsHide: true,
+         windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+       });
 diff --git a/node_modules/pi-background-tasks/src/extension.ts b/node_modules/pi-background-tasks/src/extension.ts
-index c966df5..b073a15 100644
+index c966df5..10b38c4 100644
 --- a/node_modules/pi-background-tasks/src/extension.ts
 +++ b/node_modules/pi-background-tasks/src/extension.ts
-@@ -710,8 +710,8 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
+@@ -223,6 +223,20 @@ function renderPlainResult(result: TextToolResult, options: ToolRenderResultOpti
+   return new Text(text, 0, 0);
+ }
+ 
++const MAX_ONE_SHOT_EXIT_NOTICES = 3;
++
++function oneShotExitNotice(tasks: string[]): string {
++  return [
++    'You ended your turn, but this is a one-shot run. The process exits when you stop, and these background tasks will be killed with it:',
++    ...tasks.map((task) => `- ${task}`),
++    '',
++    'Handle each one before you finish:',
++    '- If the work depends on its result, wait for it. Check with bg_status and bg_logs, using `sleep` in bash between checks, then finish and verify the work.',
++    '- If it has to keep running after this run, such as a server or daemon, bg_kill it, start it detached with `setsid nohup <command> > <logfile> 2>&1 < /dev/null &`, and confirm it is still up.',
++    '- If it is no longer needed, bg_kill it.',
++  ].join('\n');
++}
++
+ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promise<void> {
+   const config = parseBackgroundTasksConfig();
+   const dockEntryHint = dockShortcutFooterHint(config.dockShortcut);
+@@ -710,8 +724,8 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
      currentCtx = ctx;
      const nextRegistryCtx = currentRegistryCtx ?? registryContext(ctx);
      currentRegistryCtx = nextRegistryCtx;
@@ -88,7 +143,36 @@ index c966df5..b073a15 100644
      updateUi(ctx);
      hostService.markReady();
      if (disposed) return;
-@@ -830,22 +830,11 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
+@@ -729,6 +743,28 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
+     if (!disposed) void scheduleUpdateCheck(ctx);
+   });
+ 
++  // Privateer patch: a one-shot run must not quietly kill what it started.
++  //
++  // In the TUI a background task outlives the turn and reports back when it finishes. `-p`
++  // exits when the turn ends and shutdown kills whatever is still running, so a model that
++  // says "training continues in the background", or leaves a server up, has just lost it.
++  // Say so while it can still act. Capped so a model that keeps stopping cannot loop.
++  let oneShotExitNotices = 0;
++  pi.on('agent_end', (_event, ctx) => {
++    if (ctx.mode !== 'print' && ctx.mode !== 'json') return;
++    const running = registry.allTasks().filter((task) => task.status === 'running');
++    if (running.length === 0 || oneShotExitNotices >= MAX_ONE_SHOT_EXIT_NOTICES) return;
++    oneShotExitNotices += 1;
++    pi.sendMessage(
++      {
++        customType: 'bg-one-shot-exit',
++        content: oneShotExitNotice(running.map((task) => `${task.id}: ${taskDisplayName(task)}`)),
++        display: false,
++      },
++      { deliverAs: 'followUp', triggerTurn: true },
++    );
++  });
++
+   pi.on('session_shutdown', async (event, ctx) => {
+     beginSessionShutdown(event.reason);
+     if (shutdownCleanupStarted) return;
+@@ -830,22 +866,11 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
    });
  
    pi.registerCommand('bg-update', {
@@ -114,7 +198,7 @@ index c966df5..b073a15 100644
        ];
        ctx.ui.notify(lines.join('\n'), 'info');
        return Promise.resolve();
-@@ -958,7 +947,7 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
+@@ -958,7 +983,7 @@ export default async function backgroundTasksExtension(pi: ExtensionAPI): Promis
    pi.registerTool<typeof BgRunParams, BgRunDetails>({
      name: 'bg_run',
      label: 'Background Run',

package/src/cli/chat.ts

@@ -16,6 +16,7 @@ import { privacyDisabled } from "../config/privacyDisabled.ts"; // no Pi deps
 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
+import { transcriptSnapshot, type SnapshotEntry } from "../remote/transcriptSnapshot.ts"; // no deps → 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"
@@ -181,7 +182,12 @@ async function main() {
     // the driver learns which folder they're driving without the OS username
     // crossing the relay.
     onControllerAttached: () => {
-      relay?.sendSnapshot([]);
+      // The session's transcript, so an app back from sleep catches up (transcriptSnapshot.ts).
+      {
+        let entries: SnapshotEntry[] = [];
+        try { entries = transcriptSnapshot(session?.sessionManager?.getBranch?.() ?? []); } catch { /* no session yet */ }
+        relay?.sendSnapshot(entries, { full: entries.length > 0, running: turnActive });
+      }
       relay?.sendContext({ model: currentSpec, cwd, version: agentVersion() });
       relay?.sendCommands(availableCommands());
     },

package/src/config/moatManifest.json

@@ -25,7 +25,9 @@
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
     { "entry": "extensions/privateer-truncation.ts", "name": "privateer-truncation", "note": "picks the task back up when a reply is cut off at the output limit" },
+    { "entry": "extensions/privateer-final-audit.ts", "name": "privateer-final-audit", "note": "makes a -p run check its result, and say what it invented or could not verify, before it ends" },
     { "entry": "extensions/privateer-fresh.ts", "name": "privateer-fresh", "note": "/fresh — replace the agent with a new one and stop everything it started" },
+    { "entry": "extensions/privateer-recovery.ts", "name": "privateer-recovery", "note": "crash recovery — the live marker the supervisor resumes from, the note that tells the model its last action may have half-run, and session-sealing warnings" },
     { "entry": "extensions/privateer-speak.ts", "name": "privateer-speak", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },
     { "entry": "extensions/privateer-web.ts", "name": "privateer-web", "note": "web_search/web_fetch — account search when signed in, else the user's own provider (rpiv-web-tools); crypto_lookup — account market data, in both cases" },
     { "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "name": "rpiv-ask-user-question", "note": "ask_user_question" },

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.15.4",
+  "reviewedFor": "0.15.6",
   "items": [
+    { "text": "Privateer now starts about three times faster, and quitting no longer freezes the next launch for up to 30 seconds", "since": "0.15.6" },
+    { "text": "If the agent crashes mid-task it comes back into your session, and saved sessions are now encrypted on disk", "since": "0.15.5" },
     { "text": "Slow images, speech and music run as background jobs — a dropped connection no longer loses a paid result", "since": "0.15.4" },
-    { "text": "Driving from the app: a message sent mid-turn steers it, and questions survive a dropped link", "since": "0.15.1" },
-    { "text": "MCP on Pi's built-in support — sign OAuth connectors back in with", "cmd": "/mcp", "since": "0.15.0" },
-    { "text": "Sub-agents are back: hand work to bounded parallel agents", "since": "0.15.0" }
+    { "text": "MCP on Pi's built-in support — sign OAuth connectors back in with", "cmd": "/mcp", "since": "0.15.0" }
   ]
 }

package/src/context.ts

@@ -191,14 +191,42 @@ export function discoverContextFiles(cwd: string = process.cwd()): ContextFile[]
 export const CONTEXT_BLOCK_MARKER = "<!-- privateer:PRIVATEER.md -->";
 export const RUNTIME_GUIDELINES_MARKER = "<!-- privateer:runtime-guidelines -->";
 
-export function runtimeGuidelinesBlock(): string {
+// bin/privateer-launch.mjs sets PRIVATEER_NODE; a host that embeds Privateer without the
+// launcher has no runtime to promise, so the model is told to check instead.
+function nodeGuideline(): string {
+  if (!process.env.PRIVATEER_NODE) {
+    return "- Node.js: may not be installed here. Check with `command -v node` before relying on it.";
+  }
+  return `- Node.js: Privateer's own runtime is at \`$PRIVATEER_NODE\` (v22+). Use it for throwaway calculations or JSON processing when nothing else fits: \`"$PRIVATEER_NODE" -e "..."\`. It is not part of this system: plain \`node\` exists only if the system really has it, and nothing you deliver (scripts, shebangs, services, git hooks, build output) may depend on \`$PRIVATEER_NODE\`, because it does not exist outside Privateer.`;
+}
+
+// Only for a `-p` run with nobody attached. An interactive user reviews each step and pays
+// per call, so they keep the stricter batching rule below; a run nobody is watching has no
+// other chance to catch its own mistakes.
+const UNATTENDED_RUN_GUIDELINES = `\n<unattended_run>
+Nobody is watching this run: no one can answer a question or catch a mistake before your final message. Work through to the end, take the most plausible reading of anything ambiguous, and name that assumption in your final message.
+- Prove the result before you stop. Exercise it the way the user will: from a fresh shell, through the requested entry point, with their exact commands if they gave any. Check what has to still exist after you exit, and build whatever throwaway checks that takes. Cleaning up must not undo the result.
+- Deliver exactly what was asked: the requested paths, formats and text, with nothing added or reworded.
+- Treat data you were given as irreplaceable. Copy it first and experiment on the copy, because merely opening a file with its usual tool can change or delete it.
+- Keep long jobs visible. Anything that may take more than a few minutes runs in the background writing to a log; check its progress, and shrink or drop an approach that will not finish. Never sit blocked on one silent command.
+- Open your final message with anything unfinished, unverified or lost.
+</unattended_run>\n`;
+
+export function runtimeGuidelinesBlock({ unattended = false }: { unattended?: boolean } = {}): string {
+  const whenToolMissing = unattended
+    ? "install it with the host package manager (e.g. `apt-get install -y`, `brew install`) and mention that in your final message"
+    : "explain clearly what is missing, and offer to install it using the host package manager (e.g. `brew install`, `xcode-select --install`, `winget install`, `apt install`) upon user approval";
+  const whatNotToBuild = unattended
+    ? "."
+    : "; do not build test harnesses, scratch scripts or regression runs that the user did not ask for.";
   return `\n\n${RUNTIME_GUIDELINES_MARKER}\n<environment_guidelines>
-- Node.js environment: Node.js (v22+) is guaranteed to be available in Privateer. Prefer \`node -e "..."\` or small Node.js scripts for quick scripting, calculations, or JSON processing instead of assuming \`python\` or \`python3\` is installed.
+${nodeGuideline()}
 - Search fallback: If \`rg\` (ripgrep) is missing or returns "command not found", fall back to standard POSIX \`grep -rn <pattern> <path>\` or \`find <path>\`.
-- Missing system dependencies: If an essential external tool (e.g. \`git\`, \`python\`, \`rg\`) is missing and needed, check its presence (\`command -v <tool>\`), explain clearly what is missing, and offer to install it using the host package manager (e.g. \`brew install\`, \`xcode-select --install\`, \`winget install\`, \`apt install\`) upon user approval.
+- Missing system dependencies: If an essential external tool (e.g. \`git\`, \`python\`, \`rg\`) is missing and needed, check its presence (\`command -v <tool>\`), ${whenToolMissing}.
 - Shell calls share no state: every shell call runs in a fresh subshell rooted at the session's working directory, so a \`cd\` (or a variable, or an activated venv) in one call is gone by the next. Use absolute paths, or move and work in ONE call (\`cd <dir> && <command>\`). Never spend a call on \`cd\` alone.
-- Batch your steps: every tool call re-sends the whole conversation to the model, so a chain of one-line calls is far slower and more expensive than the same work combined into fewer calls. Group independent reads, searches and checks into one command; do not build test harnesses, scratch scripts or regression runs that the user did not ask for.
-</environment_guidelines>\n`;
+- Batch your steps: every tool call re-sends the whole conversation to the model, so a chain of one-line calls is far slower and more expensive than the same work combined into fewer calls. Group independent reads, searches and checks into one command${whatNotToBuild}
+- Report what really happened: never present invented, guessed or placeholder data as a real result. If something could not be obtained, or you lost or damaged it, say so plainly.
+</environment_guidelines>\n${unattended ? UNATTENDED_RUN_GUIDELINES : ""}`;
 }
 
 // Format the discovered files into a system-prompt fragment using the same framing Pi

package/src/engine/finalAudit.ts

@@ -0,0 +1,38 @@
+// One forced look back before an unattended run ends.
+//
+// A `-p` run has nobody to notice a wrong result, and telling the model up front to be
+// honest did not hold. Measured on a data-recovery task (2026-11-09): having destroyed
+// its input, the model wrote invented rows into the user's database, cited the row count
+// as verification, and reported success with no caveat, with the honesty rule in its
+// system prompt. The rule is one line among thousands of tokens read before the work
+// starts; this asks the question after the work is done, with the evidence in context.
+//
+// So: when a top-level headless run that used tools ends normally, queue one follow-up
+// asking the model to check its result against what actually happened, fix what it can,
+// and open its final message with anything invented, unverified or lost. Pi continues a
+// message queued from an agent_end handler inside the same run, so `-p` waits for it, and
+// the audited reply is the one a script reads.
+//
+// Once per run. Runs that only answered have nothing to audit, and a turn that ended on
+// an error or an abort is handled elsewhere. A subagent's parent reviews what it returns.
+// PRIVATEER_FINAL_AUDIT=0 turns it off.
+//
+// IMPORT-SAFETY: no Pi imports — the shapes below are the few fields read.
+
+import { lastAssistant } from "./truncationRecovery.ts";
+
+export const FINAL_AUDIT_ENV = "PRIVATEER_FINAL_AUDIT";
+
+export const FINAL_AUDIT_PROMPT = `Before this run ends, check your work against what actually happened in this session.
+
+1. Re-read the original request. Is every part of it done, and did you see it work the way the user will use it? If something can still be fixed, fix it now.
+2. Look for anything presented as real that you did not directly observe or derive from the inputs: invented, guessed or reconstructed values, checks you did not run, inputs you changed or lost. If you wrote such values into a deliverable or the user's files, take them out if you can.
+
+Then write your final message to the user. Start with those items, stated plainly. If there are none, just give the result.`;
+
+export function needsFinalAudit(messages: unknown, mode: unknown, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (mode !== "print" && mode !== "json") return false;
+  if (env.PI_SUBAGENT_CHILD === "1" || env[FINAL_AUDIT_ENV] === "0") return false;
+  if (!Array.isArray(messages) || lastAssistant(messages)?.stopReason !== "stop") return false;
+  return messages.some((message) => message?.role === "toolResult");
+}

package/src/engine/stallWatchdog.ts

@@ -9,7 +9,8 @@
 // So: armed when a request goes out, re-armed by every streamed event (text, thinking,
 // tool-call deltas all count, so a slow but live stream never trips it), disarmed when
 // the message ends. Between requests (tool execution) it is off — a long local command
-// is not a provider stall. If it fires, the caller aborts the turn and says why.
+// is not a provider stall. If it fires, the caller aborts the turn and either resends it
+// (reset() re-enables the watchdog) or gives up and says why.
 //
 // The limit: PRIVATEER_REPLY_TIMEOUT seconds, default 180, 0 turns it off. Silence, not
 // total time, is what is measured, so a long answer is never cut off for being long.
@@ -55,6 +56,12 @@ export class StallWatchdog {
     this.timer = undefined;
   }
 
+  /** The stalled request is being resent: watch the new one. */
+  reset(): void {
+    this.disarm();
+    this.fired = false;
+  }
+
   get stalled(): boolean {
     return this.fired;
   }

package/src/providers/account.ts

@@ -923,7 +923,17 @@ export function makeAccountProvider(opts: { armOnStart?: boolean } = {}) {
     // all, and the first prompt dead-ends on "No API key found for privateer." — even
     // though the banner says "connected". The REPL (cli/chat.ts) and the harbor
     // already spawn one at startup; this gives the TUI the same seed.
-    if (opts.armOnStart !== false) pi.on?.("session_start", (_e, ctx) => void armAccountCredential(ctx));
+    //
+    // Nobody types faster than this resolves, so the TUI starts without waiting. `-p`
+    // prompts as soon as extensions are bound, and Pi's auth precheck runs before
+    // before_agent_start can re-arm, so a headless launch has to wait here. Without it,
+    // a signed-in machine with no leftover auth.json entry is told it isn't signed in.
+    if (opts.armOnStart !== false) {
+      pi.on?.("session_start", async (_e, ctx) => {
+        const arming = armAccountCredential(ctx);
+        if (!(ctx as SeedContext)?.hasUI) await arming;
+      });
+    }
 
     // Two safety nets around the account channel, both OUTSIDE the request path —
     // they read Pi's in-memory auth map and its finished messages, and never touch the
@@ -1088,8 +1098,10 @@ export async function armAccountCredential(
     // If the credentials vanished during the call, the spawn hit a 401 and
     // onSessionExpired already announced the sign-out — a second line here would
     // just repeat it (we returned early above if we STARTED signed out).
-    if (opts.notify !== false && c?.hasUI && hasCredentials()) {
-      c.ui?.notify?.(`Privateer account channel unavailable — ${(e as Error).message}`, "error");
+    if (opts.notify !== false && hasCredentials()) {
+      const message = `Privateer account channel unavailable — ${(e as Error).message}`;
+      if (c?.hasUI) c.ui?.notify?.(message, "error");
+      else console.error(message); // headless: the real cause, not "isn't signed in"
     }
     return false;
   }
@@ -1153,6 +1165,25 @@ export async function dropPersistedAccountCredential(
   }
 }
 
+// The drop for a process that is about to exit. Pi calls process.exit as soon as the
+// session_shutdown handlers return, so a drop nobody waits for dies mid-write: the
+// revoked credential stays on disk, and the lock on auth.json is left behind. Every
+// launch in the next 30 seconds then waits for that lock to go stale before it can
+// paint, which is what a quick quit-and-relaunch looked like: a frozen terminal.
+//
+// Bounded, because another terminal can legitimately hold that lock and quitting must
+// never hang. Past the bound the server-side TTL is the fallback, as for any failed drop.
+export async function dropPersistedAccountCredentialBeforeExit(timeoutMs = 2_000): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([
+    dropPersistedAccountCredential().catch(() => false),
+    new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+    }),
+  ]);
+  clearTimeout(timer);
+}
+
 // Make sure Pi still HAS an account credential before a turn goes out. Normally
 // session_start's arm is enough and this is a free in-memory lookup. It exists for the
 // case session_start can't cover: the persisted entry disappearing mid-session, which

package/src/remote/attentionPush.ts

@@ -0,0 +1,40 @@
+// "Your agent is asking you something" — a push to the account's phones when a
+// question (ask_user_question, a select, a text prompt) is put to an app that isn't
+// there to see it.
+//
+// A question sent up the relay only reaches a LIVE socket. A phone that backgrounded
+// a minute ago has none, so the question sat held on this machine (remoteBridge's
+// holdOpenQuestions) with nothing telling anyone it was waiting — the user found it
+// by chance, or after the hold ran out and the tool came back as an error.
+//
+// Content-free on purpose, like the Inbox nudge (server services/pushService.js): the
+// question itself never leaves the relay, so the push says only that one is waiting.
+// Fire-and-forget and throttled — a failed or skipped push must never touch the turn.
+
+const COOLDOWN_MS = 30_000;
+let lastAt = 0;
+let sink: (() => void) | null = null;
+
+export function requestAttentionPush(): void {
+  const now = Date.now();
+  if (now - lastAt < COOLDOWN_MS) return;
+  lastAt = now;
+  if (sink) return sink();
+  void (async () => {
+    try {
+      const { apiRequest, hasCredentials } = await import("../auth/privateer.ts");
+      if (!hasCredentials()) return;
+      await apiRequest("/api/push/attention", { method: "POST", signal: AbortSignal.timeout(10_000) });
+    } catch {
+      /* best effort — the question is still held and re-sent when the app comes back */
+    }
+  })();
+}
+
+/** Test seam: count pushes instead of sending them (null restores the real one), and
+ *  forget the cooldown. Tests run on machines that are signed in — without this a
+ *  bridge test would buzz the developer's phone. */
+export function setAttentionPushSink(fn: (() => void) | null): void {
+  sink = fn;
+  lastAt = 0;
+}

package/src/remote/liveTaskSession.ts

@@ -25,6 +25,7 @@ import { rememberAccountCredential, persistAccountCredential, dropPersistedAccou
 import { modelRegistryOf } from "../providers/piAuthStore.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
+import { transcriptSnapshot, type SnapshotEntry } from "./transcriptSnapshot.ts";
 import { AttachmentStore, type StoredAttachment } from "../util/attachmentStore.ts";
 import { spawnAccountCredentials, revokeAccountSession } from "../auth/privateer.ts";
 import { createUIContext } from "../ext/headlessUi.ts";
@@ -190,7 +191,12 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     onControllerAttached: () => {
       attached = true;
       if (attachTimer) { clearTimeout(attachTimer); attachTimer = undefined; }
-      relay?.sendSnapshot([]);
+      // The session's transcript, so an app back from sleep catches up (transcriptSnapshot.ts).
+      {
+        let entries: SnapshotEntry[] = [];
+        try { entries = transcriptSnapshot(session?.sessionManager?.getBranch?.() ?? []); } catch { /* no session yet */ }
+        relay?.sendSnapshot(entries, { full: entries.length > 0, running: turnActive });
+      }
       // cwd rides along here (and nowhere else — see RelayClient.sendContext): this
       // session's working directory was either named by the driver in the spawn form
       // or defaulted to the harbor's own, and they have no other way to see which.

package/src/remote/relayClient.ts

@@ -24,6 +24,7 @@ import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
 import { noQuarterActive } from "../permissions/noQuarter.ts";
 import { authorizeControl } from "./controlAuth.ts";
+import type { SnapshotTool } from "./transcriptSnapshot.ts";
 import { CARGO_CHUNK_CHARS, type CargoSaveRequest, type CargoSaveResult } from "./cargoSave.ts";
 import {
   LIBRARY_CHUNK_CHARS,
@@ -1175,10 +1176,43 @@ export class RelayClient {
 
   // Catch-up history sent to a controller on attach. Structured (not markdown) so
   // the app renders it with the same styling as the live feed. Bounded: last 80
-  // entries, each clipped.
-  sendSnapshot(entries: { kind: string; text: string }[]): void {
-    const trimmed = entries.slice(-80).map((e) => ({ kind: e.kind, text: safe(String(e.text ?? ""), 4000) }));
-    this.rawSend({ type: "snapshot", entries: trimmed });
+  // entries, each clipped, and the whole frame kept well under the relay's 256 KB
+  // frame cap by dropping the OLDEST entries first.
+  //
+  // `full` marks the entries as the terminal's whole current transcript (see
+  // transcriptSnapshot.ts), so the app may REPLACE what it holds rather than only
+  // adopting into an empty feed; `running` says whether a turn is still going, which
+  // is how a reattaching app learns that the turn it last saw "Link dropped" on is
+  // over. Both absent = the old notice-only snapshot, which the app keeps treating as
+  // such.
+  sendSnapshot(
+    entries: { kind: string; text: string; tool?: SnapshotTool }[],
+    meta?: { full?: boolean; running?: boolean },
+  ): void {
+    const out: Record<string, unknown>[] = [];
+    let budget = 160 * 1024;
+    for (const e of entries.slice(-80).reverse()) {
+      const t = e.tool;
+      const entry: Record<string, unknown> = t
+        ? {
+            kind: e.kind,
+            text: "",
+            tool: {
+              id: t.id,
+              name: t.name,
+              input: safe(t.input, 500),
+              ...(t.output !== undefined ? { output: safe(t.output, 1500) } : {}),
+              ...(t.error !== undefined ? { error: safe(t.error, 1000) } : {}),
+              ...(t.running ? { running: true } : {}),
+            },
+          }
+        : { kind: e.kind, text: safe(String(e.text ?? ""), e.kind === "reasoning" ? 1500 : 4000) };
+      budget -= JSON.stringify(entry).length;
+      if (budget < 0) break;
+      out.push(entry);
+    }
+    out.reverse();
+    this.rawSend({ type: "snapshot", entries: out, ...(meta?.full ? { full: true, running: meta.running === true } : {}) });
   }
 
   // ── agent → app file transfer (chunked) ─────────────────────────────────────

package/src/remote/remoteBridge.ts

@@ -20,6 +20,7 @@ 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";
+import { requestAttentionPush } from "./attentionPush.ts";
 import type { CargoSaveRequest, CargoSaveResult } from "./cargoSave.ts";
 import type { LibrarySaveRequest, LibrarySaveResult } from "./librarySave.ts";
 import type { ChartOpRequest, ChartOpResult } from "./chartOps.ts";
@@ -168,6 +169,10 @@ export interface RemoteBridgeConfig {
   onFilesSearch?: (id: string, query: string) => void;
   // A controller (re)attached — the owner should push a transcript snapshot.
   onControllerAttached?: () => void;
+  // A question is open and no app is attached to see it. Defaults to a content-free
+  // push to the account's phones (attentionPush.ts); a test or an owner with its own
+  // channel may replace it.
+  onQuestionUnwatched?: () => void;
   // The last controller went away. Informational for the owner (the bridge already
   // fails pending approvals closed); a driven turn in flight keeps running.
   onControllerDetached?: () => void;
@@ -380,6 +385,7 @@ export class RemoteBridge {
       this.remote = false;
       this.rejectAllPending();
       this.holdOpenQuestions();
+      if (this.hasOpenQuestion()) this.questionUnwatched();
       this.cfg.onControllerDetached?.();
     },
     onAttachment: (file) => {
@@ -472,6 +478,9 @@ export class RemoteBridge {
         signal.addEventListener("abort", onAbort, { once: true });
       }
       this.relay!.requestSelect(id, req);
+      // Sent into a socket with no app on the other end: it is held and re-sent on
+      // reattach, but nobody knows to come back unless they are told.
+      if (this.relay!.hasController?.() === false) this.questionUnwatched();
     });
   };
 
@@ -495,6 +504,9 @@ export class RemoteBridge {
         signal.addEventListener("abort", onAbort, { once: true });
       }
       this.relay!.requestInput(id, req);
+      // Sent into a socket with no app on the other end: it is held and re-sent on
+      // reattach, but nobody knows to come back unless they are told.
+      if (this.relay!.hasController?.() === false) this.questionUnwatched();
     });
   };
 
@@ -711,6 +723,11 @@ export class RemoteBridge {
     return true;
   }
 
+  private questionUnwatched(): void {
+    if (this.cfg.onQuestionUnwatched) return this.cfg.onQuestionUnwatched();
+    requestAttentionPush();
+  }
+
   private resendOpenQuestions(): void {
     this.releaseQuestionGrace();
     for (const [id, q] of this.pendingSelects) this.relay?.requestSelect(id, q.req);