@securecoms/agent-bridge 0.30.1 → 0.30.2

package/README.md

@@ -35,13 +35,9 @@ The server still sees ciphertext only. The trust boundary is the machine running
 - **Node.js 24 LTS or newer.** The daemon requires >= 24 (node:sqlite stable API).
 - A valid SecureComs agent credential (`agent.json`, `chmod 600`)
 
-You don't have to check your Node version yourself. The installer self-checks before anything else runs: on an older Node it prints a clear diagnosis instead of crashing, and on macOS it offers to install Node 24 LTS for you. The install is consent-gated and names its source before asking. If Homebrew is present it runs `brew install node` (user-space, no sudo); otherwise it downloads the official installer from nodejs.org over TLS and verifies the published SHA-256 checksum (an integrity check on the download) before running it.
+You don't have to check your Node version yourself. The installer checks it before anything else runs. On an older Node it says so plainly, and on macOS it offers to install Node 24 from nodejs.org after asking you. That step needs your computer's administrator password. It checks the download's published SHA-256 checksum before running it.
 
-To install Node 24 manually instead:
-
-1. Official installer (recommended): download the Node 24 LTS installer from [nodejs.org](https://nodejs.org) and run it.
-2. Homebrew (macOS): `brew install node`
-3. nvm: `nvm install 24 && nvm use 24`
+To install Node 24 yourself, download the Node 24 LTS installer from [nodejs.org](https://nodejs.org) and run it. Then run the install command again.
 
 Always re-run the install command after upgrading Node — the background service pins the Node path it was installed with.
 
@@ -935,6 +931,44 @@ copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.30.2
+
+<!-- [COPY, approved by Eric 2026-10-15] -->
+
+0.30.2 fixes the guided Node upgrade, makes reinstall safe while the agent is
+running, and prints plain messages when the agent cannot start.
+
+- **The Node upgrade works again on macOS.** When this computer has an older
+  Node, install offers to install Node 24 from nodejs.org. Before 0.30.2 this
+  step could not find the installer and stopped without saying why. It now
+  finds it, checks its published SHA-256 checksum, and asks first:
+  `SecureComs needs Node 24. Install it now from nodejs.org? This needs your
+  computer's administrator password. [y/N]`. If the step fails after you say
+  yes, it prints: `Couldn't install Node 24 from nodejs.org.`
+- **Homebrew is no longer used.** The guided upgrade always uses the
+  nodejs.org installer.
+- **Reinstall while the agent runs.** Install now waits up to 10 seconds for
+  the running Connector to stop before it starts the new one. Before, the new
+  copy could start too early, find the old copy still running, and stay
+  stopped. If the old copy does not stop in time, install starts nothing and
+  tells you to run install again.
+- **Plain messages when the agent cannot start.** A missing, unreadable or
+  invalid key file, or a bad setting in it, now each print one short line
+  that says what to do. File paths are printed only in a terminal, not in the
+  service log.
+- **No key file found.** If the copied install command finds no key file, it
+  prints: `No key file was found in your Downloads folder. Download the key
+  file again from SecureComs, or add --credential <path>.` An empty
+  `--credential` no longer falls back to the `SECURECOMS_CREDENTIAL`
+  environment variable.
+- **Node 24 or newer.** The package now declares `node >= 24`, which the
+  Connector already required to run.
+
+You do not need to change anything after the upgrade. Run the install command
+again only if you want the new install behavior now.
+
+---
+
 ## Release notes: 0.30.1
 
 <!-- [COPY, approved by Eric 2026-10-14] -->

package/dist/bin.d.ts

@@ -7,7 +7,7 @@
  * token, its fingerprint, or its path. This prevents the former
  * `BRIDGE_TOKEN=<value>` leak into journald/launchd logs.
  */
-import { type BridgeConfig } from "./config.js";
+import { type BridgeConfig, type ConfigErrorReason } from "./config.js";
 import { BridgeAgent } from "./bridge-agent.js";
 import { createHttpServer } from "./http-server.js";
 import { attachAgentWebSocket } from "./ws-server.js";
@@ -98,8 +98,27 @@ export interface RunModeDeps {
     exit(code: number): void;
     /** One line of approved user-facing copy (spec §8). */
     print(line: string): void;
+    /**
+     * Whether stderr is a terminal. Under launchd and systemd stderr IS the
+     * service log, so a printed line may carry a path only when this is true
+     * (spec 2026-10-15 §5.3 path rule).
+     */
+    isTTY: boolean;
     log: ServiceLog;
 }
+export type StartupConfigReason = ConfigErrorReason | "identity_id_invalid" | "bind_refused" | "unknown";
+/**
+ * The one human line for a run-mode config refusal (spec 2026-10-15 §5.3,
+ * E1-E7 approved; E5 with source=env is the BT-5 draft). The path is shown
+ * only on a TTY; `field` is one of the six fixed REQUIRED names. `unknown`
+ * has no line. Never built from an error message.
+ */
+export declare function configErrorLine(reason: StartupConfigReason, o: {
+    path: string;
+    isTTY: boolean;
+    field?: string;
+    source?: "file" | "env";
+}): string | undefined;
 /**
  * The daemon's run mode (spec §4.1.1). Order, each step gated on the last:
  *   1. loadConfig (+ daemon args, bind check);

package/dist/bin.js

@@ -8001,8 +8001,30 @@ function ackOnlyGreeting(agentName, callerName) {
 
 // src/config.ts
 var REQUIRED = ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+var CONFIG_ERROR_MESSAGE = {
+  credential_not_found: "credential file not found",
+  credential_unreadable: "credential file could not be read",
+  credential_not_json: "credential file is not valid JSON",
+  credential_missing_field: "credential file missing required field",
+  credential_voice_invalid: "credential file voice config invalid"
+};
+var ConfigError = class extends Error {
+  constructor(reason, field, source) {
+    super(CONFIG_ERROR_MESSAGE[reason] + (field ? `: ${field}` : ""));
+    this.reason = reason;
+    this.field = field;
+    this.source = source;
+    this.name = "ConfigError";
+  }
+};
 function loadConfig(opts) {
-  const raw = readFileSync2(opts.credentialPath, "utf8");
+  let raw;
+  try {
+    raw = readFileSync2(opts.credentialPath, "utf8");
+  } catch (e) {
+    const code = e?.code;
+    throw new ConfigError(code === "ENOENT" ? "credential_not_found" : "credential_unreadable");
+  }
   try {
     const mode = statSync(opts.credentialPath).mode & 511;
     if (mode & 63) writeServiceLog("warn", "config.credential_permissions_unsafe");
@@ -8012,9 +8034,9 @@ function loadConfig(opts) {
   try {
     json2 = JSON.parse(raw);
   } catch {
-    throw new Error("credential file is not valid JSON");
+    throw new ConfigError("credential_not_json");
   }
-  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new Error(`credential file missing required field: ${k}`);
+  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new ConfigError("credential_missing_field", k);
   const storePath = opts.storePath ?? join2(dirname2(opts.credentialPath), "bridge-state.db");
   const ownerGrantPin = loadOwnerGrantPin({ credentialPath: opts.credentialPath, credentialJson: json2 });
   writeServiceLog(ownerGrantPin.state === "ok" || ownerGrantPin.state === "no_pin" ? "info" : "warn", "authz.pin", {
@@ -8052,8 +8074,14 @@ function loadConfig(opts) {
   let voice;
   try {
     voice = parseVoiceConfig(json2.voice, process.env);
-  } catch (e) {
-    throw new Error(`credential file voice config invalid: ${e.message}`);
+  } catch {
+    let source = "env";
+    try {
+      parseVoiceConfig(json2.voice, {});
+    } catch {
+      source = "file";
+    }
+    throw new ConfigError("credential_voice_invalid", void 0, source);
   }
   const modelSource = json2.memory?.model_source === "import_only" ? "import_only" : "download";
   const enabledRaw = json2.memory?.enabled;
@@ -18169,7 +18197,13 @@ var CODES = [
   // lookup missed and before any write, so a retry can never land: the
   // pending commit is dropped instead of being resent forever. The same pair
   // answers an application send into a deleted channel (#325 F5).
-  { status: 409, code: "channel_unavailable" }
+  { status: 409, code: "channel_unavailable" },
+  // ADR-0023 B.1: an Add or Welcome into a humans-only enclave's group naming
+  // a device that is not provably a person's. Refused after the replay lookup
+  // missed and before any write, so nothing landed. Definite: the committer's
+  // work cannot name an agent in a humans-only enclave (admission refuses
+  // one), so dropping the commit starts no resend loop.
+  { status: 403, code: "humans_only_enclave" }
 ];
 var DISTRIBUTE_DEFINITE_CODES = Object.freeze(CODES.map((c) => Object.freeze({ ...c })));
 var DEFINITE_KEYS = new Set(DISTRIBUTE_DEFINITE_CODES.map((c) => `${c.status} ${c.code}`));
@@ -44197,7 +44231,7 @@ function slugify(s) {
 function deriveServiceConfig(input) {
   if (isVersionEmbeddedNodePath(input.execPath)) {
     throw new Error(
-      `install: refusing to bake a version-embedded Node path into the service definition: ${input.execPath}. Re-run install under a system/Homebrew Node, or pass --exec-path <stable-path>.`
+      `The Node at ${input.execPath} moves when it is upgraded, so the background service can't use it. Install Node ${REQUIRED_NODE_MAJOR} from https://nodejs.org, then run the install command again.`
     );
   }
   const stem = input.label ?? basename5(input.credentialPath, extname(input.credentialPath));
@@ -44278,6 +44312,26 @@ WantedBy=default.target
 // src/service/install.ts
 var ServiceUnsupportedError = class extends Error {
 };
+var PREVIOUS_EXIT_WAIT_MS = 1e4;
+var PREVIOUS_EXIT_POLL_MS = 100;
+function launchdPid(deps, target) {
+  const r = deps.run("launchctl", ["print", target]);
+  if (r.status !== 0) return void 0;
+  const m = /^\s*pid = (\d+)\s*$/m.exec(r.stdout);
+  const pid = m ? Number(m[1]) : NaN;
+  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+}
+function waitForPreviousExit(deps, pid) {
+  const deadline = deps.now() + PREVIOUS_EXIT_WAIT_MS;
+  while (deps.pidAlive(pid)) {
+    if (deps.now() >= deadline) {
+      throw new Error(
+        `the previous bridge (pid ${pid}) did not exit within ${PREVIOUS_EXIT_WAIT_MS / 1e3} s of launchctl bootout, so a new copy would find the instance lock held and stay down. Wait for that process to exit (check with: ps -p ${pid}), then run install again.`
+      );
+    }
+    deps.sleepMs(PREVIOUS_EXIT_POLL_MS);
+  }
+}
 function tokenHint(input) {
   return `${dirname8(input.credentialPath)}/bridge-token`;
 }
@@ -44290,7 +44344,10 @@ function installService(input, deps) {
     deps.mkdirp(dirname8(cfg.plistPath));
     deps.mkdirp(dirname8(cfg.logPath));
     deps.writeFile(cfg.plistPath, renderLaunchdPlist(cfg));
-    deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
+    const target = `gui/${cfg.uid}/${cfg.label}`;
+    const previousPid = launchdPid(deps, target);
+    deps.run("launchctl", ["bootout", target]);
+    if (previousPid !== void 0) waitForPreviousExit(deps, previousPid);
     requireOk(deps.run("launchctl", ["bootstrap", `gui/${cfg.uid}`, cfg.plistPath]), "launchctl bootstrap");
     deps.run("launchctl", ["enable", `gui/${cfg.uid}/${cfg.label}`]);
     requireOk(deps.run("launchctl", ["kickstart", "-k", `gui/${cfg.uid}/${cfg.label}`]), "launchctl kickstart");
@@ -45617,6 +45674,20 @@ function runPinCli(argv, io) {
   return 1;
 }
 
+// src/service/credential-arg.ts
+function readCredentialArg(argv, env) {
+  const i = argv.indexOf("--credential");
+  if (i >= 0) {
+    const v = argv[i + 1];
+    return v ? { kind: "path", path: v } : { kind: "empty_flag" };
+  }
+  const fromEnv = env.SECURECOMS_CREDENTIAL;
+  return fromEnv ? { kind: "path", path: fromEnv } : { kind: "absent" };
+}
+function noCredentialLine(verb) {
+  return verb === "run" ? "No key file was given. If you used the copied run command, no key file for this agent was found in your Downloads folder." : "No key file was found in your Downloads folder. Download the key file again from SecureComs, or add --credential <path>.";
+}
+
 // src/bin.ts
 function nodeMajorOk(version) {
   return Number(version.split(".")[0]) >= 24;
@@ -45653,15 +45724,22 @@ function realServiceDeps() {
     removeFile: (p) => rmSync8(p, { force: true }),
     mkdirp: (p) => mkdirSync8(p, { recursive: true }),
     fileExists: (p) => existsSync7(p),
-    user: userInfo().username
+    user: userInfo().username,
+    pidAlive: pidAliveByKill,
+    // installService is synchronous; Atomics.wait is a real blocking sleep.
+    sleepMs: (ms) => {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    },
+    now: () => Date.now()
   };
 }
 function chooseInstallExecPath(runningExecPath, override, deps) {
   if (override) return override;
   const r = resolveStableNodePath(runningExecPath, deps);
   if (!r.stable) {
+    const list = STABLE_LOCATIONS.slice(0, -1).join(", ") + " or " + STABLE_LOCATIONS[STABLE_LOCATIONS.length - 1];
     throw new Error(
-      "install: no reboot-stable Node found. Version-manager Nodes (nvm/asdf/fnm/volta/n) are removed on upgrade and will break the daemon after a reboot. Install a system Node (nodejs.org pkg \u2192 /usr/local/bin/node) or pass --exec-path <stable-path> to override."
+      "The agent's background service needs Node " + REQUIRED_NODE_MAJOR + " or newer at a fixed location (" + list + "), and none was found. Node from nvm, fnm and similar tools moves when it is upgraded, so it is not used. Install Node " + REQUIRED_NODE_MAJOR + " from https://nodejs.org, then run the install command again."
     );
   }
   return r.path;
@@ -45841,9 +45919,17 @@ function runWireVerb(verb) {
   process.exit(verb === "wire" ? runWire(realWireDeps()) : runUnwire(realWireDeps()));
 }
 async function runServiceVerb(verb) {
-  const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
+  let credentialPath;
+  if (verb === "install") {
+    const cred = readCredentialArg(process.argv, process.env);
+    credentialPath = cred.kind === "path" ? cred.path : void 0;
+  } else {
+    credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
+  }
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
   if (verb === "install" ? !credentialPath : !credentialPath && !label) {
+    if (verb === "install") process.stderr.write(`${noCredentialLine("install")}
+`);
     const execPathUsage = verb === "install" ? " [--exec-path <path>]" : "";
     process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|universal]${execPathUsage}
 `);
@@ -45966,6 +46052,26 @@ var HELD_POLL_TOTAL_MS = 1e4;
 var HELD_POLL_INTERVAL_MS = 500;
 var HELD_NO_PID_REACQUIRES = 3;
 var SHUTDOWN_HARD_EXIT_MS = 8e3;
+function configErrorLine(reason, o) {
+  const at = o.isTTY ? ` at ${o.path}` : "";
+  switch (reason) {
+    case "credential_not_found":
+      return `Can't find the key file${at}. Check the path after --credential.`;
+    case "credential_unreadable":
+      return `Can't open the key file${at}. Check that it exists and that your user can read it.`;
+    case "credential_not_json":
+    case "identity_id_invalid":
+      return `The key file${at} is damaged. Get a new key file from the agent's page in SecureComs.`;
+    case "credential_missing_field":
+      return `The key file${at} is incomplete (no ${o.field}). Get a new key file from the agent's page in SecureComs.`;
+    case "credential_voice_invalid":
+      return o.source === "env" ? "The voice settings in this computer's environment are not valid." : `The voice settings in the key file${at} are not valid.`;
+    case "bind_refused":
+      return "The Connector only accepts connections from this computer unless TLS is set. Remove --bind, or add --tls-cert and --tls-key.";
+    case "unknown":
+      return void 0;
+  }
+}
 function realRunModeDeps(credentialPath, storePath) {
   return {
     credentialPath,
@@ -45996,22 +46102,56 @@ function realRunModeDeps(credentialPath, storePath) {
       process.stderr.write(`${line}
 `);
     },
+    isTTY: process.stderr.isTTY === true,
     log: writeServiceLog
   };
 }
 async function runMode(deps) {
   const { credentialPath, storePath, log } = deps;
+  const refuse2 = (reason, extra, e) => {
+    const fields = {
+      reason: ServiceLogEnum.of(reason, [
+        "credential_not_found",
+        "credential_unreadable",
+        "credential_not_json",
+        "credential_missing_field",
+        "credential_voice_invalid",
+        "identity_id_invalid",
+        "bind_refused",
+        "unknown"
+      ])
+    };
+    if (extra.field) {
+      fields.field = ServiceLogEnum.of(extra.field, [
+        "api_key",
+        "identity_id",
+        "device_id",
+        "signing_private_key",
+        "enclave_id",
+        "api_base"
+      ]);
+    }
+    log("error", "startup.config_invalid", fields, e);
+    const line = configErrorLine(reason, { path: credentialPath, isTTY: deps.isTTY, ...extra });
+    if (line !== void 0) deps.print(line);
+  };
   let cfg, daemon;
   try {
     cfg = loadConfig({ credentialPath, storePath });
     daemon = parseDaemonArgs(deps.argv, deps.env);
+  } catch (e) {
+    if (e instanceof ConfigError) refuse2(e.reason, { field: e.field, source: e.source }, e);
+    else refuse2("unknown", {}, e);
+    return deps.exit(1);
+  }
+  try {
     validateBind(daemon.bind, daemon.tls);
   } catch (e) {
-    log("error", "startup.config_invalid", {}, e);
+    refuse2("bind_refused", {}, e);
     return deps.exit(1);
   }
   if (!CANONICAL_UUID2.test(cfg.identityId)) {
-    log("error", "startup.config_invalid", { field: ServiceLogEnum.of("identity_id", ["identity_id"]) });
+    refuse2("identity_id_invalid", { field: "identity_id" });
     return deps.exit(1);
   }
   const lockDir = join25(deps.home, ".securecoms", "locks");
@@ -46050,7 +46190,9 @@ async function runMode(deps) {
         lock_path: ServiceLogEnum.of("home_securecoms_locks_identity", ["home_securecoms_locks_identity"]),
         remedy: ServiceLogEnum.of("delete_lock_if_no_other_host", ["delete_lock_if_no_other_host"])
       });
-      deps.print(`This agent's lock file was written under a different computer name: ${lockPath}. If no other computer runs this agent, delete that file and start the agent again.`);
+      deps.print(
+        deps.isTTY ? `This agent's lock file was written under a different computer name: ${lockPath}. If no other computer runs this agent, delete that file and start the agent again.` : "This agent's lock file was written under a different computer name. If no other computer runs this agent, delete that file and start the agent again."
+      );
       return deps.exit(1);
     case "unreadable":
       log("error", "startup.instance_lock_unreadable", {}, lock.lastError);
@@ -46171,6 +46313,10 @@ async function runMode(deps) {
     }
   });
 }
+function printNoCredentialRunLine() {
+  process.stderr.write(`${noCredentialLine("run")}
+`);
+}
 async function main() {
   if (!nodeMajorOk(process.versions.node)) {
     writeServiceLog("error", "startup.node_unsupported");
@@ -46197,11 +46343,13 @@ async function main() {
     await runServiceVerb(verb);
     return;
   }
-  const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
-  if (!credentialPath) {
+  const cred = readCredentialArg(process.argv, process.env);
+  if (cred.kind !== "path") {
+    printNoCredentialRunLine();
     writeServiceLog("error", "startup.credential_required.use_--credential");
     process.exit(2);
   }
+  const credentialPath = cred.path;
   const storePath = argOrEnv("--store", "SECURECOMS_STORE");
   await runMode(realRunModeDeps(credentialPath, storePath));
 }
@@ -46219,6 +46367,7 @@ export {
   HELD_POLL_TOTAL_MS,
   SHUTDOWN_HARD_EXIT_MS,
   chooseInstallExecPath,
+  configErrorLine,
   formatServiceError,
   nodeMajorOk,
   parseVerb,

package/dist/config.d.ts

@@ -56,6 +56,19 @@ export interface BridgeConfig {
     ownerGrantPin?: OwnerGrantPinResult;
 }
 export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+export type ConfigErrorReason = "credential_not_found" | "credential_unreadable" | "credential_not_json" | "credential_missing_field" | "credential_voice_invalid";
+/**
+ * A key-file load failure with a fixed reason code, set by the step that
+ * failed (spec 2026-10-15 §5.2). Callers map the code to a log field and a
+ * fixed human line; nothing reads `message`, which carries no path, no
+ * identifier and no upstream error text.
+ */
+export declare class ConfigError extends Error {
+    readonly reason: ConfigErrorReason;
+    readonly field?: (typeof REQUIRED)[number] | undefined;
+    readonly source?: "file" | "env" | undefined;
+    constructor(reason: ConfigErrorReason, field?: (typeof REQUIRED)[number] | undefined, source?: "file" | "env" | undefined);
+}
 export declare function loadConfig(opts: {
     credentialPath: string;
     storePath?: string;

package/dist/index.js

@@ -17457,7 +17457,13 @@ var CODES = [
   // lookup missed and before any write, so a retry can never land: the
   // pending commit is dropped instead of being resent forever. The same pair
   // answers an application send into a deleted channel (#325 F5).
-  { status: 409, code: "channel_unavailable" }
+  { status: 409, code: "channel_unavailable" },
+  // ADR-0023 B.1: an Add or Welcome into a humans-only enclave's group naming
+  // a device that is not provably a person's. Refused after the replay lookup
+  // missed and before any write, so nothing landed. Definite: the committer's
+  // work cannot name an agent in a humans-only enclave (admission refuses
+  // one), so dropping the commit starts no resend loop.
+  { status: 403, code: "humans_only_enclave" }
 ];
 var DISTRIBUTE_DEFINITE_CODES = Object.freeze(CODES.map((c) => Object.freeze({ ...c })));
 var DEFINITE_KEYS = new Set(DISTRIBUTE_DEFINITE_CODES.map((c) => `${c.status} ${c.code}`));
@@ -42821,8 +42827,30 @@ ${channelId}`;
 import { readFileSync as readFileSync10, statSync as statSync5 } from "node:fs";
 import { dirname as dirname6, join as join18 } from "node:path";
 var REQUIRED = ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+var CONFIG_ERROR_MESSAGE = {
+  credential_not_found: "credential file not found",
+  credential_unreadable: "credential file could not be read",
+  credential_not_json: "credential file is not valid JSON",
+  credential_missing_field: "credential file missing required field",
+  credential_voice_invalid: "credential file voice config invalid"
+};
+var ConfigError = class extends Error {
+  constructor(reason, field, source) {
+    super(CONFIG_ERROR_MESSAGE[reason] + (field ? `: ${field}` : ""));
+    this.reason = reason;
+    this.field = field;
+    this.source = source;
+    this.name = "ConfigError";
+  }
+};
 function loadConfig(opts) {
-  const raw = readFileSync10(opts.credentialPath, "utf8");
+  let raw;
+  try {
+    raw = readFileSync10(opts.credentialPath, "utf8");
+  } catch (e) {
+    const code = e?.code;
+    throw new ConfigError(code === "ENOENT" ? "credential_not_found" : "credential_unreadable");
+  }
   try {
     const mode = statSync5(opts.credentialPath).mode & 511;
     if (mode & 63) writeServiceLog2("warn", "config.credential_permissions_unsafe");
@@ -42832,9 +42860,9 @@ function loadConfig(opts) {
   try {
     json2 = JSON.parse(raw);
   } catch {
-    throw new Error("credential file is not valid JSON");
+    throw new ConfigError("credential_not_json");
   }
-  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new Error(`credential file missing required field: ${k}`);
+  for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new ConfigError("credential_missing_field", k);
   const storePath = opts.storePath ?? join18(dirname6(opts.credentialPath), "bridge-state.db");
   const ownerGrantPin = loadOwnerGrantPin({ credentialPath: opts.credentialPath, credentialJson: json2 });
   writeServiceLog2(ownerGrantPin.state === "ok" || ownerGrantPin.state === "no_pin" ? "info" : "warn", "authz.pin", {
@@ -42872,8 +42900,14 @@ function loadConfig(opts) {
   let voice;
   try {
     voice = parseVoiceConfig(json2.voice, process.env);
-  } catch (e) {
-    throw new Error(`credential file voice config invalid: ${e.message}`);
+  } catch {
+    let source = "env";
+    try {
+      parseVoiceConfig(json2.voice, {});
+    } catch {
+      source = "file";
+    }
+    throw new ConfigError("credential_voice_invalid", void 0, source);
   }
   const modelSource = json2.memory?.model_source === "import_only" ? "import_only" : "download";
   const enabledRaw = json2.memory?.enabled;

package/dist/preflight-upgrade.d.cts

@@ -14,8 +14,6 @@ export interface UpgradeDeps {
     isTTY: boolean;
     stderr: (s: string) => void;
     ask: (q: string) => Promise<string>;
-    hasBrew: () => boolean;
-    runBrew: () => number;
     fetchText: (url: string) => Promise<string>;
     fetchBinary: (url: string, destPath: string) => Promise<void>;
     fileSha256: (p: string) => string;

package/dist/preflight.cjs

@@ -41,11 +41,10 @@ __export(preflight_upgrade_exports, {
   sha256Hex: () => sha256Hex
 });
 function parseShasums(text, arch) {
-  const want = "-darwin-" + arch + ".pkg";
   const lines = String(text).split("\n");
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].trim().match(/^([0-9a-f]{6,64})\s+(\S+)$/);
-    if (m && m[2].indexOf(want) !== -1 && m[2].indexOf("node-v24.") === 0) {
+    if (m && PKG_NAME.test(m[2])) {
       return { filename: m[2], sha256: m[1] };
     }
   }
@@ -62,48 +61,47 @@ async function promptYesNo(question, deps) {
 }
 async function guidedUpgrade(deps) {
   if (deps.platform !== "darwin") return false;
+  let consented = false;
+  const failed = () => {
+    if (consented) deps.stderr("[bridge] Couldn't install Node 24 from nodejs.org.\n");
+    return false;
+  };
   try {
     const existing = deps.existingCompatibleNode();
     if (existing) {
       deps.stderr(
-        "[bridge] Node " + deps.activeVersion + " is running, but a compatible Node (>= " + REQUIRED_NODE_MAJOR + ") is already installed at " + existing + " \u2014 it is shadowed earlier on your PATH. Continuing under it (no install needed).\n"
+        "[bridge] Using Node " + REQUIRED_NODE_MAJOR + " or newer found at " + existing + ". (The node command on this computer is an older version.)\n"
       );
       return deps.reexec(existing);
     }
-    const viaBrew = deps.hasBrew();
-    const source = viaBrew ? "Homebrew (brew install node \u2014 user-space, no sudo)" : "the official installer from " + DIST_BASE + " (needs your admin password)";
     const ok = await promptYesNo(
-      "[bridge] Node 24 LTS is required. Install it now via " + source + "? [y/N] ",
+      "[bridge] SecureComs needs Node 24. Install it now from nodejs.org? This needs your computer's administrator password. [y/N] ",
       deps
     );
     if (!ok) return false;
-    if (viaBrew) {
-      deps.stderr("[bridge] running: brew install node\n");
-      if (deps.runBrew() !== 0) return false;
-    } else {
-      const shasums = await deps.fetchText(DIST_BASE + "/SHASUMS256.txt");
-      const entry = parseShasums(shasums, deps.arch);
-      if (!entry) return false;
-      const dest = deps.tmpdir() + "/" + entry.filename;
-      deps.stderr("[bridge] downloading " + DIST_BASE + "/" + entry.filename + "\n");
-      try {
-        await deps.fetchBinary(DIST_BASE + "/" + entry.filename, dest);
-        if (deps.fileSha256(dest) !== entry.sha256) {
-          deps.stderr("[bridge] checksum mismatch \u2014 aborting install (file discarded)\n");
-          return false;
-        }
-        deps.stderr("[bridge] running: sudo installer -pkg " + entry.filename + " -target /\n");
-        if (deps.runSudoInstaller(dest) !== 0) return false;
-      } finally {
-        deps.cleanup(dest);
+    consented = true;
+    const shasums = await deps.fetchText(DIST_BASE + "/SHASUMS256.txt");
+    const entry = parseShasums(shasums, deps.arch);
+    if (!entry) return failed();
+    const dest = deps.tmpdir() + "/" + entry.filename;
+    deps.stderr("[bridge] downloading " + DIST_BASE + "/" + entry.filename + "\n");
+    try {
+      await deps.fetchBinary(DIST_BASE + "/" + entry.filename, dest);
+      if (deps.fileSha256(dest) !== entry.sha256) {
+        deps.stderr("[bridge] checksum mismatch \u2014 aborting install (file discarded)\n");
+        return failed();
       }
+      deps.stderr("[bridge] running: sudo installer -pkg " + entry.filename + " -target /\n");
+      if (deps.runSudoInstaller(dest) !== 0) return failed();
+    } finally {
+      deps.cleanup(dest);
     }
     const fresh = deps.resolveNewNode();
-    if (!fresh) return false;
+    if (!fresh) return failed();
     deps.stderr("[bridge] Node 24 installed \u2014 continuing under " + fresh + "\n");
     return deps.reexec(fresh);
   } catch {
-    return false;
+    return failed();
   }
 }
 function resolveNewNodeFrom(probe, candidates) {
@@ -152,11 +150,6 @@ function realUpgradeDeps(originalArgv) {
         resolve(a);
       });
     }),
-    hasBrew: () => spawnSync("brew", ["--version"], { stdio: "ignore" }).status === 0,
-    runBrew: () => {
-      var _a;
-      return (_a = spawnSync("brew", ["install", "node"], { stdio: "inherit" }).status) != null ? _a : 1;
-    },
     fetchText: async (url) => {
       const res = await fetch(url, 3);
       let out = "";
@@ -197,12 +190,13 @@ function realUpgradeDeps(originalArgv) {
     }
   };
 }
-var DIST_BASE, NODE_CANDIDATES;
+var DIST_BASE, PKG_NAME, NODE_CANDIDATES;
 var init_preflight_upgrade = __esm({
   "src/preflight-upgrade.cts"() {
     "use strict";
     init_resolve_node();
     DIST_BASE = "https://nodejs.org/dist/latest-v24.x";
+    PKG_NAME = /^node-v24\.\d+\.\d+\.pkg$/;
     NODE_CANDIDATES = [
       "/usr/local/bin/node",
       // nodejs.org pkg (stable across upgrades)
@@ -216,6 +210,7 @@ var init_preflight_upgrade = __esm({
 // src/preflight.cts
 var preflight_exports = {};
 __export(preflight_exports, {
+  NODE_FLOOR: () => NODE_FLOOR,
   effectiveVersion: () => effectiveVersion,
   instructionsBlock: () => instructionsBlock,
   meetsFloor: () => meetsFloor,
@@ -224,7 +219,6 @@ __export(preflight_exports, {
 });
 module.exports = __toCommonJS(preflight_exports);
 var NODE_FLOOR = 24;
-var FLOOR_REASON = "requires >= 24 (node:sqlite stable API)";
 function parseNodeMajor(version) {
   const n = Number(String(version).split(".")[0]);
   return Number.isFinite(n) && n > 0 ? n : 0;
@@ -239,23 +233,30 @@ function effectiveVersion(real, faked) {
   return real;
 }
 function instructionsBlock(platform, current) {
-  const lines = [
-    "[bridge] Node " + current + " is too old \u2014 SecureComs " + FLOOR_REASON + ".",
-    "",
-    "How to get Node 24 LTS:",
-    "  1. Official installer (recommended): https://nodejs.org \u2014 download the",
-    "     Node 24 LTS installer for your platform and run it."
-  ];
+  const n = String(NODE_FLOOR);
+  const head = "[bridge] This computer has Node " + current + ". SecureComs needs Node " + n + " or newer.";
+  let lines;
   if (platform === "darwin") {
-    lines.push("  2. Homebrew: brew install node");
+    lines = [
+      head,
+      "",
+      "To get Node " + n + ":",
+      "  1. Download the Node " + n + " LTS installer for macOS from https://nodejs.org and run it.",
+      "  2. Run the SecureComs install command again."
+    ];
+  } else if (platform === "win32") {
+    lines = [
+      head,
+      "",
+      "Install Node " + n + " from https://nodejs.org, then run the SecureComs install command again."
+    ];
+  } else {
+    lines = [
+      head,
+      "",
+      "Install Node " + n + " so that it is at /usr/local/bin/node or /usr/bin/node, then run the SecureComs install command again. See https://nodejs.org for options."
+    ];
   }
-  lines.push("  " + (platform === "darwin" ? "3" : "2") + ". nvm:      nvm install 24 && nvm use 24");
-  lines.push(
-    "",
-    "Then re-run the install command. (Always re-run the install command after",
-    "upgrading Node \u2014 the background service pins the Node path it was",
-    "installed with.)"
-  );
   return lines.join("\n") + "\n";
 }
 async function runPreflight(deps) {
@@ -292,6 +293,7 @@ if (require.main === module) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  NODE_FLOOR,
   effectiveVersion,
   instructionsBlock,
   meetsFloor,

package/dist/preflight.d.cts

@@ -1,4 +1,18 @@
 #!/usr/bin/env node
+/**
+ * CommonJS preflight shim — the package's bin entry. CJS on purpose: any
+ * Node back to v10 can parse it, so a machine with stale Node always gets
+ * the friendly diagnosis instead of an ESM/builtin crash (static imports in
+ * the ESM bundle hoist — node:sqlite would detonate before any guard ran).
+ * Built with esbuild format=cjs target=node10 to dist/preflight.cjs.
+ *
+ * AUDIT C1: this file must contain ZERO dynamic `import()` — esbuild's
+ * node10 downlevel would turn it into require() (cannot load ESM), and
+ * keeping the syntax breaks node10 parse. The real import lives in
+ * preflight-modern.cts, which is only require()d AFTER the gate passes.
+ * An artifact test greps the emitted file to pin this.
+ */
+export declare const NODE_FLOOR = 24;
 export declare function parseNodeMajor(version: string): number;
 export declare function meetsFloor(version: string): boolean;
 export declare function effectiveVersion(real: string, faked: string | undefined): string;

package/dist/service/credential-arg.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How `--credential` is read for `install` and run mode (spec 2026-10-15
+ * §5.3, OQ-18 (b)). A flag that is present with an empty value means "no key
+ * file": it never falls back to SECURECOMS_CREDENTIAL, so a copied command
+ * whose Downloads lookup found nothing cannot silently pick up a different
+ * agent's key file from the environment. The variable is used only when the
+ * flag is absent. Every other flag keeps argOrEnv's behaviour.
+ */
+export type CredentialArg = {
+    kind: "path";
+    path: string;
+} | {
+    kind: "empty_flag";
+} | {
+    kind: "absent";
+};
+export declare function readCredentialArg(argv: string[], env: NodeJS.ProcessEnv): CredentialArg;
+/**
+ * The one line printed when no key file was given: E8 for run mode
+ * (approved), E9 for install (DRAFT: the approved E9 names the agent, which
+ * the bridge cannot know when no key file was found).
+ */
+export declare function noCredentialLine(verb: "run" | "install"): string;

package/dist/service/install.d.ts

@@ -13,7 +13,14 @@ export interface ServiceDeps {
     mkdirp: (path: string) => void;
     fileExists: (path: string) => boolean;
     user: string;
+    /** kill(pid, 0): true while the process runs (EPERM counts as running). */
+    pidAlive: (pid: number) => boolean;
+    /** Blocking sleep: installService is synchronous end to end. */
+    sleepMs: (ms: number) => void;
+    now: () => number;
 }
+/** How long install waits for the previous bridge to exit after bootout. */
+export declare const PREVIOUS_EXIT_WAIT_MS = 10000;
 export interface InstallResult {
     label: string;
     filePath: string;

package/dist/service/resolve-node.d.ts

@@ -7,6 +7,7 @@ export interface ResolveNodeDeps {
     arch: () => string;
     archOf: (p: string) => string | null;
 }
+export declare const STABLE_LOCATIONS: readonly string[];
 export declare function resolveStableNodePath(runningExecPath: string, deps: ResolveNodeDeps): {
     path: string;
     stable: boolean;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.30.1";
+export declare const BRIDGE_VERSION = "0.30.2";

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "type": "module",
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=24"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",