privateer-agent 0.9.0 → 0.9.1

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.1",
   "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/harbor/index.ts

@@ -57,7 +57,7 @@ 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 { makeWebTools, WEB_TOOL_NAMES } from "../tools/web.ts";
 
@@ -807,6 +807,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",
               }),
@@ -1192,6 +1202,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 +1236,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 +1295,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/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