privateer-agent 0.9.0 → 0.9.2

package/extensions/privateer-gate.ts

@@ -26,6 +26,7 @@ import { AttachmentStore, type StoredAttachment } from "../src/util/attachmentSt
 import { makeExtensionsControl } from "../src/remote/extensionsControl.ts";
 import { makeSkillsControl } from "../src/remote/skillsControl.ts";
 import { agentDir } from "../src/config/paths.ts";
+import { inHarborDaemon } from "../src/config/harborDaemon.ts";
 import { agentVersion } from "../src/config/version.ts";
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
@@ -446,8 +447,18 @@ export default function privateerControl(pi: any): void {
   // File transfer both ways: send_file_to_client (CLI→app, via the bridge's relay) and
   // save_attachment (app→CLI, from the AttachmentStore inbound files land in). Both
   // live here because they share the RemoteBridge / its attachment stream.
-  pi.registerTool?.(makeSendFileTool(bridge));
-  pi.registerTool?.(makeSaveAttachmentTool(attachments));
+  //
+  // NOT inside the harbor daemon. This extension is auto-discovered from the shared
+  // ~/.privateer/agent/extensions into every session the daemon runs, but `bridge` only
+  // ever gets a relay from THIS file's /remote-access command — which the daemon never
+  // runs. Registering there would shadow (Pi: first registration per name wins, and
+  // discovered extensions load before inline factories) the session-scoped pair a live
+  // task spawn registers against its own connected relay, so send_file_to_client would
+  // always answer "remote access is off" while the app was attached and driving.
+  if (!inHarborDaemon()) {
+    pi.registerTool?.(makeSendFileTool(bridge));
+    pi.registerTool?.(makeSaveAttachmentTool(attachments));
+  }
 
   // Subagents (and print/rpc) run as headless child `pi` processes with no UI. There
   // no one can approve, so a "default" gate would fail-closed on every tool and the

package/extensions/privateer-privacy.ts

@@ -5,15 +5,25 @@
 // over-warning), and a zdr account model as zdr-policy. Replaces loading pi-privacy's
 // default entry directly.
 //
-// It also WIDENS the tinfoil provider's model list. pi-privacy registers `tinfoil` with
-// a single seed model, so any other Tinfoil model — notably our default `tinfoil/glm-5-2`
-// — resolves as a "custom model id" with a startup warning and never shows in the picker.
-// We re-register tinfoil with its current chat catalog AFTER pi-privacy runs (a second
-// registerProvider call replaces the provider's model list; pi-privacy registers
-// synchronously, so ours lands second and wins). This is purely a display/resolution
-// list — posture and attestation are dispatcher-bound and unaffected by the model set.
+// It also REPAIRS two provider registrations pi-privacy makes from its own catalog, each
+// of which replaces (not merges) whatever model list that provider already had:
+//
+//   - `tinfoil` gets a single seed model, so any other Tinfoil model — notably our
+//     default `tinfoil/glm-5-2` — resolves as a "custom model id" with a startup warning
+//     and never shows in the picker. We re-register it with the current chat catalog.
+//   - `privateer` gets pi-privacy's PUBLIC developer-key channel (api.privateer.pro/v1 +
+//     `${PRIVATEER_API_KEY}`, one seed model), which clobbers the ACCOUNT channel our own
+//     privateer-account extension registers. That is our default model's provider, so the
+//     same "not found for provider privateer" warning followed — and worse, the model Pi
+//     synthesized pointed at the public endpoint instead of `/api/agent/v1`. We re-assert
+//     the account registration (see registerAccountModels).
+//
+// Both repairs run AFTER pi-privacy inside this same extension, so ours land second and
+// win regardless of the order pi discovers extensions in. This is purely a
+// display/resolution + routing list — posture and attestation are dispatcher-bound and
+// unaffected by the model set.
 import { makePiPrivacyExtension } from "pi-privacy";
-import { accountPosture } from "../src/providers/account.ts";
+import { accountPosture, registerAccountModels } from "../src/providers/account.ts";
 
 // Tinfoil's live chat models (inference.tinfoil.sh/v1/models), glm-5-2 first — the
 // launcher's default. Non-chat endpoints (embeddings, tts, whisper, websearch,
@@ -82,4 +92,6 @@ export default function privateerPrivacy(pi: any): void {
     authHeader: true,
     models: TINFOIL_MODELS.map(tinfoilModel),
   });
+  // Put the ACCOUNT channel back over pi-privacy's public developer-key `privateer`.
+  registerAccountModels(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",

package/src/config/harborDaemon.ts

@@ -0,0 +1,31 @@
+// "Am I running inside the harbor daemon?" — a process-level marker, set once by
+// Harbor.start() and read by code that must behave differently there.
+//
+// The harbor daemon shares ~/.privateer/agent with the interactive TUI, so Pi
+// auto-discovers the shipped TUI extensions (extensions/*.ts shims installed by
+// bin/privateer-launch.mjs) into every session the daemon creates. Most of that is
+// harmless, but the gate extension also registers the relay file tools against ITS
+// module-level bridge — the one only `/remote-access` ever attaches a relay to. In the
+// daemon that bridge is permanently unattached, and because Pi resolves duplicate tool
+// names first-registration-wins (discovered extensions load before inline factories), it
+// would shadow the session-scoped pair a live task registers against its own live relay.
+// So the gate stands its file tools down here and each daemon session registers its own
+// (see src/tools/relayFileTools.ts, src/remote/liveTaskSession.ts).
+//
+// An env var rather than a module singleton on purpose: discovered extensions are loaded
+// through jiti with its module cache off, so they may hold a SEPARATE copy of our modules.
+// process.env is the one piece of state both copies are guaranteed to share.
+//
+// IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere.
+
+const ENV = "PRIVATEER_HARBOR_DAEMON";
+
+/** Called once by the daemon as it starts. Idempotent. */
+export function markHarborDaemon(): void {
+  process.env[ENV] = "1";
+}
+
+/** True inside the harbor daemon process (routines, workflows, tasks, live spawns). */
+export function inHarborDaemon(): boolean {
+  return process.env[ENV] === "1";
+}

package/src/harbor/index.ts

@@ -48,6 +48,7 @@ import {
   loadPendingCloud,
   savePendingCloud,
   type PendingCloud,
+  type OutboxKind,
   routineRelayId,
 } from "../routines/store.ts";
 import type { Routine } from "../routines/schema.ts";
@@ -57,8 +58,9 @@ import { resolveMcpSelection, readMcpInventory, type ResolvedMcpTools } from "..
 import { deliver, type RelayPusher, type CloudPusher } from "../routines/delivery.ts";
 import { sealJson, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
-import { startIpcServer, HarborAlreadyRunningError, type IpcRequest, type IpcResponse } from "./ipc.ts";
+import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
 import { isHosted, publishRelayPub, webEnabled } from "../config/hosted.ts";
+import { markHarborDaemon } from "../config/harborDaemon.ts";
 import { makeWebTools, WEB_TOOL_NAMES } from "../tools/web.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
@@ -282,6 +284,11 @@ export class Harbor {
   };
 
   async start(): Promise<void> {
+    // Mark the process before anything can create a session: the shipped TUI extensions
+    // are auto-discovered from the shared agent dir into every session we run, and the
+    // gate one has to stand its relay file tools down here so a live task's own pair
+    // (bound to that task's live relay) isn't shadowed. See config/harborDaemon.ts.
+    markHarborDaemon();
     // Single-instance lock FIRST, before any other side effect: binding the IPC
     // socket is the machine's mutex. If a live harbor already holds it this throws
     // HarborAlreadyRunningError — two harbors under one ~/.privateer share a single
@@ -596,7 +603,7 @@ export class Harbor {
     return this.originCache;
   }
 
-  private async postOutbox(name: string, at: string, status: "ok" | "error", content: string, kind: "routine" | "task" = "routine"): Promise<boolean> {
+  private async postOutbox(name: string, at: string, status: "ok" | "error", content: string, kind: OutboxKind = "routine"): Promise<boolean> {
     const pub = await this.ensureOutboxPub();
     if (!pub) return false;
     const body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
@@ -807,6 +814,16 @@ export class Harbor {
               // Privateer's TEE-channel models (near/tinfoil/phala) as "◆ Verifiable TEE"
               // when logged in; ZDR-channel models stay at their honest floor. The live
               // verdict still comes from accountPosture on select — this only lifts the label.
+              //
+              // ORDER MATTERS: pi-privacy's own catalog registers a `privateer`
+              // provider (its PUBLIC developer-key channel, one seed model), and Pi's
+              // registerProvider REPLACES a provider's models and request config. It
+              // must stay ABOVE makeAccountProvider() so the ACCOUNT channel lands last
+              // — otherwise the default model stops resolving and requests go to
+              // api.privateer.pro/v1 instead of /api/agent/v1. (The TUI hits this
+              // through extension discovery, where the order isn't ours to choose;
+              // extensions/privateer-privacy.ts re-asserts the account registration
+              // there. See registerAccountModels.)
               makePiPrivacyExtension({
                 privateerVerifiedTee: (m) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
               }),
@@ -1037,6 +1054,19 @@ export class Harbor {
           parseSpec,
           log,
           onClosed: (id) => this.liveTasks.delete(id),
+          // A live spawn's feed lives only in the attached app; when the session ends
+          // (closed, reaped, or timed out) its answer would otherwise be gone. Seal the
+          // closing one to the outbox like a submitted task's, so the app's inbox holds
+          // every agent result, not just the unattended ones. Same queue-on-failure path.
+          onResult: ({ title, status, content }) => {
+            void (async () => {
+              const at = new Date().toISOString();
+              const body = redactText(content, collectSecrets(loadHarborConfig().providers));
+              if (!(await this.postOutbox(title, at, status, body, "task"))) {
+                addPendingCloud({ routine: title, at, status, content: body, kind: "task" });
+              }
+            })();
+          },
         });
         this.liveTasks.set(handle.termId, handle);
         this.relay?.sendTaskSpawned(handle.termId, handle.label);
@@ -1101,8 +1131,8 @@ export class Harbor {
       const content = formatWorkflowResult(wf.workflow.name, result);
       const at = new Date().toISOString();
       // Durable delivery: seal to the outbox (queue on failure to re-seal later).
-      if (!(await this.postOutbox(wf.workflow.name, at, status, content, "task"))) {
-        addPendingCloud({ routine: wf.workflow.name, at, status, content, kind: "task" });
+      if (!(await this.postOutbox(wf.workflow.name, at, status, content, "workflow"))) {
+        addPendingCloud({ routine: wf.workflow.name, at, status, content, kind: "workflow" });
       }
       if (this.controllerAttached) this.relay?.sendWorkflowResult(wf.workflow.name, content);
       log(`  workflow "${wf.workflow.name}" ${result.status}${result.reason ? `: ${result.reason}` : ""}`);
@@ -1192,6 +1222,31 @@ export class Harbor {
     return { text: notes.length > 0 ? `${out}${formatNotes(notes)}` : out, output, status, error };
   }
 
+  // What the app can actually see. A harbor is only drivable while its relay socket
+  // is up, and every way that can fail — signed out, turned off from the app, refused
+  // by the plan's agent cap, a socket that died without closing — used to be visible
+  // ONLY as a line in a log file nobody reads. Reported alongside pid/uptime so
+  // `privateer harbor status` can never again say "running" about a harbor the app
+  // shows as offline.
+  private relayStatus(): RelayStatus {
+    const termId = routineRelayId();
+    if (this.relayTerminated) {
+      return { termId, connected: false, detail: "remote access was turned off from the app — restart the harbor to re-enable it" };
+    }
+    if (!this.relay) {
+      return {
+        termId,
+        connected: false,
+        detail: hasCredentials()
+          ? "relay not started"
+          : "no account signed in on this machine — run `privateer` and /login, then restart the harbor",
+      };
+    }
+    const conn = this.relay.connectionStatus();
+    if (!conn.connected) return { termId, connected: false, detail: "connecting…" };
+    return { termId, connected: true, upSec: conn.upSec, quietSec: conn.quietSec };
+  }
+
   private persistRun(id: string, patch: Partial<Routine>): void {
     const current = findRoutine(loadRoutines(), id);
     if (!current) return;
@@ -1201,7 +1256,13 @@ export class Harbor {
   private async handleIpc(req: IpcRequest): Promise<IpcResponse> {
     switch (req.cmd) {
       case "status":
-        return { ok: true, pid: process.pid, uptimeSec: Math.round((Date.now() - this.startedAt) / 1000), routines: loadRoutines() };
+        return {
+          ok: true,
+          pid: process.pid,
+          uptimeSec: Math.round((Date.now() - this.startedAt) / 1000),
+          relay: this.relayStatus(),
+          routines: loadRoutines(),
+        };
       case "list":
         return { ok: true, routines: loadRoutines() };
       case "add": {
@@ -1254,11 +1315,29 @@ export function runHarbor(): void {
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  harbor.start().catch((err) => {
+  harbor.start().catch(async (err) => {
     if (err instanceof HarborAlreadyRunningError) {
       // A resident harbor already owns this machine — leave it in charge. Exit 0 so a
       // manual `privateer harbor run` beside the installed login service isn't an error.
+      //
+      // Say WHICH harbor, and whether it is actually reachable from the app: the
+      // incumbent can be a stale process that still answers IPC while its relay socket
+      // is long dead, and "leaving the existing one in charge" then reads as reassurance
+      // for a harbor the app shows as offline. The incumbent knows — ask it.
       process.stderr.write("A Harbor is already running on this machine — leaving the existing one in charge.\n");
+      try {
+        const status = await sendToHarbor({ cmd: "status" }, 3_000);
+        const up = typeof status.uptimeSec === "number" ? `, up ${formatDuration(status.uptimeSec)}` : "";
+        process.stderr.write(`  incumbent: pid ${status.pid ?? "?"}${up}\n`);
+        process.stderr.write(`  relay:     ${describeRelay(status.relay)}\n`);
+        if (status.relay && !status.relay.connected) {
+          process.stderr.write("  Stop that process (or `privateer harbor uninstall && privateer harbor install`) to hand the machine to a fresh Harbor.\n");
+        }
+      } catch {
+        // It held the lock a moment ago but won't answer now — a wedged process is
+        // worth naming too, since nothing else will start while it holds the socket.
+        process.stderr.write("  incumbent: holds the lock but is not answering IPC — it may be wedged; stop it and start again.\n");
+      }
       process.exit(0);
     }
     process.stderr.write(`Harbor failed to start: ${err instanceof Error ? err.message : String(err)}\n`);

package/src/harbor/ipc.ts

@@ -22,6 +22,28 @@ export type IpcRequest =
   | { cmd: "run-now"; idOrName: string }
   | { cmd: "reload" };
 
+/**
+ * The harbor's view of its own relay connection, reported by `status`.
+ *
+ * A harbor answering on this socket is running; that is NOT the same as being
+ * reachable from the app, which needs the relay socket up (the server drops a
+ * terminal from its presence registry ~60s after it stops hearing from it). The two
+ * used to be conflated — "running (answering IPC)" while the app showed the same
+ * harbor as offline — so every liveness report carries both now.
+ */
+export interface RelayStatus {
+  /** The relay terminal id the app looks for ("routines-…"). */
+  termId: string;
+  /** Socket open right now, i.e. the app can see and drive this harbor. */
+  connected: boolean;
+  /** Seconds the current connection has been up. */
+  upSec?: number;
+  /** Seconds since the server last sent anything (frame, ping or pong). */
+  quietSec?: number;
+  /** Why it isn't connected, when we know: signed out, turned off from the app, … */
+  detail?: string;
+}
+
 export interface IpcResponse {
   ok: boolean;
   message?: string;
@@ -29,6 +51,8 @@ export interface IpcResponse {
   // Harbor liveness/uptime for `status`.
   pid?: number;
   uptimeSec?: number;
+  // Relay reachability for `status` — see RelayStatus.
+  relay?: RelayStatus;
 }
 
 export type IpcHandler = (req: IpcRequest) => Promise<IpcResponse> | IpcResponse;
@@ -164,6 +188,32 @@ export class HarborAlreadyRunningError extends Error {
   }
 }
 
+// One-line, human rendering of a status reply's relay block — shared by
+// `privateer harbor status` and the second-instance notice so both tell the same
+// story. `undefined` means the harbor answering us predates this field.
+export function describeRelay(relay?: RelayStatus): string {
+  if (!relay) return "unknown (this harbor is an older build)";
+  if (!relay.connected) {
+    return `NOT connected — the app shows this Harbor as inactive${relay.detail ? ` (${relay.detail})` : ""}`;
+  }
+  const up = typeof relay.upSec === "number" ? `, up ${formatDuration(relay.upSec)}` : "";
+  // A connected socket the server hasn't spoken on in a while is the half-open shape;
+  // the watchdog drops it within ~75s, so say so rather than reporting a flat "connected".
+  const quiet = typeof relay.quietSec === "number" && relay.quietSec > 40 ? `, quiet for ${relay.quietSec}s — checking` : "";
+  return `connected — drivable from the Privateer app (${relay.termId}${up}${quiet})`;
+}
+
+export function formatDuration(totalSec: number): string {
+  const s = Math.max(0, Math.round(totalSec));
+  const d = Math.floor(s / 86400);
+  const h = Math.floor((s % 86400) / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (d) return `${d}d ${h}h`;
+  if (h) return `${h}h ${m}m`;
+  if (m) return `${m}m`;
+  return `${s}s`;
+}
+
 // Convenience: is the harbor reachable right now?
 export async function harborIsRunning(): Promise<boolean> {
   try {

package/src/harbor/service.ts

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globalDir } from "../config/paths.ts";
-import { harborIsRunning } from "./ipc.ts";
+import { harborIsRunning, sendToHarbor, describeRelay, formatDuration, type IpcResponse } from "./ipc.ts";
 
 const LABEL = "pro.privateer.harbor"; // launchd label / reverse-dns id
 const UNIT = "privateer-harbor.service"; // systemd --user unit name
@@ -62,7 +62,13 @@ function xmlEscape(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function launchdPlist(): string {
+// KeepAlive is `{ SuccessfulExit: false }`, NOT plain `true` — restart on a crash,
+// but leave a CLEAN exit alone. A bare `true` restarts unconditionally, which turns
+// the two clean-exit paths into loops: the harbor that finds another one already
+// holding the machine lock (exit 0 every ~10s, appending the same line to harbor.log
+// forever — this is what produced a 7 MB log of "already running"), and a deliberate
+// shutdown, which launchd would undo. Matches the systemd unit's Restart=on-failure.
+export function launchdPlist(): string {
   const args = [nodeBinaryPath(), harborLauncherPath(), "run"];
   const envVars = forwardedEnv();
   const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
@@ -83,7 +89,10 @@ ${argXml}
 ${envVars.PRIVATEER_HOME || envVars.PRIVATEER_SERVER_URL ? `  <key>EnvironmentVariables</key>\n  <dict>\n${envXml}\n  </dict>\n` : ""}  <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <true/>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
   <key>StandardOutPath</key>
   <string>${log}</string>
   <key>StandardErrorPath</key>
@@ -199,6 +208,24 @@ export interface ServiceInfo {
   installed: boolean;
   unitPath: string;
   logPath: string;
+  /** Installed unit predates a fix and should be rewritten — see needsRefresh(). */
+  needsRefresh: boolean;
+}
+
+// Does the INSTALLED unit need rewriting? Deliberately narrow: a full text compare
+// against what we'd generate today would flag every service installed by a different
+// copy of the CLI (a dev checkout resolves a different launcher path), which is not a
+// problem and not something the user should be nagged about. The one thing worth
+// flagging is the pre-fix launchd `KeepAlive: true`, which restarts the harbor even
+// after a clean exit — the log-spam loop described above launchdPlist().
+export function unitNeedsRefresh(platform: NodeJS.Platform, unitPath: string): boolean {
+  if (platform !== "darwin" || !existsSync(unitPath)) return false;
+  try {
+    const plist = readFileSync(unitPath, "utf8");
+    return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(plist);
+  } catch {
+    return false;
+  }
 }
 
 function unitPathFor(platform: NodeJS.Platform): string {
@@ -216,6 +243,7 @@ export function serviceInfo(): ServiceInfo {
     installed: !!unitPath && existsSync(unitPath),
     unitPath,
     logPath: harborLogPath(),
+    needsRefresh: unitNeedsRefresh(platform, unitPath),
   };
 }
 
@@ -236,20 +264,40 @@ export function uninstallService(): ServiceInfo {
   return serviceInfo();
 }
 
-// Human-readable status line for `privateer harbor status`: whether the service is
-// installed AND whether a harbor is actually answering on the IPC socket right now.
+// Human-readable status for `privateer harbor status`: whether the service is
+// installed, whether a harbor is answering on the IPC socket, and — the part that
+// actually answers "why does the app say inactive?" — whether that harbor is
+// connected to the relay. Answering IPC only proves a local process is alive; the
+// app lists a harbor from the server's presence registry, which a dead relay socket
+// drops within ~60s. Reporting the first as if it implied the second is what made a
+// stale harbor look healthy from the terminal and offline from the phone.
 export async function statusReport(): Promise<string> {
   const info = serviceInfo();
-  const live = await harborIsRunning();
+  let status: IpcResponse | null = null;
+  try {
+    status = await sendToHarbor({ cmd: "status" }, 3_000);
+  } catch {
+    status = null; // not running, or wedged — harborIsRunning() below tells them apart
+  }
+  const live = status ? status.ok : await harborIsRunning();
+  const up = status && typeof status.uptimeSec === "number" ? `, up ${formatDuration(status.uptimeSec)}` : "";
+  const pid = status?.pid ? `pid ${status.pid}${up}` : "answering IPC";
   const lines = [
     `platform:  ${info.platform}${info.supported ? "" : " (auto-start unsupported — run `privateer harbor` manually)"}`,
     `service:   ${info.installed ? `installed (${info.unitPath})` : "not installed"}`,
-    `harbor:    ${live ? "running (answering IPC)" : "not reachable"}`,
-    `logs:      ${info.logPath}`,
+    `harbor:    ${live ? `running (${pid})` : "not reachable"}`,
   ];
+  if (live) lines.push(`relay:     ${describeRelay(status?.relay)}`);
+  lines.push(`logs:      ${info.logPath}`);
   // Surface a stale-unit hint: file present but nothing answering usually means it
   // failed to boot — the log path above is where to look.
   if (info.installed && !live) lines.push("hint:      service is installed but not answering — check the log for a boot error.");
+  if (live && status?.relay && !status.relay.connected) {
+    lines.push("hint:      Harbor is running but not reachable from the app. Restart it (`privateer harbor uninstall && privateer harbor install`) once the cause above is resolved.");
+  }
+  if (info.needsRefresh) {
+    lines.push("hint:      the installed login service restarts Harbor even after a clean exit (older install) — run `privateer harbor install` to refresh it.");
+  }
   return lines.join("\n");
 }
 

package/src/providers/account.ts

@@ -429,6 +429,51 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
   }
 }
 
+// A model entry, with a per-model baseUrl override once the EHBP shim is listening:
+// `tinfoil/*` then route through the loopback shim (which seals to the blind relay)
+// instead of the cleartext `/api/agent/v1` proxy. Everything else keeps the provider
+// baseUrl. Until the shim is up (or when sealed mode is off) sealed models fall back to
+// the cleartext path — and the badge stays honestly `tee-unverified` (see accountPosture).
+function modelEntry(id: string) {
+  const base = seedModel(id);
+  const provider = sealedEnabled() ? sealedProviderFor(id) : null;
+  const shim = sealedShimBase();
+  return provider && shim ? { ...base, baseUrl: `${shim}/${provider}/v1` } : base;
+}
+
+// The Pi provider config for the account channel, over a given set of model ids.
+export function accountProviderConfig(ids: string[]): Record<string, unknown> {
+  return {
+    name: "Privateer account",
+    baseUrl: `${serverBaseUrl()}/api/agent/v1`,
+    api: "openai-completions",
+    oauth: privateerOAuthProvider,
+    models: ids.map(modelEntry),
+  };
+}
+
+// Re-assert the account channel's registration from ANOTHER extension.
+//
+// pi-privacy also ships a `privateer` provider (its PRIVACY_PROVIDERS catalog) — the
+// PUBLIC developer-key channel: baseUrl api.privateer.pro/v1, `${PRIVATEER_API_KEY}`,
+// and a single seed model (near/zai-org/GLM-5.1-FP8). Pi's registerProvider FULLY
+// REPLACES a provider's model list and its request config, so whichever registration
+// lands last wins — and pi extensions are discovered with an unsorted readdirSync, which
+// on a typical box puts privateer-privacy after privateer-account. The account channel's
+// whole catalog was then replaced by that one model, so the default `tinfoil/glm-5-2` no
+// longer resolved ("not found for provider privateer. Using custom model id") and the
+// synthesized model inherited the PUBLIC endpoint instead of `/api/agent/v1`.
+//
+// So privateer-privacy.ts calls this right after pi-privacy runs, exactly as it re-widens
+// `tinfoil`. Idempotent and order-independent: if privacy happens to load first, the
+// account extension's own registration lands afterwards with the same config, and the
+// live-catalog fetch re-registers over both moments later either way.
+export function registerAccountModels(pi: {
+  registerProvider?: (name: string, config: unknown) => void;
+}): void {
+  pi.registerProvider?.("privateer", accountProviderConfig(seedCatalogIds()));
+}
+
 // Extension factory: registers the account provider so `/login` can offer it.
 //
 // We register UNCONDITIONALLY (not only when a machine login already exists). Pi's
@@ -454,31 +499,13 @@ export function makeAccountProvider() {
     on?: (event: string, handler: (e: unknown, ctx: unknown) => void) => void;
   }): void => {
     if (typeof pi.registerProvider !== "function") return;
-    // A model entry, with a per-model baseUrl override for sealed models once the
-    // EHBP shim is listening: `tinfoil/*` then route through the loopback shim (which
-    // seals to the blind relay) instead of the cleartext `/api/agent/v1` proxy.
-    // Everything else keeps the provider baseUrl below. Until the shim is up (or when
-    // sealed mode is off) sealed models fall back to the cleartext path — and the
-    // badge stays honestly `tee-unverified` (see accountPosture).
-    const modelEntry = (id: string) => {
-      const base = seedModel(id);
-      const provider = sealedEnabled() ? sealedProviderFor(id) : null;
-      const shim = sealedShimBase();
-      return provider && shim ? { ...base, baseUrl: `${shim}/${provider}/v1` } : base;
-    };
     // Seed with the last live catalog when we have one (see seedCatalogIds): this is the
     // list Pi resolves a saved default / a restored session model against at launch,
     // before the live re-registration can reach the registry.
     let lastIds: string[] = seedCatalogIds();
     const register = (ids: string[]): void => {
       lastIds = ids;
-      pi.registerProvider!("privateer", {
-        name: "Privateer account",
-        baseUrl: `${serverBaseUrl()}/api/agent/v1`,
-        api: "openai-completions",
-        oauth: privateerOAuthProvider,
-        models: ids.map(modelEntry),
-      });
+      pi.registerProvider!("privateer", accountProviderConfig(ids));
     };
     register(lastIds); // immediate: provider exists this tick, with a resolvable catalog
     // Bring up the sealed shim, then re-register so sealed models pick up their shim

package/src/remote/liveTaskSession.ts

@@ -28,6 +28,8 @@ import {
 } from "../providers/account.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
+import { makeRelayFileTools } from "../tools/relayFileTools.ts";
+import { AttachmentStore, type StoredAttachment } from "../util/attachmentStore.ts";
 import { spawnAccountCredentials, revokeAccountSession, hasCredentials } from "../auth/privateer.ts";
 
 export interface LiveTaskHandle {
@@ -41,6 +43,11 @@ export interface LiveTaskDeps {
   parseSpec: (spec: string) => { provider: string; modelId: string };
   log: (msg: string) => void;
   onClosed: (termId: string) => void;
+  // Deliver the session's closing answer durably (the harbor seals it to the account
+  // outbox, so it lands in the app's inbox). A live spawn's feed is otherwise purely
+  // ephemeral: close the screen, reap the session, and everything it said is gone —
+  // unlike a submitted task or a routine, whose results are always sealed.
+  onResult?: (result: { title: string; status: "ok" | "error"; content: string }) => void;
 }
 
 // How long to keep a spawned session alive with NO controller ever attaching, and the
@@ -72,12 +79,42 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   let attachTimer: ReturnType<typeof setTimeout> | undefined;
   let lifeTimer: ReturnType<typeof setTimeout> | undefined;
 
+  // Files the app sends down mid-session, keyed by the "#n" ref save_attachment writes
+  // back out. `sinceLastPrompt` is drained into the next prompt so the model is told what
+  // it just received — same contract as the TUI's (extensions/privateer-gate.ts).
+  const attachments = new AttachmentStore();
+  let sinceLastPrompt: StoredAttachment[] = [];
+
+  // The assistant text of the most recent turn, accumulated from the event stream and
+  // reset at the start of each one, so what we keep is the session's CLOSING answer
+  // rather than a transcript. Bounded — the outbox truncates anyway, and a long
+  // session's scrollback is not what makes a useful inbox entry.
+  const MAX_RESULT_CHARS = 8000;
+  let lastAnswer = "";
+  let turnErrored = false;
+
   const stop = async (): Promise<void> => {
     if (stopped) return;
     stopped = true;
+    // Hand the closing answer over BEFORE tearing anything down. Best-effort by
+    // design: no answer (nothing ever ran, or the model only used tools) means
+    // nothing to deliver, and a delivery failure must never block teardown.
+    const answer = lastAnswer.trim();
+    if (answer && deps.onResult) {
+      try {
+        deps.onResult({
+          title: title || "Spawned agent",
+          status: turnErrored ? "error" : "ok",
+          content: answer.slice(0, MAX_RESULT_CHARS),
+        });
+      } catch (e) {
+        deps.log(`live task ${termId} result delivery failed: ${(e as Error).message}`);
+      }
+    }
     if (attachTimer) clearTimeout(attachTimer);
     if (lifeTimer) clearTimeout(lifeTimer);
     try { relay?.stop(); } catch { /* already stopped */ }
+    attachments.cleanup(); // drop the scratch dir holding inbound file bytes
     // Revoke ONLY this session's account inference session so it doesn't linger in the
     // app's Linked Devices; the harbor's own child session stays alive. Best-effort.
     if (spawnedAccount) {
@@ -93,9 +130,20 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   const runTurn = async (text: string): Promise<void> => {
     if (turnActive || stopped) return;
     turnActive = true;
+    lastAnswer = "";   // keep the CLOSING answer, not the whole session
+    turnErrored = false;
     try {
-      await session.prompt(text);
+      // Fold any files the app sent since the last prompt into a reference note, so the
+      // model knows they exist and can save_attachment them to disk.
+      const atts = sinceLastPrompt;
+      sinceLastPrompt = [];
+      const note = atts.length
+        ? `\n\n[Files attached from the app: ${atts.map((a) => `#${a.n} ${a.name} (${a.mediaType})`).join(", ")}. ` +
+          `Use the save_attachment tool with the ref number to write one to disk.]`
+        : "";
+      await session.prompt(text + note);
     } catch (e) {
+      turnErrored = true;
       deps.log(`live task ${termId} turn error: ${(e as Error).message}`);
     } finally {
       turnActive = false;
@@ -122,6 +170,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
         bridge.callbacks.onPrompt(spec.prompt);
       }
     },
+    onAttachment: (file) => sinceLastPrompt.push(attachments.register(file)),
     onTerminate: () => void stop(),
     onStatus: (t) => deps.log(`live task ${termId}: ${t}`),
   });
@@ -157,6 +206,11 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
           privateerVerifiedTee: (m) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
         }),
         makeAccountProvider(),
+        // send_file_to_client / save_attachment bound to THIS session's bridge — the one
+        // whose relay the app is attached to. The shipped gate extension is discovered
+        // into this session too but stands its own pair down inside the daemon, so these
+        // are the ones the model gets (see tools/relayFileTools.ts).
+        makeRelayFileTools(bridge, attachments),
       ] as any,
     },
   });
@@ -219,7 +273,12 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
 
   const adapter = createEngineEventAdapter();
   session.subscribe((ev: any) => {
-    for (const ee of adapter.toEngineEvents(ev)) bridge.forwardEvent(ee);
+    for (const ee of adapter.toEngineEvents(ev)) {
+      // Assistant prose only — reasoning, tool calls and results are deliberately not
+      // kept: the inbox entry should read like the agent's answer, not a trace.
+      if (ee.type === "text" && lastAnswer.length < MAX_RESULT_CHARS) lastAnswer += ee.text;
+      bridge.forwardEvent(ee);
+    }
   });
 
   relay = new RelayClient(bridge.callbacks, { termId, label });

package/src/remote/relayClient.ts

@@ -233,6 +233,24 @@ const RECONNECT_MS = 3000;
 // record TTL so the app's "blocked" row stays warm between attempts rather than
 // flickering in and out of the plan-limit state.
 const REFUSED_RECONNECT_MS = 60_000;
+// ── Liveness ────────────────────────────────────────────────────────────────────
+// A TCP socket can die without either side being told: a server instance restarts,
+// a NAT/idle timer drops the flow, a laptop sleeps. The kernel keeps reporting
+// ESTABLISHED, `ws` never fires 'close', and the reconnect path above — which only
+// runs on close/error — never runs. That failure mode is invisible AND permanent:
+// the server prunes the terminal from its presence registry after ~60s, so the app
+// shows the harbor as offline while the harbor's own log says "connected", forever.
+//
+// So don't wait to be told. The server pings every 25s, so an alive socket sees
+// inbound traffic at least that often; we ping on our own timer too (the peer's pong
+// counts as inbound). If nothing arrives for LIVENESS_TIMEOUT_MS — three missed
+// server pings — the socket is dead: terminate it and take the normal reconnect path.
+const HEARTBEAT_MS = 20_000;
+const LIVENESS_TIMEOUT_MS = 75_000;
+// Cap the opening handshake too. Without this a black-holed connect leaves `this.ws`
+// set with no open/close/error ever firing, and connect()'s `if (this.ws) return`
+// guard then blocks every future attempt — the same permanent silence by another route.
+const HANDSHAKE_TIMEOUT_MS = 15_000;
 // File-transfer ceilings for app→CLI attachments. The app enforces its own caps
 // before sending; these are a defensive backstop so a controller can't exhaust
 // memory with a lying `size` or a flood of concurrent transfers.
@@ -291,6 +309,11 @@ export class RelayClient {
   private closed = false;
   private connecting = false;
   private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  // Liveness watchdog for the open socket (see HEARTBEAT_MS): our own ping timer plus
+  // the epoch of the last thing we heard from the server — any frame, ping or pong.
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  private lastInboundAt = 0;
+  private connectedAt = 0;
   // Last refusal reason reported, so a 4xx is logged once instead of on every retry.
   private refusal: string | null = null;
   // Ordered delta buffer (text/reasoning) coalesced into one frame per flush.
@@ -377,6 +400,8 @@ export class RelayClient {
     this.settleFirstConnect(new Error("relay stopped before registering"));
     if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = undefined; }
     if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = undefined; }
+    this.stopHeartbeat();
+    this.connectedAt = 0;
     this.bufKind = null;
     this.buf = "";
     this.incoming.clear();
@@ -417,7 +442,7 @@ export class RelayClient {
       const wsUrl =
         serverBaseUrl().replace(/^http/, "ws") + `/relay?ticket=${encodeURIComponent(ticket)}`;
       this.debug(`connecting → ${wsUrl}`);
-      const ws = new WebSocket(wsUrl);
+      const ws = new WebSocket(wsUrl, { handshakeTimeout: HANDSHAKE_TIMEOUT_MS });
       this.ws = ws;
       let opened = false;
       let lastErr = "";
@@ -425,12 +450,20 @@ export class RelayClient {
       ws.on("open", () => {
         opened = true;
         this.refusal = null; // a later refusal is news again
+        this.connectedAt = Date.now();
+        this.startHeartbeat(ws);
         this.settleFirstConnect(); // terminal is live on the relay — awaitRegistered() resolves
         this.cb.onStatus?.("Remote access connected — drive this terminal from the Privateer app.");
       });
-      ws.on("message", (data) => this.handle(data));
+      // Anything the server sends counts as proof of life for the watchdog. `ws`
+      // answers server pings with a pong for us, and answers our pings with 'pong'.
+      ws.on("message", (data) => { this.lastInboundAt = Date.now(); this.handle(data); });
+      ws.on("ping", () => { this.lastInboundAt = Date.now(); });
+      ws.on("pong", () => { this.lastInboundAt = Date.now(); });
       ws.on("close", () => {
+        this.stopHeartbeat();
         if (this.ws === ws) this.ws = null;
+        this.connectedAt = 0;
         this.cb.onDisconnected?.();
         if (!this.closed) {
           this.cb.onStatus?.(
@@ -484,6 +517,37 @@ export class RelayClient {
     if (process.env.PRIVATEER_RELAY_DEBUG) this.cb.onStatus?.(`relay: ${msg}`);
   }
 
+  // Watch one open socket: ping on a timer, and terminate it if the server has gone
+  // quiet for longer than any healthy connection ever is (see LIVENESS_TIMEOUT_MS).
+  // `terminate()` (not close()) because the point is that the peer may be gone — a
+  // close handshake would wait for a reply that never comes. The 'close' it fires
+  // takes the ordinary reconnect path, so recovery needs no separate machinery.
+  private startHeartbeat(ws: WebSocket): void {
+    this.stopHeartbeat();
+    this.lastInboundAt = Date.now();
+    this.heartbeatTimer = setInterval(() => {
+      // A socket we've since replaced or dropped isn't ours to police anymore.
+      if (this.ws !== ws) { this.stopHeartbeat(); return; }
+      if (ws.readyState !== WebSocket.OPEN) return; // closing — 'close' will clean up
+      const quietMs = Date.now() - this.lastInboundAt;
+      if (quietMs > LIVENESS_TIMEOUT_MS) {
+        this.cb.onStatus?.(
+          `Remote access went silent for ${Math.round(quietMs / 1000)}s (the connection died without closing) — dropping it and reconnecting…`,
+        );
+        this.stopHeartbeat();
+        try { ws.terminate(); } catch (_) { /* already gone — 'close' still fires */ }
+        return;
+      }
+      try { ws.ping(); } catch (_) { /* socket dying — the next tick or 'close' handles it */ }
+    }, HEARTBEAT_MS);
+    // Never hold the process open for a heartbeat alone.
+    this.heartbeatTimer.unref?.();
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = undefined; }
+  }
+
   private scheduleReconnect(delayMs: number = RECONNECT_MS): void {
     if (this.closed || this.reconnectTimer) return;
     this.reconnectTimer = setTimeout(() => {
@@ -746,6 +810,21 @@ export class RelayClient {
     return this.ws?.readyState === WebSocket.OPEN;
   }
 
+  // Connection health, for `privateer harbor status` / the IPC status reply. `quietSec`
+  // is how long since the server last said anything: a connected socket that has been
+  // quiet for longer than the server's 25s ping cadence is the shape of the half-open
+  // failure the watchdog exists to catch, so it is worth showing rather than a bare
+  // "connected".
+  connectionStatus(): { connected: boolean; upSec?: number; quietSec?: number } {
+    if (!this.isConnected()) return { connected: false };
+    const now = Date.now();
+    return {
+      connected: true,
+      upSec: this.connectedAt ? Math.round((now - this.connectedAt) / 1000) : undefined,
+      quietSec: this.lastInboundAt ? Math.round((now - this.lastInboundAt) / 1000) : undefined,
+    };
+  }
+
   // Push a finished routine result to any attached controller as a text event, so
   // it renders in the app's live feed. Returns whether the socket was open to send
   // on; a durable channel (file/notice) still backs this up, since we can't know

package/src/routines/store.ts

@@ -204,6 +204,11 @@ export function drainPendingRelay(): PendingRelay[] {
   return queue;
 }
 
+// What produced a result delivered to the account outbox. Travels inside the sealed
+// envelope, so the app can label and filter its inbox without the server learning
+// anything. Kept here (not in the harbor) because the pending-cloud queue persists it.
+export type OutboxKind = "routine" | "task" | "workflow";
+
 // A `cloud`-delivery result that couldn't be sealed+posted to the account outbox
 // yet (offline, server down, or the app hasn't published its outbox key). Held on
 // disk until a later flush succeeds. Unlike PendingRelay this carries `status`, so
@@ -214,9 +219,10 @@ export interface PendingCloud {
   status: "ok" | "error";
   content: string;
   // What produced this — a scheduled routine (default, for back-compat with items
-  // written before ad-hoc tasks existed) or an app-submitted one-shot task. Preserved
-  // so the flush re-seals with the right `kind` and the app labels it correctly.
-  kind?: "routine" | "task";
+  // written before ad-hoc tasks existed), an app-submitted one-shot task, or a
+  // workflow run. Preserved so the flush re-seals with the right `kind` and the app
+  // labels it correctly in the inbox.
+  kind?: OutboxKind;
 }
 
 function pendingCloudPath(): string {

package/src/tools/relayFileTools.ts

@@ -0,0 +1,24 @@
+// The two relay file tools as a Pi extension factory bound to ONE specific bridge.
+//
+// `send_file_to_client` / `save_attachment` are normally registered by the shipped TUI
+// extension (extensions/privateer-gate.ts), against that extension's module-level
+// RemoteBridge — the one `/remote-access` attaches a relay to. That is right for the TUI
+// and wrong everywhere else: the extension is AUTO-DISCOVERED from ~/.privateer/agent/
+// extensions into every session that shares the agent dir, including the sessions the
+// harbor daemon stands up (live task spawns), which own their OWN bridge + relay. Pi
+// resolves duplicate tool names first-registration-wins and loads discovered extensions
+// before inline factories, so the discovered pair would shadow a session's own and answer
+// "remote access is off" while the session's relay is connected and driving.
+//
+// Hence this factory: a session that has its own bridge registers the pair here, and the
+// gate extension stands down inside the daemon (PRIVATEER_HARBOR_DAEMON).
+import { makeSendFileTool, type SendFileBridge } from "./sendFile.ts";
+import { makeSaveAttachmentTool } from "./saveAttachment.ts";
+import type { AttachmentStore } from "../util/attachmentStore.ts";
+
+export function makeRelayFileTools(bridge: SendFileBridge, attachments: AttachmentStore) {
+  return function relayFileTools(pi: any): void {
+    pi.registerTool?.(makeSendFileTool(bridge));
+    pi.registerTool?.(makeSaveAttachmentTool(attachments));
+  };
+}