privateer-agent 0.12.17 → 0.12.19

package/bin/privateer-launch.mjs

@@ -29,6 +29,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 import { routeUpdate } from "./update-route.mjs";
+import { runToCompletion } from "./run-to-completion.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
 const REPO = path.resolve(HERE, "..");
@@ -132,18 +133,6 @@ if (sub === "--version" || sub === "-V") {
 }
 
 // Faithfully propagate a child's exit/signal, mirroring bash `exec`.
-function runToCompletion(cmd, cmdArgs, opts = {}) {
-  const child = spawn(cmd, cmdArgs, { stdio: "inherit", env: process.env, ...opts });
-  child.on("exit", (code, signal) => {
-    if (signal) process.kill(process.pid, signal);
-    else process.exit(code ?? 0);
-  });
-  child.on("error", (e) => {
-    console.error(`privateer: failed to launch — ${e.message}`);
-    process.exit(1);
-  });
-}
-
 // npm gives no usable progress, so on a TTY show a braille spinner while it runs
 // and keep its output buffered — shown only if the install fails. Non-TTY (CI,
 // piped) keeps the old passthrough behaviour. The global package is replaced in
@@ -291,7 +280,9 @@ if (sub === "update") {
 else if (sub === "harbor" || sub === "daemon") {
   sweepLegacyShims(); // a harbor-only machine upgrades too — see the function's note
   const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
-  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)]);
+  // A resident background process, stopped by launchd/systemd/scripts with a plain
+  // `kill` — which reaches only this launcher. See runToCompletion.
+  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
 // --- `privateer verify` ----------------------------------------------------
@@ -314,7 +305,9 @@ else if (sub === "verify") {
 else if (sub === "acp") {
   sweepLegacyShims(); // silent: only ever removes files
   const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
-  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-acp.mjs"), ...args.slice(1)]);
+  // Long-lived and driven over stdio by an editor, which stops it by terminating
+  // the process rather than by a keystroke. Same leak, same fix.
+  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-acp.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
 // --- normal launch: resolve the moat, then exec Pi's TUI with it -----------

package/bin/run-to-completion.d.mts

@@ -0,0 +1,18 @@
+// Types for the launcher's child-process handoff. Same reason as update-route.d.mts:
+// the implementation is plain .mjs because bin/ runs under a bare `node`, before any
+// transpiler exists — but the test that pins the signal behaviour is TypeScript.
+
+import type { SpawnOptions } from "node:child_process";
+
+export interface RunToCompletionOptions extends SpawnOptions {
+  /** Pass SIGTERM/SIGHUP on to the child and wait for it, instead of dying alone and
+   *  leaving it reparented to init. Off by default — only the long-lived headless
+   *  children (harbor, acp) need it; see the implementation's note on why SIGINT and
+   *  SIGQUIT are deliberately NOT forwarded. */
+  forwardSignals?: boolean;
+}
+
+/** Spawn a child and hand it this process's lifetime: its exit code, its signal
+ *  death, and — with `forwardSignals` — the termination signals sent to us. Never
+ *  returns normally; the process exits with the child. */
+export function runToCompletion(cmd: string, cmdArgs: string[], opts?: RunToCompletionOptions): void;

package/bin/run-to-completion.mjs

@@ -0,0 +1,73 @@
+/**
+ * Spawn a child and hand it this process's lifetime — including its termination
+ * signals.
+ *
+ * Extracted from the launcher for the same reason update-route.mjs was: the
+ * reasoning is subtle enough to want a test next to it, and the launcher itself
+ * runs on import so nothing inside it can be unit-tested in place.
+ */
+import { spawn } from "node:child_process";
+
+// How long a forwarded SIGTERM has to work before we stop being polite. A harbor
+// shuts down in milliseconds; this only matters for a child wedged mid-write.
+const SIGNAL_GRACE_MS = 5000;
+
+/**
+ * `forwardSignals` — pass a termination signal on to the child and wait for it.
+ *
+ * WHY THIS EXISTS. Every subcommand here re-execs a second Node process, and
+ * without this the launcher dies alone: the child is reparented to init and keeps
+ * running. For the TUI that is nearly invisible (Ctrl-C is delivered by the
+ * terminal to the whole foreground process group, so both die anyway), but for the
+ * long-lived headless children it is a real leak — `privateer harbor` is started by
+ * launchd/systemd and by scripts, both of which stop a process with a plain
+ * `kill`, and that signal reaches only the launcher.
+ *
+ * Measured 2026-08-23 while building the E2E CLI fixture: killing
+ * `privateer harbor run` left the harbor alive, reparented to init, and STILL
+ * CONNECTED TO THE RELAY — holding the account's live-agent slot (one, on the free
+ * plan) with no way to find it except by pid. The harbor already handles SIGTERM
+ * and shuts down cleanly; nothing was ever passing it on.
+ *
+ * **Only SIGTERM and SIGHUP are forwarded, deliberately.** SIGINT and SIGQUIT are
+ * generated by the terminal and delivered to the entire foreground process group,
+ * so the child has already had them — forwarding would deliver a SECOND one, and a
+ * TUI that treats the first Ctrl-C as "clear the line" and the second as "quit"
+ * would exit on a single keypress.
+ *
+ * The parent then waits for the child rather than exiting under it, so the exit
+ * code still belongs to the child, and escalates to SIGKILL after a grace period:
+ * a child that ignores SIGTERM must not be able to outlive the launcher, which is
+ * the whole failure being fixed.
+ */
+export function runToCompletion(cmd, cmdArgs, opts = {}) {
+  const { forwardSignals = false, ...spawnOpts } = opts;
+  const child = spawn(cmd, cmdArgs, { stdio: "inherit", env: process.env, ...spawnOpts });
+
+  let killTimer = null;
+  if (forwardSignals) {
+    for (const sig of ["SIGTERM", "SIGHUP"]) {
+      process.on(sig, () => {
+        try { child.kill(sig); } catch { /* already gone */ }
+        // Do NOT exit here: installing a listener suppresses Node's default
+        // terminate-now behaviour, so we stay up until the child's own exit fires
+        // below and can report its code.
+        if (killTimer) return;
+        killTimer = setTimeout(() => {
+          try { child.kill("SIGKILL"); } catch { /* already gone */ }
+        }, SIGNAL_GRACE_MS);
+        killTimer.unref?.();
+      });
+    }
+  }
+
+  child.on("exit", (code, signal) => {
+    if (killTimer) clearTimeout(killTimer);
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+  child.on("error", (e) => {
+    console.error(`privateer: failed to launch — ${e.message}`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.17",
+  "version": "0.12.19",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/src/crypto/terminalKey.ts

@@ -18,7 +18,7 @@
  * app's seal(): X25519 → HKDF-SHA256 → AES-256-GCM.
  */
 
-import { readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, chmodSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { x25519 } from "@noble/curves/ed25519";
 import { globalDir } from "../config/paths.ts";
@@ -67,6 +67,14 @@ function loadOrCreate(): { publicKey: Uint8Array; secretKey: Uint8Array } {
   const secretKey = x25519.utils.randomPrivateKey();
   const publicKey = x25519.getPublicKey(secretKey);
   const file: TerminalKeyFile = { v: 1, publicKey: b64(publicKey), secretKey: b64(secretKey) };
+  // The home may not exist yet: the FIRST thing a fresh machine does is /login, and
+  // requestDeviceCode swallows a throw from here (a login must not fail over a key it
+  // can live without). Without the mkdir that swallow turned an absent directory into
+  // a login that silently carried no pubkey — so the app had nothing to pin and every
+  // app-sealed secret to this terminal stayed impossible until the next re-link.
+  // saveCredentials writes into the same directory and has always created it; this is
+  // the same rule, one step earlier in the flow.
+  mkdirSync(globalDir(), { recursive: true, mode: 0o700 });
   // Create 0600 from the start — passing `mode` to writeFileSync avoids the TOCTOU
   // window where a fresh file briefly carries umask perms (group/world-readable)
   // before a follow-up chmod. `mode` only applies on CREATE, so also chmod to fix an

package/src/harbor/index.ts

@@ -651,6 +651,16 @@ export class Harbor {
   }
 
   private async tick(): Promise<void> {
+    // Retry the relay every tick, not just at startup. syncRelay() bails when the
+    // account isn't signed in on this machine — and a harbor that came up in that
+    // state used to stay off the relay FOREVER, because start() was the only caller
+    // that mattered (the three IPC commands that also call it are ones the desktop
+    // app never sends). Signing in afterwards wrote credentials.json and changed
+    // nothing: the harbor kept answering IPC, so the app called it running, while
+    // its relay socket had never been opened — the permanent "Connecting" with a
+    // harbor that fires no routine and answers no spawn. Cheap and idempotent: it
+    // returns immediately once a client exists, or while remote access is off.
+    this.syncRelay();
     void this.flushPendingCloud();
     const now = Date.now();
     for (const r of loadRoutines()) {
@@ -1269,19 +1279,35 @@ export class Harbor {
   private relayStatus(): RelayStatus {
     const termId = routineRelayId();
     if (this.relayTerminated) {
-      return { termId, connected: false, detail: "remote access was turned off from the app — restart the harbor to re-enable it" };
+      return { termId, connected: false, reason: "terminated", detail: "remote access was turned off from the app — restart the harbor to re-enable it" };
     }
     if (!this.relay) {
+      // "relay not started" with credentials present is now a sub-tick window, not a
+      // permanent state: tick() re-runs syncRelay(), so a harbor that came up signed
+      // out connects on its own once you sign in. Reported as "connecting" because
+      // that is what it now is.
+      const signedIn = hasCredentials();
       return {
         termId,
         connected: false,
-        detail: hasCredentials()
+        reason: signedIn ? "connecting" : "signed-out",
+        detail: signedIn
           ? "relay not started"
-          : "no account signed in on this machine — run `privateer` and /login, then restart the harbor",
+          : "no account signed in on this machine — run `privateer` and /login",
       };
     }
     const conn = this.relay.connectionStatus();
-    if (!conn.connected) return { termId, connected: false, detail: "connecting…" };
+    // The client knows why it isn't up — a refused ticket, an unreachable server —
+    // and reporting a flat "connecting…" over the top of that is what made a harbor
+    // that will never connect look like one that is about to.
+    if (!conn.connected) {
+      return {
+        termId,
+        connected: false,
+        reason: conn.refused ? "refused" : "connecting",
+        detail: conn.detail ?? "connecting…",
+      };
+    }
     return { termId, connected: true, upSec: conn.upSec, quietSec: conn.quietSec };
   }
 

package/src/harbor/ipc.ts

@@ -42,6 +42,21 @@ export type IpcRequest =
   | { cmd: "run-now"; idOrName: string }
   | { cmd: "reload" };
 
+/**
+ * Why a harbor isn't on the relay, as a code rather than a sentence.
+ *
+ * `detail` below is written for a terminal — it names CLI commands and is English
+ * only — so the app can't put it in front of a user. It used to have nothing else
+ * to go on, and said "give it a moment" about every one of these, including the
+ * three that never clear on their own. This is the machine-readable half.
+ *
+ *   terminated  remote access was switched off from the app; needs a restart
+ *   signed-out  no account credentials on this machine
+ *   refused     the server said no (plan's agent cap, rejected ticket) — standing
+ *   connecting  genuinely still trying; this one really is worth a moment
+ */
+export type RelayReason = "terminated" | "signed-out" | "refused" | "connecting";
+
 /**
  * The harbor's view of its own relay connection, reported by `status`.
  *
@@ -62,6 +77,8 @@ export interface RelayStatus {
   quietSec?: number;
   /** Why it isn't connected, when we know: signed out, turned off from the app, … */
   detail?: string;
+  /** The same fact as `detail`, for a caller that has to localize it. */
+  reason?: RelayReason;
 }
 
 export interface IpcResponse {

package/src/remote/relayClient.ts

@@ -383,6 +383,11 @@ export class RelayClient {
   private reconnectDelay = RECONNECT_MS;
   // Last refusal reason reported, so a 4xx is logged once instead of on every retry.
   private refusal: string | null = null;
+  // Why the last connection attempt failed, kept for connectionStatus(). A refusal
+  // (4xx) outranks it — that one is a decision, not a hiccup — but without either,
+  // every un-connected relay reports as a bare "connecting…", which is the same
+  // sentence whether the socket opens in two seconds or never opens again.
+  private lastFailure: string | null = null;
   // Ordered delta buffer (text/reasoning) coalesced into one frame per flush.
   private bufKind: "text" | "reasoning" | null = null;
   private buf = "";
@@ -518,6 +523,7 @@ export class RelayClient {
       ws.on("open", () => {
         opened = true;
         this.refusal = null; // a later refusal is news again
+        this.lastFailure = null; // whatever kept us out is history
         this.reconnectDelay = RECONNECT_MS; // reachable again — next blip retries fast
         this.connectedAt = Date.now();
         this.startHeartbeat(ws);
@@ -537,6 +543,9 @@ export class RelayClient {
         // attach/detach frame said. Re-learned on the next attach or inbound frame.
         this.controllerHere = false;
         this.cb.onDisconnected?.();
+        // A socket that never opened failed for a reason worth reporting; one that
+        // opened and dropped is an ordinary blip the reconnect handles.
+        this.lastFailure = opened ? null : lastErr || "the relay connection closed before it opened";
         if (!this.closed) {
           this.cb.onStatus?.(
             opened
@@ -560,6 +569,7 @@ export class RelayClient {
       const status = (err as { status?: number })?.status;
       const refused = typeof status === "number" && status >= 400 && status < 500;
       if (refused) {
+        this.lastFailure = msg;
         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,
@@ -578,6 +588,7 @@ export class RelayClient {
       }
       // Transient (network/route/5xx): stay on the fast retry.
       this.refusal = null;
+      this.lastFailure = msg;
       this.cb.onStatus?.(`Remote access couldn't reach the relay (${msg}) — retrying…`);
       this.scheduleReconnect();
     } finally {
@@ -970,8 +981,19 @@ export class RelayClient {
   // 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 };
+  connectionStatus(): { connected: boolean; upSec?: number; quietSec?: number; detail?: string; refused?: boolean } {
+    // Not connected: say WHY when we know. A standing refusal (the plan's agent cap,
+    // a rejected ticket) is the answer that matters most — it will not clear on its
+    // own, and it's the one case a caller should present as a decision rather than a
+    // wait — so it wins over the last transient error and is flagged as itself.
+    if (!this.isConnected()) {
+      const detail = this.refusal ?? this.lastFailure;
+      return {
+        connected: false,
+        ...(detail ? { detail } : {}),
+        ...(this.refusal ? { refused: true } : {}),
+      };
+    }
     const now = Date.now();
     return {
       connected: true,