privateer-agent 0.8.0 → 0.9.0

package/src/remote/liveTaskSession.ts

@@ -20,7 +20,12 @@ import { agentVersion } from "../config/version.ts";
 import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
 import { makePermissionGate, isRemoteUnsafeTool, type GateController } from "../ext/permissionGate.ts";
 import { makePiPrivacyExtension } from "pi-privacy";
-import { makeAccountProvider, privateerChannel } from "../providers/account.ts";
+import {
+  makeAccountProvider,
+  privateerChannel,
+  rememberAccountCredential,
+  dropPersistedAccountCredential,
+} from "../providers/account.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
 import { spawnAccountCredentials, revokeAccountSession, hasCredentials } from "../auth/privateer.ts";
@@ -43,6 +48,10 @@ export interface LiveTaskDeps {
 // abandoned spawn can't run the account meter or hold resources forever).
 const ATTACH_GRACE_MS = 180_000; // 3 min to attach after spawn
 const MAX_LIFETIME_MS = 30 * 60_000; // 30 min absolute cap
+// How long to wait for the spawned terminal to actually register on the relay before we give
+// up and report the spawn as failed. `start()` resolves before the socket opens, so without
+// this confirmation the harbor would announce a terminal the app can never attach to.
+const REGISTER_TIMEOUT_MS = 20_000;
 
 export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps): Promise<LiveTaskHandle> {
   const cwd = spec.cwd && spec.cwd.trim() ? spec.cwd : process.cwd();
@@ -58,7 +67,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   let initialPromptSent = false;
   let stopped = false;
   let spawnedAccount = false;
-  let servicesRef: { authStorage?: { remove?: (p: string) => void } } | null = null;
+  let servicesRef: { authStorage?: { remove?: (p: string) => void; get?: (p: string) => unknown } } | null = null;
 
   let attachTimer: ReturnType<typeof setTimeout> | undefined;
   let lifeTimer: ReturnType<typeof setTimeout> | undefined;
@@ -73,7 +82,9 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     // app's Linked Devices; the harbor's own child session stays alive. Best-effort.
     if (spawnedAccount) {
       try { await revokeAccountSession(); } catch { /* server TTL is the fallback */ }
-      try { servicesRef?.authStorage?.remove?.("privateer"); } catch { /* nothing persisted */ }
+      // Ownership-checked: auth.json is shared machine-wide, so a live task's teardown
+      // must not delete an interactive terminal's entry (see providers/account.ts).
+      try { dropPersistedAccountCredential({ modelRegistry: { authStorage: servicesRef?.authStorage } }); } catch { /* nothing persisted */ }
     }
     deps.onClosed(termId);
     deps.log(`live task ${termId} closed`);
@@ -156,6 +167,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     try {
       const creds = await spawnAccountCredentials();
       (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
+      rememberAccountCredential(creds); // claim it, so stop() drops OUR entry only
       spawnedAccount = true;
     } catch (e) {
       deps.log(`live task ${termId} account channel unavailable: ${(e as Error).message}`);
@@ -213,6 +225,11 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   relay = new RelayClient(bridge.callbacks, { termId, label });
   bridge.attachRelay(relay);
   await relay.start();
+  // start() resolves before the socket registers; confirm the terminal is actually live on
+  // the relay BEFORE returning (→ the harbor announces task_spawned). Rejects on a hard
+  // failure (e.g. the concurrency cap) or timeout → the catch below tears down and propagates,
+  // so the harbor reports task_spawn_error instead of pointing the app at a dead terminal.
+  await relay.awaitRegistered(REGISTER_TIMEOUT_MS);
 
   // Reap if nobody ever attaches, and cap the absolute lifetime regardless.
   attachTimer = setTimeout(() => { if (!attached) void stop(); }, ATTACH_GRACE_MS);

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,12 @@ 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;
 // 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,16 +291,26 @@ export class RelayClient {
   private closed = false;
   private connecting = false;
   private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  // 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;
+  // First-registration signal (opt-in via awaitRegistered): `start()` resolves before the
+  // socket actually opens, so a caller that must not act until the terminal is truly live on
+  // the relay — e.g. a live-task spawn that announces `task_spawned` — waits on this instead.
+  // Settled once: resolved on the first ws `open`, rejected on a hard (4xx) ticket-mint
+  // failure. Reconnect blips after a successful first open do NOT re-settle it.
+  private firstConnectSettled = false;
+  private firstConnectError: Error | null = null;
+  private firstConnectWaiters: Array<{ resolve: () => void; reject: (e: Error) => void }> = [];
   // In-progress file transfers from the app, keyed by the controller's attachment
   // id. Reassembled from attach_begin/chunk/end frames, then handed to onAttachment.
   private readonly incoming = new Map<
@@ -322,8 +338,43 @@ export class RelayClient {
     await this.connect();
   }
 
+  // Resolve once this terminal has actually registered on the relay (ws `open`), reject on a
+  // hard registration failure (e.g. a 403 concurrency-cap denial) or after `timeoutMs`.
+  // `start()` resolves before the socket opens, so a live-task spawn calls this to confirm the
+  // app can attach BEFORE it announces the terminal — otherwise the app is told to drive a
+  // terminal that never came up and hangs. Idempotent; settling stores its result so a caller
+  // that awaits after the fact still gets it (no dangling/unhandled rejection).
+  awaitRegistered(timeoutMs: number): Promise<void> {
+    if (this.firstConnectSettled) {
+      return this.firstConnectError ? Promise.reject(this.firstConnectError) : Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      const waiter = {
+        resolve: () => { clearTimeout(timer); resolve(); },
+        reject: (e: Error) => { clearTimeout(timer); reject(e); },
+      };
+      const timer = setTimeout(() => {
+        this.firstConnectWaiters = this.firstConnectWaiters.filter((w) => w !== waiter);
+        reject(new Error(`relay registration timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.firstConnectWaiters.push(waiter);
+    });
+  }
+
+  private settleFirstConnect(err?: Error): void {
+    if (this.firstConnectSettled) return;
+    this.firstConnectSettled = true;
+    this.firstConnectError = err ?? null;
+    const waiters = this.firstConnectWaiters;
+    this.firstConnectWaiters = [];
+    for (const w of waiters) err ? w.reject(err) : w.resolve();
+  }
+
   stop(): void {
     this.closed = true;
+    // Fail any awaitRegistered() waiter promptly instead of leaving it to time out — a
+    // terminal stopped before it ever registered is never coming up.
+    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.bufKind = null;
@@ -344,7 +395,23 @@ export class RelayClient {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ role: "agent", termId: this.termId, label: this.label }),
       });
-      if (!res.ok) throw new Error(`relay ticket HTTP ${res.status}`);
+      if (!res.ok) {
+        // 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;
+      }
       const { ticket } = (await res.json()) as { ticket: string };
 
       const wsUrl =
@@ -357,6 +424,8 @@ export class RelayClient {
 
       ws.on("open", () => {
         opened = true;
+        this.refusal = null; // a later refusal is news again
+        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));
@@ -381,6 +450,29 @@ export class RelayClient {
       // Ticket mint failed (auth/network/route) — surface it; a silent failure
       // looks identical to "connected but ignoring me".
       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.
+      const status = (err as { status?: number })?.status;
+      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 {
@@ -392,12 +484,12 @@ export class RelayClient {
     if (process.env.PRIVATEER_RELAY_DEBUG) this.cb.onStatus?.(`relay: ${msg}`);
   }
 
-  private scheduleReconnect(): void {
+  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 {
@@ -691,6 +783,13 @@ export class RelayClient {
     this.rawSend({ type: "task_spawned", termId, label });
   }
 
+  // Tell the app a live task spawn FAILED (reply to task_spawn), with a short reason, so the
+  // spawn screen can stop waiting and show it — a live spawn otherwise has no failure signal
+  // and the app would spin until its own timeout. Fire-and-forget over the management relay.
+  sendTaskSpawnError(reason: string): void {
+    this.rawSend({ type: "task_spawn_error", reason: safe(reason, 300) });
+  }
+
   sendEvent(ev: EngineEvent): void {
     if (ev.type === "text") return this.bufferDelta("text", ev.text);
     if (ev.type === "reasoning") return this.bufferDelta("reasoning", ev.text);

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}`).