@securecoms/agent-bridge 0.30.0 → 0.30.2

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-prep.d.ts

@@ -1,5 +1,19 @@
 import { type ServiceInput } from "./config.js";
 import { type AutoWireDeps } from "./harness-wire.js";
+/** The parsed `/healthz` body fields the install and status liveness checks read. */
+export interface DaemonHealth {
+    agent_sessions?: number;
+    evictions?: number;
+    state?: string;
+}
+/**
+ * Liveness is a routed `/healthz` 200 whose state is not `session_superseded`
+ * (P-2). A TCP accept proves nothing: the daemon pre-binds its port before
+ * `agent.start()`, so a connect succeeds before the bridge routes anything.
+ */
+export declare function isDaemonRouted(h: DaemonHealth | null): h is DaemonHealth;
+/** Default install wait: the boot drain may take up to BOOT_DRAIN_WAIT_MS_DEFAULT, plus 15 s. */
+export declare const VERIFY_BUDGET_MS: number;
 export interface PrepDeps {
     readFile: (p: string) => string;
     writeFileMode: (p: string, data: string, mode: number) => void;
@@ -8,8 +22,11 @@ export interface PrepDeps {
     realpath: (p: string) => string;
     listDir: (p: string) => string[];
     probeBindFree: (port: number) => boolean;
-    probeConnect: (port: number) => boolean;
+    /** Routed `/healthz` probe (P-2): null unless the daemon answered a 200 with parseable JSON. */
+    getHealth: (port: number) => DaemonHealth | null;
     sleep: (ms: number) => Promise<void>;
+    /** Wall clock in ms (Date.now). verifyDaemonUp's deadline reads it, so probe time counts, not only sleep. */
+    now: () => number;
 }
 export interface ParsedCredential {
     deviceId: string;
@@ -19,6 +36,9 @@ export interface ParsedCredential {
 export declare function assertReadableCredential(absPath: string, deps: PrepDeps): ParsedCredential;
 export declare function durableDir(home: string, slug: string): string;
 export declare function durableCredentialPath(home: string, slug: string): string;
+/** M5 (OQ-3): the approved refusal text for an identity that is already installed. */
+export declare class InstallRefusedError extends Error {
+}
 export declare function takeCustody(args: {
     home: string;
     slug: 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/instance-lock.d.ts

@@ -0,0 +1,88 @@
+import type { ServiceLog } from "../service-log.js";
+/** An unparseable lock this young may be a holder mid-write. */
+export declare const LOCK_PARTIAL_WRITE_GRACE_MS = 10000;
+/** A takeover guard this old was left by a crashed takeover. */
+export declare const LOCK_TAKEOVER_GUARD_STALE_MS = 30000;
+/** Two boot-epoch reads further apart than this are two different boots. */
+export declare const BOOT_TOLERANCE_SEC = 120;
+/** A holder refreshes its lock's mtime this often (#808 N1). */
+export declare const LOCK_HEARTBEAT_MS = 60000;
+/** A same-kernel, other-hostname lock untouched for this long is abandoned. */
+export declare const LOCK_FOREIGN_STALE_MS: number;
+export type LockRefusal = "held" | "foreign_host" | "unreadable" | "busy" | "failed";
+export type LockResult = "acquired" | LockRefusal;
+/** Everything the lock reads about the machine. Injected in tests. */
+export interface LockEnv {
+    pid: number;
+    hostname(): string;
+    /** Linux boot_id, or undefined where the platform has none. */
+    bootId(): string | undefined;
+    bootEpochSec(): number;
+    /** Linux /proc/<pid>/stat start time, or undefined (not Linux / no such pid). */
+    procStart(pid: number): string | undefined;
+    /** kill(pid, 0): true when running (EPERM counts as running). */
+    pidAlive(pid: number): boolean;
+    /** Test seam: runs after the takeover guard is taken, before the re-read. */
+    beforeTakeoverReread?(): void;
+    /** Test seam: runs after the stale lock is unlinked, before our create. */
+    beforeTakeoverCreate?(): void;
+    /** Test seam: runs after an O_EXCL create found the lock, before it is read. */
+    beforeLockRead?(): void;
+}
+/** Field 22 of /proc/<pid>/stat. The comm field (2) may contain spaces or
+ *  parentheses, so fields are counted from the LAST ')'. */
+export declare function procStartFromStat(stat: string): string | undefined;
+export declare function pidAliveByKill(pid: number): boolean;
+export declare const realLockEnv: LockEnv;
+export declare class InstanceLock {
+    readonly path: string;
+    private readonly env;
+    private readonly log;
+    private readonly heartbeatMs;
+    held: boolean;
+    /** The exact body this process wrote (#808 N1): release and the ownership
+     *  check compare the file against THIS, never against live machine facts
+     *  (a hostname can change under a running process). */
+    private written;
+    private heartbeat;
+    /** The error behind the last `unreadable` / `failed`, for the caller's one
+     *  log line (the lock itself never logs a refusal: it is retried per call). */
+    lastError: unknown;
+    /** PID read from the lock body of the live holder behind the last `held`. */
+    private holderPid;
+    constructor(path: string, env?: LockEnv, log?: ServiceLog, heartbeatMs?: number);
+    private body;
+    /** Try to hold the lock. Never throws (#808 L-e: machine reads included). */
+    acquire(): {
+        result: LockResult;
+        holderPid?: number;
+    };
+    /**
+     * True while the file is still exactly the body this process wrote. Read
+     * before every reserve (one small read), so a holder whose lock was taken
+     * while it was frozen stops before it spends (#808 N1). A lost lock is
+     * dropped: the caller then refuses, and later calls try to re-acquire.
+     */
+    stillHeld(): boolean;
+    private acquireUnguarded;
+    /** Remove the lock only while it is still exactly the body this process
+     *  wrote (#808 N1: not the live hostname, which can change under us). */
+    release(): void;
+    private drop;
+    /** We hold it: remember what we wrote (the file as it is now, ours) and
+     *  start the heartbeat. */
+    private took;
+    /** Refresh the mtime while the file is still ours; stop if it is not. */
+    private beat;
+    private sameBoot;
+    /** O_EXCL create with our body. A write failure removes the half-written
+     *  file (it is ours: we created it) and reports `failed`, never throws. */
+    private create;
+    /**
+     * Replace a stale lock. Only the holder of the O_EXCL takeover guard may
+     * remove a lock, and only after re-reading it UNCHANGED, so two runtimes
+     * that both saw the same stale lock cannot each delete the other's new one.
+     * A fresh guard means a takeover is in progress: busy this time.
+     */
+    private takeOver;
+}

package/dist/service/launchd.d.ts

@@ -1,4 +1,4 @@
 import type { ServiceConfig } from "./config.js";
 /** A deterministic launchd LaunchAgent plist. ProgramArguments re-invoke the
- *  running bin in run mode; KeepAlive restarts on crash, RunAtLoad starts at login. */
+ *  running bin in run mode; KeepAlive{SuccessfulExit:false} restarts only on a non-zero exit (a clean exit stays down), RunAtLoad starts at login. */
 export declare function renderLaunchdPlist(cfg: ServiceConfig): 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/service/status.d.ts

@@ -1,11 +1,9 @@
 import type { AgentFleetEntry } from "./fleet.js";
+import { type DaemonHealth } from "./install-prep.js";
 export interface StatusDeps {
     readFleet: () => AgentFleetEntry[];
-    probeConnect: (port: number) => boolean;
-    getHealth: (port: number) => {
-        agent_sessions?: number;
-        evictions?: number;
-    } | null;
+    /** Routed `/healthz` probe (P-2): null unless the daemon answered a 200. */
+    getHealth: (port: number) => DaemonHealth | null;
 }
 export interface AgentStatusRow {
     slug: string;

package/dist/service/systemd.d.ts

@@ -1,4 +1,4 @@
 import type { ServiceConfig } from "./config.js";
 /** A systemd --user unit. ExecStart re-invokes the running bin in run mode;
- *  Restart=always supervises crashes. WantedBy=default.target enables at login. */
+ *  Restart=on-failure supervises crashes only (a clean exit stays down). WantedBy=default.target enables at login. */
 export declare function renderSystemdUnit(cfg: ServiceConfig): string;

package/dist/version.d.ts

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

package/dist/ws-server.d.ts

@@ -34,6 +34,9 @@ export declare const INFLIGHT_STALE_AFTER_MS: number;
  * consumer, so it never carried its notes.
  */
 export declare const HELLO_WAIT_MS = 2000;
+/** C9: the close code a superseded bridge sends its local runtime sockets;
+ *  the same code the server sends the bridge (spec §4.1.5, OQ-9). */
+export declare const WS_CLOSE_SESSION_SUPERSEDED = 4409;
 /** Spec §8.5: the hello-reply feature that tells the runtime it may offer memory_note on this socket. */
 export declare const MEMORY_NOTES_FEATURE = "memory_notes";
 /** Semantic memory 7b (spec §7.2 Q4): the hello feature a runtime declares to receive `memory.recall`; the bridge echoes it. */
@@ -52,4 +55,5 @@ export declare const WS_AGENT_MEMBERS: readonly ["ackRuntimeMessages", "action",
 export type WsAgent = Pick<BridgeAgent, (typeof WS_AGENT_MEMBERS)[number]>;
 export declare function attachAgentWebSocket(server: HttpServer, agent: WsAgent, opts: AgentWebSocketOptions): {
     close(): void;
+    enterSessionSuperseded(): void;
 };

package/package.json

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