privateer-agent 0.8.2 → 0.9.1

package/src/remote/mcpControl.ts

@@ -15,13 +15,22 @@
  * means a machine has ONE coherent MCP config whether it was edited from the desktop
  * over IPC or from the phone over the relay.
  *
- * SECRETS: MCP env values are credentials (GITHUB_PERSONAL_ACCESS_TOKEN, …). Over the
- * untrusted relay they are WRITE-ONLY, exactly like channel bot tokens: list() NEVER
- * returns an env VALUE — only which env keys exist (`envKeys`) and which are non-empty
- * (`secretsSet`), by name. save() persists whatever env VALUES it is handed in
- * `draft.env`; the seal/open of those values in transit is the caller's job (the
- * harbor opens a sealed-box addressed to its terminal, mirroring applyChannelSave), so
- * this module only ever deals in the plaintext files it already owns.
+ * SECRETS: MCP env values are credentials (GITHUB_PERSONAL_ACCESS_TOKEN, …), and so
+ * are a `bearerToken` and every HTTP header VALUE (an `Authorization:` header is a
+ * credential by construction). Over the untrusted relay all three are WRITE-ONLY,
+ * exactly like channel bot tokens: list() NEVER returns one — only which keys exist
+ * (`envKeys` / `headerKeys`) and which are non-empty (`secretsSet` / `headersSet`),
+ * by name, plus a `bearerTokenSet` boolean. `bearerTokenEnv` IS returned: it is a
+ * variable NAME, not a value. save() persists whatever values it is handed; the
+ * seal/open of those values in transit is the caller's job (the harbor opens a
+ * sealed-box addressed to its terminal, mirroring applyChannelSave, and REFUSES a
+ * secret that arrived unsealed), so this module only ever deals in the plaintext files
+ * it already owns.
+ *
+ * SCOPE — bearer tokens are a LOCAL/DESKTOP capability. A hosted (Harbor) agent gets
+ * OAuth connectors only, because its home is tmpfs and a durable secret would have to
+ * rest somewhere we can read; see treeview/docs/HARBOR_CONNECTORS_PLAN.md §2, decided
+ * Option B. Nothing here may become the mechanism for storing a hosted credential.
  *
  * Framework-agnostic: nothing here imports React or the relay. The caller owns the
  * frame plumbing and the sealed-secret open.
@@ -32,6 +41,13 @@ import { agentDir } from "../config/paths.ts";
 
 export type McpTransport = "stdio" | "http";
 
+/**
+ * How an HTTP connector authenticates — our vocabulary, projected onto the adapter's
+ * `auth` field. "none" is a server that needs no credential at all (or carries one
+ * entirely in custom headers); stdio connectors are always "none".
+ */
+export type McpAuth = "oauth" | "bearer" | "none";
+
 // One server as stored in the source file (mcp-desktop.json). Mirrors the desktop's
 // SourceEntry: the standard fields the adapter needs plus our `enabled` flag.
 interface SourceEntry {
@@ -40,6 +56,13 @@ interface SourceEntry {
   args?: string[];
   env?: Record<string, string>;
   url?: string;
+  headers?: Record<string, string>;
+  auth?: McpAuth;
+  bearerToken?: string;
+  bearerTokenEnv?: string;
+  // LEGACY, read-only: entries written before `auth` existed carry a boolean here.
+  // authOf() folds it in; nothing new ever writes it, and project() never emits it
+  // (the adapter's own `oauth` field is an OAuthConfig object, not a boolean).
   oauth?: boolean;
   enabled?: boolean;
 }
@@ -47,6 +70,30 @@ interface SourceFile {
   servers: Record<string, SourceEntry>;
 }
 
+const AUTHS: readonly McpAuth[] = ["oauth", "bearer", "none"];
+function isAuth(v: unknown): v is McpAuth {
+  return typeof v === "string" && AUTHS.includes(v as McpAuth);
+}
+
+// What this entry will actually do when it connects. Explicit `auth` wins; a bearer
+// token implies bearer; a legacy `oauth: false` means no auth; otherwise HTTP servers
+// auto-detect OAuth, which is the adapter's own default.
+//
+// The headers rule mirrors pi-mcp-adapter's supportsOAuth(): "configured custom headers
+// take precedence over implicit OAuth auto-detection." Without this we'd project an
+// EXPLICIT auth:"oauth" for a headers-carrying entry, and the adapter checks
+// auth === "oauth" BEFORE its headers check — so we'd force OAuth on exactly the
+// connectors it means to skip it for. Only implicit auth defers to headers; an explicit
+// `auth` from the user still wins.
+function authOf(e: SourceEntry, transport: McpTransport): McpAuth {
+  if (transport !== "http") return "none";
+  if (isAuth(e.auth)) return e.auth;
+  if (e.bearerToken || e.bearerTokenEnv) return "bearer";
+  if (e.oauth === false) return "none";
+  if (e.headers && Object.keys(e.headers).length > 0) return "none";
+  return "oauth";
+}
+
 // Non-secret projection of one server, sent to the app. No env VALUES, ever — only
 // which env keys exist and which are set (`secretsSet`). `host` is surfaced for the
 // app's privacy badge ("Sends data to <host>" for http; stdio runs locally).
@@ -58,23 +105,36 @@ export interface RemoteMcpServer {
   argsPreview?: string; // stdio: args joined, for a one-line summary
   url?: string; // http: the endpoint (not a secret; the vendor host)
   host?: string; // http: parsed host for the privacy badge
-  oauth: boolean; // http servers negotiate OAuth; stdio never does
+  auth: McpAuth; // what this connector will actually do to authenticate
+  // Kept for app builds that predate `auth`. True only for a real OAuth connector —
+  // it used to mean "is an http server", which claimed OAuth for bearer/no-auth ones.
+  oauth: boolean;
   envKeys: string[]; // env var NAMES only (e.g. ["GITHUB_PERSONAL_ACCESS_TOKEN"])
   secretsSet: string[]; // subset of envKeys whose value is non-empty — names only
+  headerKeys: string[]; // http: header NAMES only — values are credentials
+  headersSet: string[]; // subset of headerKeys whose value is non-empty — names only
+  bearerTokenSet: boolean; // http: a static bearer token is stored (never its value)
+  bearerTokenEnv?: string; // http: the env var the token is read from — a NAME, safe
 }
 
-// An app-submitted edit. Non-secret fields REPLACE when present; `env` maps a var
-// name → its (already-opened) value, and only present, non-empty values overwrite —
-// an omitted key keeps the existing value (so a re-save without re-typing the token
-// preserves it, matching the channels-manager rule).
+// An app-submitted edit. Non-secret fields REPLACE when present; `env` and `headers`
+// map a key → its (already-opened) value, and only present, non-empty values
+// overwrite — an omitted key keeps the existing value (so a re-save without re-typing
+// the token preserves it, matching the channels-manager rule), while an explicit
+// empty string clears it. `bearerToken` follows the same rule as a single value.
 export interface McpDraft {
   name: string;
   transport?: McpTransport;
   command?: string;
   args?: string[];
   url?: string;
+  auth?: McpAuth;
+  // Legacy alias for `auth` — true → "oauth", false → "none". `auth` wins if both.
   oauth?: boolean;
   env?: Record<string, string>;
+  headers?: Record<string, string>;
+  bearerToken?: string;
+  bearerTokenEnv?: string;
 }
 
 export interface McpControl {
@@ -147,21 +207,65 @@ export function makeMcpControl(opts?: {
   // Project the enabled servers into the standard mcp.json the adapter reads. An
   // entry with no explicit transport is treated as stdio if it has a command, http
   // if it has a url — matching the adapter's own inference.
+  //
+  // `toolPrefix` is pinned rather than left to the adapter's default because a
+  // routine's "<server>__<tool>" selector is translated into a REGISTERED tool name
+  // before it can grant anything (src/mcp/toolNames.ts), and that translation depends
+  // on the mode. "server" is the adapter's own default, so pinning it changes nothing
+  // today and stops a future default flip from silently voiding every allow-list.
   function project(src: SourceFile): void {
     const mcpServers: Record<string, unknown> = {};
     for (const [name, e] of Object.entries(src.servers)) {
       if (e.enabled === false) continue;
-      const { enabled, ...std } = e;
-      mcpServers[name] = std;
+      mcpServers[name] = toStandard(e);
     }
     mkdirSync(dirname(projectionPath()), { recursive: true });
-    writeFileSync(projectionPath(), JSON.stringify({ mcpServers }, null, 2) + "\n");
+    writeFileSync(
+      projectionPath(),
+      JSON.stringify({ mcpServers, settings: { toolPrefix: "server" } }, null, 2) + "\n",
+    );
+  }
+
+  // One managed entry as pi-mcp-adapter's ServerEntry. Built field by field rather
+  // than spread, because our vocabulary and the adapter's differ in two places that
+  // matter: our `auth: "none"` is its `auth: false`, and our legacy boolean `oauth`
+  // collides with its `oauth` (an OAuthConfig OBJECT) and must never reach the file.
+  //
+  // Getting `auth` right is load-bearing, not cosmetic. The adapter only attaches an
+  // Authorization header when `auth === "bearer"` (server-manager.ts), and its
+  // supportsOAuth() refuses OAuth outright once custom headers are configured — so an
+  // omitted `auth` silently means "no bearer token was ever sent".
+  function toStandard(e: SourceEntry): Record<string, unknown> {
+    const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
+    const std: Record<string, unknown> = {};
+    if (transport === "stdio") {
+      if (e.command) std.command = e.command;
+      if (e.args?.length) std.args = e.args;
+    } else {
+      if (e.url) std.url = e.url;
+      if (e.headers && Object.keys(e.headers).length > 0) std.headers = e.headers;
+      const auth = authOf(e, transport);
+      if (auth === "bearer") {
+        std.auth = "bearer";
+        if (e.bearerToken) std.bearerToken = e.bearerToken;
+        if (e.bearerTokenEnv) std.bearerTokenEnv = e.bearerTokenEnv;
+      } else if (auth === "oauth") {
+        std.auth = "oauth";
+      } else {
+        std.auth = false;
+      }
+    }
+    if (e.env && Object.keys(e.env).length > 0) std.env = e.env;
+    return std;
   }
 
   function toRemote(name: string, e: SourceEntry): RemoteMcpServer {
     const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
     const env = e.env ?? {};
     const envKeys = Object.keys(env);
+    const headers = transport === "http" ? e.headers ?? {} : {};
+    const headerKeys = Object.keys(headers);
+    const auth = authOf(e, transport);
     return {
       name,
       transport,
@@ -170,13 +274,36 @@ export function makeMcpControl(opts?: {
       argsPreview: transport === "stdio" && e.args?.length ? e.args.join(" ") : undefined,
       url: transport === "http" ? e.url : undefined,
       host: transport === "http" && e.url ? hostOf(e.url) : undefined,
-      // http servers negotiate OAuth; stdio never does (matches mcpService.list()).
-      oauth: transport === "http",
+      auth,
+      oauth: auth === "oauth",
       envKeys,
       secretsSet: envKeys.filter((k) => String(env[k] ?? "").length > 0),
+      headerKeys,
+      headersSet: headerKeys.filter((k) => String(headers[k] ?? "").length > 0),
+      bearerTokenSet: transport === "http" && String(e.bearerToken ?? "").length > 0,
+      bearerTokenEnv: transport === "http" ? e.bearerTokenEnv : undefined,
     };
   }
 
+  // Merge a submitted key/value map into the stored one: a present non-empty value
+  // overwrites, an explicit empty string clears that key, an omitted key is left
+  // alone. Shared by `env` and `headers` so the "re-save without re-typing the token"
+  // rule can't drift between them. Returns undefined when nothing is left.
+  function mergeSecrets(
+    prev: Record<string, string> | undefined,
+    submitted: Record<string, string>,
+  ): Record<string, string> | undefined {
+    const merged: Record<string, string> = { ...(prev ?? {}) };
+    for (const [k, v] of Object.entries(submitted)) {
+      const key = String(k).trim();
+      if (!key) continue;
+      const val = String(v ?? "");
+      if (val.length > 0) merged[key] = val;
+      else delete merged[key];
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+  }
+
   return {
     list(): RemoteMcpServer[] {
       const src = readSource();
@@ -188,6 +315,8 @@ export function makeMcpControl(opts?: {
       if (!name) return { ok: false, message: "A connector needs a name." };
       if (draft.transport !== undefined && !isTransport(draft.transport))
         return { ok: false, message: "Unknown transport." };
+      if (draft.auth !== undefined && !isAuth(draft.auth))
+        return { ok: false, message: "Unknown authentication type." };
 
       const src = readSource();
       const prev: SourceEntry = src.servers[name] ?? {};
@@ -201,31 +330,57 @@ export function makeMcpControl(opts?: {
         if (draft.command !== undefined) entry.command = String(draft.command).trim();
         const args = cleanArgs(draft.args);
         if (args !== undefined) entry.args = args;
-        // A stdio server can't reach a url and never does OAuth — clear stale fields.
+        // A stdio server can't reach a url and has nothing to authenticate to — clear
+        // every http-only field so a transport flip can't leave a live token behind.
         delete entry.url;
+        delete entry.headers;
+        delete entry.auth;
+        delete entry.bearerToken;
+        delete entry.bearerTokenEnv;
         delete entry.oauth;
         if (!entry.command) return { ok: false, message: "A local (stdio) connector needs a command." };
       } else {
         if (draft.url !== undefined) entry.url = String(draft.url).trim();
-        if (draft.oauth !== undefined) entry.oauth = !!draft.oauth;
+        // `auth` is authoritative; the legacy boolean is honoured only when it isn't
+        // sent, so an old app build keeps working without being able to override.
+        if (draft.auth !== undefined) entry.auth = draft.auth;
+        else if (draft.oauth !== undefined) entry.auth = draft.oauth ? "oauth" : "none";
+        if (draft.bearerTokenEnv !== undefined) {
+          const v = String(draft.bearerTokenEnv).trim();
+          if (v) entry.bearerTokenEnv = v;
+          else delete entry.bearerTokenEnv;
+        }
+        if (draft.bearerToken !== undefined) {
+          const v = String(draft.bearerToken);
+          if (v.length > 0) entry.bearerToken = v;
+          else delete entry.bearerToken;
+        }
+        if (draft.headers !== undefined) {
+          const merged = mergeSecrets(prev.headers, draft.headers);
+          if (merged) entry.headers = merged;
+          else delete entry.headers;
+        }
+        // A token that arrived without an explicit `auth` means bearer — otherwise the
+        // adapter stores the token and never sends it (it only sets the Authorization
+        // header when auth === "bearer"), which reads to the user as "my token is
+        // saved and the connector still 401s".
+        if (draft.auth === undefined && (entry.bearerToken || entry.bearerTokenEnv)) entry.auth = "bearer";
+        // Once `auth` is set, the legacy boolean is noise that authOf would have to
+        // keep tie-breaking. Drop it.
+        if (entry.auth !== undefined) delete entry.oauth;
         delete entry.command;
         delete entry.args;
         if (!entry.url) return { ok: false, message: "A remote (http) connector needs a URL." };
+        if (authOf(entry, "http") === "bearer" && !entry.bearerToken && !entry.bearerTokenEnv)
+          return { ok: false, message: "A bearer connector needs a token, or the name of an env var holding one." };
       }
 
       // Env/secrets: a present, non-empty value overwrites; an omitted key keeps the
       // existing value (re-save without re-typing the token preserves it). An explicit
       // empty string clears that key.
       if (draft.env !== undefined) {
-        const merged: Record<string, string> = { ...(prev.env ?? {}) };
-        for (const [k, v] of Object.entries(draft.env)) {
-          const key = String(k).trim();
-          if (!key) continue;
-          const val = String(v ?? "");
-          if (val.length > 0) merged[key] = val;
-          else delete merged[key];
-        }
-        if (Object.keys(merged).length > 0) entry.env = merged;
+        const merged = mergeSecrets(prev.env, draft.env);
+        if (merged) entry.env = merged;
         else delete entry.env;
       }
 
@@ -266,3 +421,44 @@ export function makeMcpControl(opts?: {
     },
   };
 }
+
+// MCP draft fields whose VALUES are credentials. They ride a sealed box addressed to
+// the terminal and are refused anywhere else. `bearerTokenEnv` is deliberately absent:
+// it is a variable NAME, not a value, and travels in the clear.
+const MCP_SEALED_FIELDS = ["env", "headers", "bearerToken"] as const;
+
+/**
+ * Apply the sealed half of an MCP connector save to the plain draft.
+ *
+ * Credential-bearing fields may ONLY arrive in the sealed box. A signed frame proves
+ * the account authored it; it does not stop the relay from READING it, and a bearer
+ * token or an `Authorization` header in the clear on the wire is exactly what sealing
+ * exists to prevent. We refuse rather than strip: silently dropping a token looks, to
+ * the user, like a save that worked.
+ *
+ * An absent field in the box means "leave what is stored alone" (mcpControl's
+ * re-save-without-re-typing rule) — which is not the same as an empty object.
+ *
+ * Lives here rather than in the harbor so it stays Pi-free and testable: importing the
+ * harbor pulls in the whole Pi session stack, which must only load after boot.ts.
+ * The signature check runs BEFORE this (harbor applyMcpSave).
+ */
+export function mergeSealedMcpSecrets(
+  draft: Record<string, unknown>,
+  opened?: { env?: Record<string, string>; headers?: Record<string, string>; bearerToken?: string },
+): { ok: true; draft: Record<string, unknown> } | { ok: false; message: string } {
+  for (const field of MCP_SEALED_FIELDS) {
+    if (draft[field] !== undefined) {
+      return {
+        ok: false,
+        message: `Connector credentials (${field}) must be sealed to this terminal, not sent in the clear.`,
+      };
+    }
+  }
+  if (!opened) return { ok: true, draft };
+  const merged = { ...draft };
+  if (opened.env !== undefined) merged.env = opened.env;
+  if (opened.headers !== undefined) merged.headers = opened.headers;
+  if (opened.bearerToken !== undefined) merged.bearerToken = opened.bearerToken;
+  return { ok: true, draft: merged };
+}

package/src/remote/relayClient.ts

@@ -227,6 +227,30 @@ export interface RelayCallbacks {
 }
 
 const RECONNECT_MS = 3000;
+// Retry cadence after the relay REFUSES us (4xx — in practice the plan's live-agent
+// cap). Slow, because only an account change can clear it, but not never: the harbor
+// should come up on its own once a slot frees. Kept well under the server's denial
+// 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.
@@ -285,13 +309,20 @@ 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.
   private bufKind: "text" | "reasoning" | null = null;
   private buf = "";
   private flushTimer: ReturnType<typeof setTimeout> | undefined;
   // Stable for this process so reconnects keep the same terminal identity. Callers
   // may pass a persisted id/label (e.g. the routines harbor, so it shows up as one
-  // recognizable "Privateer Routines" terminal across restarts instead of a fresh
+  // recognizable "Privateer Local Harbor" terminal across restarts instead of a fresh
   // random one each time).
   private readonly termId: string;
   private readonly label: string;
@@ -369,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();
@@ -388,7 +421,19 @@ export class RelayClient {
         body: JSON.stringify({ role: "agent", termId: this.termId, label: this.label }),
       });
       if (!res.ok) {
-        const e: Error & { status?: number } = new Error(`relay ticket HTTP ${res.status}`);
+        // Carry the server's reason, not just the status. A 403 here is almost always
+        // the plan's live-agent cap, and a bare "relay ticket HTTP 403" in a harbor log
+        // tells the operator nothing about which knob to turn.
+        let detail = "";
+        try {
+          const body = (await res.json()) as { message?: string; code?: string };
+          detail = body?.message || body?.code || "";
+        } catch {
+          /* non-JSON body — the status stands on its own */
+        }
+        const e: Error & { status?: number } = new Error(
+          detail ? `relay ticket HTTP ${res.status}: ${detail}` : `relay ticket HTTP ${res.status}`,
+        );
         e.status = res.status;
         throw e;
       }
@@ -397,19 +442,28 @@ 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 = "";
 
       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?.(
@@ -431,11 +485,27 @@ export class RelayClient {
       const msg = err instanceof Error ? err.message : String(err);
       // A 4xx (e.g. 403 concurrency cap) won't self-heal by retrying the same request —
       // fail-fast any awaitRegistered() caller (a live-task spawn) so it stops hanging.
-      // The management terminal ignores this signal, so its reconnect behavior is unchanged.
       const status = (err as { status?: number })?.status;
-      if (typeof status === "number" && status >= 400 && status < 500) {
+      const refused = typeof status === "number" && status >= 400 && status < 500;
+      if (refused) {
         this.settleFirstConnect(err instanceof Error ? err : new Error(msg));
+        // A refusal is a decision, not a hiccup: hammering the same request every few
+        // seconds can't change it, and for a harbor — whose onStatus goes to a log file,
+        // not to a person — that is thousands of identical lines a day. Say it once, in
+        // full, then retry on a slow timer so the terminal still comes up by itself the
+        // moment the account frees a slot or changes plan.
+        if (this.refusal !== msg) {
+          this.refusal = msg;
+          this.cb.onStatus?.(
+            `Remote access refused: ${msg} — this terminal will not be drivable from the app until that is resolved. ` +
+              `Retrying every ${Math.round(REFUSED_RECONNECT_MS / 1000)}s.`,
+          );
+        }
+        this.scheduleReconnect(REFUSED_RECONNECT_MS);
+        return;
       }
+      // Transient (network/route/5xx): stay on the fast retry.
+      this.refusal = null;
       this.cb.onStatus?.(`Remote access couldn't reach the relay (${msg}) — retrying…`);
       this.scheduleReconnect();
     } finally {
@@ -447,12 +517,43 @@ export class RelayClient {
     if (process.env.PRIVATEER_RELAY_DEBUG) this.cb.onStatus?.(`relay: ${msg}`);
   }
 
-  private scheduleReconnect(): void {
+  // 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(() => {
       this.reconnectTimer = undefined;
       void this.connect();
-    }, RECONNECT_MS);
+    }, delayMs);
   }
 
   private handle(data: WebSocket.RawData): void {
@@ -709,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/remote/routinesControl.ts

@@ -9,7 +9,7 @@
  * Unlike those two, routines are owned by the HARBOR (not an interactive Pi
  * session): they live in routines.json (see routines/store.ts) and fire from the
  * resident scheduler. So this control is wired into the harbor's own relay
- * connection (the "Privateer Routines" terminal), not the REPL/TUI. Running a
+ * connection (the "Privateer Local Harbor" terminal), not the REPL/TUI. Running a
  * routine now is the one action that needs the harbor itself, so it's injected as
  * `runNow` rather than reaching back into the store.
  *

package/src/routines/schema.ts

@@ -52,6 +52,8 @@ export const Routine = z
     // may be builtin names ("read") or MCP selectors — "<server>__<tool>" exact or
     // "<server>__*" for a whole server (see routines/toolSelect.ts). Selected MCP
     // tools run unattended under the auto-approve gate, so grant the minimum needed.
+    // The selector is NOT the tool name Pi sees; the harbor translates it at run time
+    // (mcp/toolNames.ts). This stored vocabulary is stable — don't "fix" it to match.
     tools: z.array(z.string()).optional(),
     // Paused routines stay in the file but never fire.
     enabled: z.boolean().default(true),

package/src/routines/store.ts

@@ -21,7 +21,7 @@ function slug(name: string): string {
 }
 
 // A stable relay terminal id for the harbor, persisted so it reappears as the same
-// "Privateer Routines" terminal in the app across restarts (rather than a fresh
+// "Privateer Local Harbor" terminal in the app across restarts (rather than a fresh
 // random terminal each boot). Random on first use so it stays unique per install —
 // the relay routes on this id with no user namespacing, so a shared constant could
 // collide across accounts. Matches the server's isValidTermId (`[A-Za-z0-9_-]{8,64}`).

package/src/routines/toolSelect.ts

@@ -1,12 +1,13 @@
-// A record of tool-name → tool definition. Was `ai`'s ToolSet in 0.2; MCP tool
-// wiring is a Phase-5 concern, so a structural type suffices for the filter below.
-type ToolSet = Record<string, unknown>;
-
 // A routine's `tools` field mixes builtin tool names with MCP selectors. MCP tools
-// are namespaced "<server>__<tool>" (see adaptMcpTools), and no builtin name contains
-// "__", so the separator is unambiguous: entries with "__" are MCP selectors — an
-// exact tool name or a per-server wildcard "<server>__*" — everything else is a
-// builtin allowlist entry.
+// are selected as "<server>__<tool>", and no Pi builtin name contains "__", so the
+// separator is unambiguous: entries with "__" are MCP selectors — an exact tool name
+// or a per-server wildcard "<server>__*" — everything else is a builtin allow-list
+// entry.
+//
+// NOTE the selector is NOT the name Pi registers. pi-mcp-adapter names a tool
+// "<serverPrefix>_<tool>" (one underscore), and Pi's `tools:` option is an exact-match
+// Set — so a selector must be TRANSLATED before it can grant anything. That
+// translation lives in ../mcp/toolNames.ts; this module only splits and matches.
 
 export interface RoutineToolSplit {
   // Builtin tool names (read, glob, ...). Empty → caller falls back to the safe set.
@@ -33,18 +34,11 @@ export function splitRoutineTools(tools?: string[]): RoutineToolSplit {
   return { builtin, mcp, servers: [...servers] };
 }
 
-// Does a namespaced MCP tool name match a selector? Exact match, or "<server>__*"
-// matching any tool on that server.
+// Does a SELECTOR-vocabulary tool name match a selector? Exact match, or "<server>__*"
+// matching any tool on that server. Used to answer "does this routine already grant
+// X?" against stored selectors — never against registered Pi tool names, which use a
+// different separator (see ../mcp/toolNames.ts).
 export function matchesSelector(name: string, selector: string): boolean {
   if (selector.endsWith("__*")) return name.startsWith(selector.slice(0, -1));
   return name === selector;
 }
-
-// Narrow a connected MCP toolset to the selected tools. Least privilege matters here:
-// routine runs use the auto-approve gate, so anything left in this set fires without
-// a human in the loop.
-export function filterMcpTools(tools: ToolSet, selectors: string[]): ToolSet {
-  return Object.fromEntries(
-    Object.entries(tools).filter(([name]) => selectors.some((s) => matchesSelector(name, s))),
-  );
-}