privateer-agent 0.6.10 → 0.8.0

package/src/{daemon → harbor}/index.ts

@@ -2,7 +2,7 @@ import type { Server } from "node:net";
 import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-// Pi session stack. The daemon MUST be launched after ./boot.ts (env +
+// Pi session stack. The harbor MUST be launched after ./boot.ts (env +
 // attestation dispatcher) — these are evaluated on import.
 import {
   createAgentSessionServices,
@@ -14,7 +14,7 @@ import { agentVersion } from "../config/version.ts";
 import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
 import { makePermissionGate, type GateController } from "../ext/permissionGate.ts";
 import { makePiPrivacyExtension } from "pi-privacy";
-import { makeAccountProvider } from "../providers/account.ts";
+import { makeAccountProvider, privateerChannel } from "../providers/account.ts";
 import { resolveDefaultModel } from "../providers/defaultModel.ts";
 import { RelayClient, type TaskSpec } from "../remote/relayClient.ts";
 import { createLiveTaskSession, type LiveTaskHandle } from "../remote/liveTaskSession.ts";
@@ -30,7 +30,7 @@ import { openJsonFromApp } from "../crypto/terminalUnseal.ts";
 import { verifyChannelSave, verifyOutboxKey } from "../crypto/accountVerify.ts";
 import { loadAccountSignKey, loadLastControlTs, saveLastControlTs } from "../crypto/accountTrust.ts";
 import { authorizeControl } from "../remote/controlAuth.ts";
-import { hasCredentials, revokeLocalSessions, revokeAccountSession, apiRequest, acquireAccountCredential, handleServerRevoke } from "../auth/privateer.ts";
+import { hasCredentials, revokeLocalSessions, revokeAccountSession, apiRequest, acquireAccountCredential, handleServerRevoke, defaultDeviceLabel } from "../auth/privateer.ts";
 import {
   loadRoutines,
   upsertRoutine,
@@ -50,7 +50,7 @@ import { splitRoutineTools } from "../routines/toolSelect.ts";
 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, type IpcRequest, type IpcResponse } from "./ipc.ts";
+import { startIpcServer, HarborAlreadyRunningError, type IpcRequest, type IpcResponse } from "./ipc.ts";
 import { isHosted, publishRelayPub } from "../config/hosted.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
@@ -71,15 +71,15 @@ const MAX_CLOUD_PLAINTEXT = 45_000;
 // a stuck graph from pinning a `running` slot forever when the controller wanders off.
 const GATE_TIMEOUT_MS = 5 * 60_000;
 
-interface DaemonConfig {
+interface HarborConfig {
   defaultModel: string;
   webhooks?: Record<string, { url: string; secret?: string; headers?: Record<string, string> }>;
   providers?: Record<string, { apiKey?: string } | undefined>;
 }
 
 // Minimal config read (webhooks + providers-for-redaction + default model). The
-// full config layer is a Phase-7 port; the daemon only needs these fields.
-function loadDaemonConfig(): DaemonConfig {
+// full config layer is a Phase-7 port; the harbor only needs these fields.
+function loadHarborConfig(): HarborConfig {
   try {
     const raw = JSON.parse(readFileSync(configPath(), "utf8"));
     return {
@@ -156,7 +156,7 @@ export function taskControlArgs(spec: TaskSpec): Record<string, unknown> {
   };
 }
 
-export class Daemon {
+export class Harbor {
   private server?: Server;
   private timer?: ReturnType<typeof setInterval>;
   private readonly startedAt = Date.now();
@@ -170,36 +170,36 @@ export class Daemon {
   // socket stays open).
   private lastActivityAt = Date.now();
   // Live, app-drivable sessions spawned on demand (task_spawn). Each has its OWN relay
-  // terminal (task-<uuid>); the daemon just keeps handles so it can reap them on shutdown.
+  // terminal (task-<uuid>); the harbor just keeps handles so it can reap them on shutdown.
   private readonly liveTasks = new Map<string, LiveTaskHandle>();
 
-  // App-facing routine management (list/save/delete/pause/run) over the daemon's
-  // relay. Run-now is injected here since only the daemon can actually fire one;
+  // App-facing routine management (list/save/delete/pause/run) over the harbor's
+  // relay. Run-now is injected here since only the harbor can actually fire one;
   // webhook validation reads config fresh so a just-declared endpoint is honored.
   private readonly routines = makeRoutinesControl({
     defaultCwd: () => process.cwd(),
-    webhookExists: (name) => !!loadDaemonConfig().webhooks?.[name],
+    webhookExists: (name) => !!loadHarborConfig().webhooks?.[name],
     runNow: (routine) => void this.runRoutine(routine),
   });
 
-  // App-facing channel management (list/save/remove) over the daemon's relay. The
-  // channels daemon (channels/run.ts) is a SEPARATE process that may be down, so
+  // App-facing channel management (list/save/remove) over the harbor's relay. The
+  // channels harbor (channels/run.ts) is a SEPARATE process that may be down, so
   // this edits config.json directly; `runningPlatforms` is a best-effort heartbeat
   // read for a live/offline badge, never a dependency. Edits apply on the channels
-  // daemon's next restart (its deliberate fail-safe posture).
+  // harbor's next restart (its deliberate fail-safe posture).
   private readonly channels = makeChannelsControl({
     runningPlatforms: () => readRunningPlatforms(),
   });
 
   // App-facing MCP connector management (list/save/set_enabled/remove) over the
-  // daemon's relay — the daemon is the Node HOST that actually runs the adapter (a
+  // harbor's relay — the harbor is the Node HOST that actually runs the adapter (a
   // phone/web client can't). Edits the SHARED agent/mcp-desktop.json + mcp.json, so a
   // machine has one MCP config whether it was set from the desktop (IPC) or the phone
   // (relay). Tokens ride in a SEALED box (applyMcpSave) — the relay never sees them.
   private readonly mcp = makeMcpControl();
 
-  // App-facing workflow management (list/get/save/remove/run) over the daemon's relay.
-  // Run-now is injected here since only the daemon owns the runner + its seams. A
+  // App-facing workflow management (list/get/save/remove/run) over the harbor's relay.
+  // Run-now is injected here since only the harbor owns the runner + its seams. A
   // workflow can carry a `script` step (RCE if forged), so every mutation is
   // account-signed + verified (guardControl) before reaching this control.
   private readonly workflows = makeWorkflowsControl({
@@ -226,17 +226,23 @@ export class Daemon {
     return "queued";
   };
 
-  start(): void {
+  async start(): Promise<void> {
+    // Single-instance lock FIRST, before any other side effect: binding the IPC
+    // socket is the machine's mutex. If a live harbor already holds it this throws
+    // HarborAlreadyRunningError — two harbors under one ~/.privateer share a single
+    // routineRelayId(), so a second would collide on the relay and double-fire
+    // routines. Doing this first means a rejected second instance never publishes a
+    // relay key, connects, or fires a tick.
+    this.server = await startIpcServer((req) => this.handleIpc(req));
     // Hosted only: publish our relay pubkey for the host to bind into the SEV-SNP
     // report. Before syncRelay() so the key exists by the time we're reachable.
     publishRelayPub();
     this.primeSchedule();
     this.timer = setInterval(() => void this.tick(), TICK_MS);
-    this.server = startIpcServer((req) => this.handleIpc(req));
     this.syncRelay();
     void this.flushPendingCloud();
     const count = loadRoutines().filter((r) => r.enabled).length;
-    log(`daemon started (pid ${process.pid}); ${count} enabled routine(s). Tick every ${TICK_MS / 1000}s.`);
+    log(`harbor started (pid ${process.pid}); ${count} enabled routine(s). Tick every ${TICK_MS / 1000}s.`);
     void this.tick();
   }
 
@@ -261,7 +267,7 @@ export class Daemon {
         onInterrupt: () => {},
         // A workflow human_gate / script-approval is surfaced as a select_request; the app
         // answers with select_response (option name) or an approval_response (allow/deny).
-        // Both resolve the pending gate — otherwise the daemon relay ignores approvals.
+        // Both resolve the pending gate — otherwise the harbor relay ignores approvals.
         onApprovalResponse: (id, decision) => this.resolveGate(id, decision === "deny" ? "deny" : "approve"),
         onSelectResponse: (id, value) => this.resolveGate(id, value),
         onControllerAttached: () => this.onControllerAttached(),
@@ -321,20 +327,20 @@ export class Daemon {
           this.controllerAttached = false;
           this.relay?.stop();
           this.relay = undefined;
-          log("relay terminated from the app; staying offline until the daemon restarts");
+          log("relay terminated from the app; staying offline until the harbor restarts");
         },
-        // The account signed this daemon out server-side (revoked from the app's Linked
+        // The account signed this harbor out server-side (revoked from the app's Linked
         // Devices). Beyond ending remote access (onTerminate), this wipes the machine
         // login: drop the relay and clear credentials, so routines/tasks stop cleanly
         // instead of dead-ending on a 401 each run. Stays idle until you /login on this
-        // machine and restart the daemon (the relayTerminated guard, as with onTerminate).
+        // machine and restart the harbor (the relayTerminated guard, as with onTerminate).
         onRevoked: () => {
           this.relayTerminated = true;
           this.controllerAttached = false;
           this.relay?.stop();
           this.relay = undefined;
           handleServerRevoke();
-          log("account signed out from the app (session revoked) — cleared credentials; idle until you run /login on this machine and restart the daemon");
+          log("account signed out from the app (session revoked) — cleared credentials; idle until you run /login on this machine and restart the harbor");
         },
         onStatus: (text) => log(`relay: ${text}`),
         onDisconnected: () => {
@@ -448,7 +454,7 @@ export class Daemon {
     return this.channels.save(withSecrets as any).message;
   }
 
-  // Verify an account-signed mutating control frame (H2) against this daemon's termId,
+  // Verify an account-signed mutating control frame (H2) against this harbor's termId,
   // then run the mutation. Fail-closed: an unsigned/forged/stale frame returns the
   // refusal message and the mutation NEVER runs. `routines_*` and `channels_remove`
   // route through here; `channels_save` has its own verify (sealed secrets) above.
@@ -517,11 +523,22 @@ export class Daemon {
     }
   }
 
+  // This machine's origin tag, embedded (E2EE) in every sealed result so the app can
+  // show WHICH box/environment produced it — the outbox record itself is account-only,
+  // so attribution can only live inside the sealed blob (where hostnames are allowed;
+  // the server never sees it). `id` is this install's stable relay id; `label` is the
+  // hostname-based device name. Cached — it never changes for the process lifetime.
+  private originCache?: { id: string; label: string };
+  private machineOrigin(): { id: string; label: string } {
+    if (!this.originCache) this.originCache = { id: routineRelayId(), label: defaultDeviceLabel() };
+    return this.originCache;
+  }
+
   private async postOutbox(name: string, at: string, status: "ok" | "error", content: string, kind: "routine" | "task" = "routine"): Promise<boolean> {
     const pub = await this.ensureOutboxPub();
     if (!pub) return false;
     const body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
-    const sealed = sealJson(pub, { v: 1, kind, name, status, at, content: body });
+    const sealed = sealJson(pub, { v: 1, kind, name, status, at, content: body, origin: this.machineOrigin() });
     try {
       const res = await apiRequest("/api/outbox", {
         method: "POST",
@@ -577,7 +594,7 @@ export class Daemon {
   }
 
   // ── Harbor hosted mode ──────────────────────────────────────────────────────
-  // A hosted daemon runs on-demand: it reports its earliest upcoming fire time so
+  // A hosted harbor runs on-demand: it reports its earliest upcoming fire time so
   // the server can wake it while suspended, and idle-suspends when there's no work.
   // No-op on a user's own machine (isHosted() === false).
 
@@ -652,7 +669,7 @@ export class Daemon {
     this.markActivity(); // hosted: work in progress — don't idle-suspend under it
     log(`running routine "${routine.name}"`);
 
-    const config = loadDaemonConfig();
+    const config = loadHarborConfig();
     const modelSpec = routine.model ?? config.defaultModel;
     const split = splitRoutineTools(routine.tools);
     // MCP tools (server__tool) join the allow-list: the mcpAdapter loaded in runSession
@@ -727,7 +744,18 @@ export class Daemon {
         cwd: spec.cwd,
         agentDir: agentDir(),
         resourceLoaderOptions: {
-          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider(), mcpAdapter] as any,
+          extensionFactories: [
+            makePermissionGate(gate),
+            // Per-model verified-TEE capability for pi-privacy's /models picker: show
+            // 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.
+            makePiPrivacyExtension({
+              privateerVerifiedTee: (m) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
+            }),
+            makeAccountProvider(),
+            mcpAdapter,
+          ] as any,
         },
       });
       servicesRef = services as any;
@@ -770,7 +798,7 @@ export class Daemon {
       status = "error";
       error = err instanceof Error ? err.message : String(err);
     } finally {
-      // Revoke ONLY this run's account inference session (the daemon's own child API
+      // Revoke ONLY this run's account inference session (the harbor's own child API
       // session — relay/outbox — stays alive until shutdown). Drop Pi's persisted copy
       // too so a later run's fallback never reuses a revoked token. Best-effort.
       if (spawnedAccount) {
@@ -788,7 +816,7 @@ export class Daemon {
   // just executes. Concurrency-guarded by a `task:<title>` key in `this.running` (never
   // collides with routine ids, which are uuids).
   async runTask(spec: TaskSpec): Promise<void> {
-    const config = loadDaemonConfig();
+    const config = loadHarborConfig();
     const cwd = spec.cwd && spec.cwd.trim() ? spec.cwd : process.cwd();
     const modelSpec = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
@@ -825,7 +853,7 @@ export class Daemon {
     void (async () => {
       try {
         const handle = await createLiveTaskSession(spec, {
-          defaultModel: loadDaemonConfig().defaultModel,
+          defaultModel: loadHarborConfig().defaultModel,
           parseSpec,
           log,
           onClosed: (id) => this.liveTasks.delete(id),
@@ -845,7 +873,7 @@ export class Daemon {
 
   // Run a saved workflow graph to completion (workflows_run / the injected runNow). The
   // signed-frame gate (guardControl, STRICT) already ran before this is reached. Wires the
-  // runner's injected seams to the daemon's real capabilities: agent steps → runSession
+  // runner's injected seams to the harbor's real capabilities: agent steps → runSession
   // (SAFE_TOOLS gate), gates → relay approvals, scripts → a gated child process (only when
   // attended + approved; the runner fail-closes an unattended script itself), and the
   // result is sealed to the outbox + mirrored live, exactly like an ad-hoc task.
@@ -863,9 +891,9 @@ export class Daemon {
         runScript: (step, cwd) => this.runScript(step, cwd),
         askGate: (step, promptText) => this.askGate(step.options.map((o) => ({ name: o.name, description: o.description })), promptText),
         attended: () => this.controllerAttached,
-        // Preserve the daemon's one-at-a-time discipline: fan-out (parallel/for_each) runs
+        // Preserve the harbor's one-at-a-time discipline: fan-out (parallel/for_each) runs
         // sequentially here, so a workflow never spawns concurrent headless sessions on the
-        // resident daemon. (The standalone runner defaults to 4; a UI host can raise it.)
+        // resident harbor. (The standalone runner defaults to 4; a UI host can raise it.)
         concurrency: 1,
         // An effectful step reached while unattended: seal a "needs approval" notice so the
         // user catches up, and (if a controller is somehow attached) surface it live.
@@ -878,7 +906,7 @@ export class Daemon {
         },
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
         log: (m) => log(`  [wf ${wf.workflow.name}] ${m}`),
-        // Live progress: announce each step start in the daemon terminal's feed.
+        // Live progress: announce each step start in the harbor terminal's feed.
         onEvent: (ev) => {
           if (ev.type === "step_start") this.relay?.sendNotice(`▶ ${ev.name}`);
         },
@@ -969,7 +997,7 @@ export class Daemon {
   // (so a later step can route on `{{ step.output.field }}`). Non-JSON output leaves
   // `output` empty and lives in `text` — the raw/display path.
   private async runWorkflowAgent(spec: AgentRunSpec): Promise<AgentRunResult> {
-    const config = loadDaemonConfig();
+    const config = loadHarborConfig();
     const model = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
     const tools = [...(split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS), ...(split?.mcp ?? [])];
@@ -1031,15 +1059,24 @@ export class Daemon {
   }
 }
 
-// Entry point for `privateer daemon`. Caller must have imported ./boot.ts first.
-export function runDaemon(): void {
-  const daemon = new Daemon();
-  daemon.start();
+// Entry point for `privateer harbor`. Caller must have imported ./boot.ts first.
+export function runHarbor(): void {
+  const harbor = new Harbor();
   const shutdown = () => {
     log("shutting down");
-    daemon.stop();
+    harbor.stop();
     void revokeLocalSessions().finally(() => process.exit(0));
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
+  harbor.start().catch((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.
+      process.stderr.write("A Harbor is already running on this machine — leaving the existing one in charge.\n");
+      process.exit(0);
+    }
+    process.stderr.write(`Harbor failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  });
 }

package/src/harbor/ipc.ts

@@ -0,0 +1,175 @@
+import { createServer, createConnection, type Socket, type Server } from "node:net";
+import { existsSync, unlinkSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+import type { Routine } from "../routines/schema.ts";
+
+// The CLI/TUI talks to the resident harbor over a unix domain socket. The protocol
+// is one JSON request per connection, answered with one JSON response, both
+// newline-terminated. Kept tiny and local — nothing crosses the machine boundary.
+
+export function harborSocketPath(): string {
+  return join(globalDir(), "harbor.sock");
+}
+
+export type IpcRequest =
+  | { cmd: "status" }
+  | { cmd: "list" }
+  | { cmd: "add"; routine: Routine }
+  | { cmd: "remove"; idOrName: string }
+  | { cmd: "pause"; idOrName: string }
+  | { cmd: "resume"; idOrName: string }
+  | { cmd: "run-now"; idOrName: string }
+  | { cmd: "reload" };
+
+export interface IpcResponse {
+  ok: boolean;
+  message?: string;
+  routines?: Routine[];
+  // Harbor liveness/uptime for `status`.
+  pid?: number;
+  uptimeSec?: number;
+}
+
+export type IpcHandler = (req: IpcRequest) => Promise<IpcResponse> | IpcResponse;
+
+// Probe whether a LIVE process is listening on the socket at `path`. Used as the
+// single-instance test: a successful connect (or a slow-to-answer one) means a real
+// harbor holds the lock; ECONNREFUSED/ENOENT means the socket file is stale (no
+// listener behind it) and is safe to reclaim. Conservative — any ambiguous error
+// resolves `true` so we never steal a path that might still be owned.
+function probeExistingListener(path: string, timeoutMs = 1000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createConnection(path);
+    const done = (live: boolean) => {
+      clearTimeout(timer);
+      try { sock.destroy(); } catch { /* already gone */ }
+      resolve(live);
+    };
+    const timer = setTimeout(() => done(true), timeoutMs); // slow to answer ⇒ assume live
+    sock.on("connect", () => done(true));
+    sock.on("error", (err: NodeJS.ErrnoException) => {
+      done(!(err.code === "ECONNREFUSED" || err.code === "ENOENT"));
+    });
+  });
+}
+
+// Start the harbor-side socket server. Resolves with the Server (so the caller can
+// close it), or REJECTS with HarborAlreadyRunningError if a live harbor already owns
+// the socket — the bind is the machine's single-instance lock. Two harbors under one
+// ~/.privateer share a single routineRelayId(), so a second instance would collide on
+// the relay and double-fire routines; refusing to start is the fix. A stale socket
+// file (crash with no live listener) is detected and reclaimed, so recovery still works.
+export function startIpcServer(handler: IpcHandler): Promise<Server> {
+  const path = harborSocketPath();
+  const build = (): Server =>
+    createServer((sock: Socket) => {
+      let buf = "";
+      sock.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        const nl = buf.indexOf("\n");
+        if (nl < 0) return; // wait for the full line
+        const line = buf.slice(0, nl);
+        void (async () => {
+          let res: IpcResponse;
+          try {
+            res = await handler(JSON.parse(line) as IpcRequest);
+          } catch (err) {
+            res = { ok: false, message: err instanceof Error ? err.message : String(err) };
+          }
+          sock.end(JSON.stringify(res) + "\n");
+        })();
+      });
+      sock.on("error", () => sock.destroy());
+    });
+
+  return new Promise<Server>((resolve, reject) => {
+    // `reclaimed` guards a single stale-socket reclaim so a persistent bind failure
+    // can't loop. On EADDRINUSE we probe for a live listener rather than unlinking
+    // blindly (the old behavior, which let a second harbor silently steal the path).
+    const attempt = (reclaimed: boolean) => {
+      const server = build();
+      server.once("error", (err: NodeJS.ErrnoException) => {
+        if (err.code !== "EADDRINUSE") { reject(err); return; }
+        void probeExistingListener(path).then((live) => {
+          if (live) { reject(new HarborAlreadyRunningError()); return; }
+          if (reclaimed) { reject(err); return; } // already reclaimed once — give up
+          try { unlinkSync(path); } catch { /* ignore — retry surfaces a clearer error */ }
+          attempt(true);
+        });
+      });
+      server.listen(path, () => {
+        try {
+          chmodSync(path, 0o600); // owner-only IPC endpoint
+        } catch {
+          /* non-POSIX — best effort */
+        }
+        resolve(server);
+      });
+    };
+    attempt(false);
+  });
+}
+
+// Client side: send one request, resolve with the response. Rejects if the harbor
+// isn't running (no socket / connection refused) so callers can offer to start it.
+export function sendToHarbor(req: IpcRequest, timeoutMs = 5_000): Promise<IpcResponse> {
+  const path = harborSocketPath();
+  return new Promise<IpcResponse>((resolve, reject) => {
+    if (!existsSync(path)) {
+      reject(new HarborNotRunningError());
+      return;
+    }
+    const sock = createConnection(path);
+    let buf = "";
+    const timer = setTimeout(() => {
+      sock.destroy();
+      reject(new Error("harbor did not respond in time"));
+    }, timeoutMs);
+    sock.on("connect", () => sock.end(JSON.stringify(req) + "\n"));
+    sock.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+    });
+    sock.on("end", () => {
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(buf.trim()) as IpcResponse);
+      } catch {
+        reject(new Error("malformed response from harbor"));
+      }
+    });
+    sock.on("error", (err: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      // ECONNREFUSED means a stale socket file with no listener behind it.
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") reject(new HarborNotRunningError());
+      else reject(err);
+    });
+  });
+}
+
+export class HarborNotRunningError extends Error {
+  constructor() {
+    super("Harbor is not running. Start it with `privateer harbor`.");
+    this.name = "HarborNotRunningError";
+  }
+}
+
+// Thrown by startIpcServer when a live harbor already holds this machine's socket —
+// i.e. a second instance is trying to start under the same ~/.privateer. The caller
+// (runHarbor) treats this as a clean no-op exit, not a crash.
+export class HarborAlreadyRunningError extends Error {
+  constructor() {
+    super("A Harbor is already running on this machine.");
+    this.name = "HarborAlreadyRunningError";
+  }
+}
+
+// Convenience: is the harbor reachable right now?
+export async function harborIsRunning(): Promise<boolean> {
+  try {
+    const res = await sendToHarbor({ cmd: "status" }, 2_000);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}