@securecoms/agent-bridge 0.30.0 → 0.30.2

package/dist/bin.js

@@ -7556,7 +7556,7 @@ __export(import_bundle_exports, {
   importModelBundle: () => importModelBundle
 });
 import { createHash as createHash6, randomBytes as randomBytes12 } from "node:crypto";
-import { readFileSync as readFileSync14, statSync as statSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { readFileSync as readFileSync15, statSync as statSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join24 } from "node:path";
 async function importModelBundle(srcDir, root3, m) {
   const verified = [];
@@ -7564,7 +7564,7 @@ async function importModelBundle(srcDir, root3, m) {
     const src = join24(srcDir, f.name);
     let size;
     try {
-      const s = statSync6(src);
+      const s = statSync7(src);
       if (!s.isFile()) throw new Error("not a file");
       size = s.size;
     } catch {
@@ -7574,7 +7574,7 @@ async function importModelBundle(srcDir, root3, m) {
     if (size !== f.size) throw mismatch;
     let bytes;
     try {
-      bytes = readFileSync14(src);
+      bytes = readFileSync15(src);
     } catch {
       throw new ModelImportError(`${f.name} is missing from the import directory`);
     }
@@ -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}`));
@@ -24803,6 +24837,7 @@ function base64UrlNoPad(s) {
 }
 var BEARER_SUBPROTOCOL = "securecoms.bearer.v1";
 var WS_CLOSE_IDENTITY_REVOKED = 4006;
+var WS_CLOSE_SESSION_SUPERSEDED = 4409;
 function isIdentityRevokedClose(code, reason) {
   return code === WS_CLOSE_IDENTITY_REVOKED || reason === "identity_revoked";
 }
@@ -25018,7 +25053,7 @@ function openDeliveryPings(o) {
         end();
       };
       if (!hardened) {
-        if (code === 4001 || isIdentityRevokedClose(code, reason)) {
+        if (code === 4001 || code === WS_CLOSE_SESSION_SUPERSEDED || isIdentityRevokedClose(code, reason)) {
           terminalClose();
           return;
         }
@@ -25027,7 +25062,7 @@ function openDeliveryPings(o) {
       }
       const tr = terminalReason;
       terminalReason = void 0;
-      if (code === 4006 || tr && code === 4001) {
+      if (code === 4006 || code === WS_CLOSE_SESSION_SUPERSEDED || tr && code === 4001) {
         lifecycle("terminal", tr ?? `code ${code}`);
         terminalClose();
         return;
@@ -25184,10 +25219,14 @@ var RestTransport = class {
   f;
   ws;
   tokenProvider;
-  /** The most recent device-wide WS send handle, captured on subscribe and
-   * cleared on its close. Control frames (status keepalive) route through it;
-   * a no-op when no subscription is active. */
+  /** The shared delivery-ping socket's send, set while that socket is open and
+   * cleared when it closes (last subscriber gone, or terminal). Control frames
+   * (status keepalive) route through it; a no-op when no subscription is active. */
   _controlSend = null;
+  /** P-5: the one delivery-ping stream this transport holds, shared by every subscriber. */
+  pingHub = null;
+  /** Set once the shared stream ends on a terminal close; no socket is ever reopened. */
+  pingsTerminal = false;
   constructor(opts) {
     this.opts = opts;
     this.f = opts.fetchImpl ?? fetch;
@@ -25289,25 +25328,52 @@ var RestTransport = class {
       idempotentReplay: j.idempotent_replay === true
     };
   }
+  /** One device-wide delivery-ping socket per transport (P-5): the backend
+   * supersedes a second socket for the same device, so every subscriber shares
+   * one `openDeliveryPings` handle. Each gets its own bounded queue; its close()
+   * detaches only itself; the socket closes with the last subscriber and a later
+   * subscribe opens a fresh one. After a terminal close the transport is
+   * terminal: later calls open no socket and get an already-ended iterator. */
   subscribeDeliveryPings(_channelId) {
+    if (this.pingsTerminal) {
+      const ended = new PingSubscriber();
+      ended.end();
+      return { pings: ended.pings, close: () => {
+      }, send: () => {
+      } };
+    }
+    const hub = this.pingHub ??= this.openPingHub();
+    const sub = hub.attach();
+    return { pings: sub.pings, close: () => hub.detach(sub), send: hub.send };
+  }
+  openPingHub() {
     let wsUrl = this.opts.baseUrl.replace(/^http/, "ws").replace(/\/$/, "") + "/api/v1/ws";
     if (this.opts.connectIdentityId) {
       wsUrl += `?connect_identity_id=${encodeURIComponent(this.opts.connectIdentityId)}`;
     }
-    const handle = openDeliveryPings({
+    const hub = new PingHub(openDeliveryPings({
       url: wsUrl,
       tokenProvider: this.tokenProvider,
       wsImpl: this.ws,
       hardened: this.opts.hardenedReconnect ?? false,
-      onLifecycle: this.opts.onWsLifecycle
-    });
-    this._controlSend = handle.send;
-    const close = () => {
-      if (this._controlSend === handle.send)
-        this._controlSend = null;
-      handle.close();
-    };
-    return { pings: handle.pings, close, send: handle.send };
+      onLifecycle: this.opts.onWsLifecycle,
+      // Any terminal close (4001, 4006, 4409, hardened war-cap) of the shared
+      // socket makes this transport terminal. The shared iterator ends right
+      // after this call, so the pump exit tears down every subscriber.
+      onTerminalClose: (close) => {
+        this.pingsTerminal = true;
+        this.opts.onTerminalClose?.(close);
+      }
+    }), () => this.dropPingHub(hub));
+    this._controlSend = hub.send;
+    return hub;
+  }
+  dropPingHub(hub) {
+    if (this.pingHub === hub) {
+      this.pingHub = null;
+      this._controlSend = null;
+    }
+    hub.shutdown();
   }
   sendControlFrame(_channelId, frame) {
     try {
@@ -25335,6 +25401,90 @@ var RestTransport = class {
     }));
   }
 };
+var SUBSCRIBER_QUEUE_MAX = 8;
+var PingSubscriber = class {
+  queue = [];
+  waiter;
+  ended = false;
+  started = false;
+  pings = {
+    [Symbol.asyncIterator]: () => {
+      if (this.started)
+        throw new Error("subscribeDeliveryPings: single-use async iterable");
+      this.started = true;
+      return {
+        next: () => {
+          if (this.ended)
+            return Promise.resolve({ value: void 0, done: true });
+          if (this.queue.length)
+            return Promise.resolve({ value: this.queue.shift(), done: false });
+          return new Promise((resolve4) => {
+            this.waiter = resolve4;
+          });
+        }
+      };
+    }
+  };
+  push(p) {
+    if (this.ended)
+      return;
+    if (this.waiter) {
+      const w = this.waiter;
+      this.waiter = void 0;
+      w({ value: p, done: false });
+    } else if (this.queue.length < SUBSCRIBER_QUEUE_MAX) {
+      this.queue.push(p);
+    }
+  }
+  end() {
+    this.ended = true;
+    this.queue.length = 0;
+    if (this.waiter) {
+      const w = this.waiter;
+      this.waiter = void 0;
+      w({ value: void 0, done: true });
+    }
+  }
+};
+var PingHub = class {
+  handle;
+  onGone;
+  subs = /* @__PURE__ */ new Set();
+  send;
+  constructor(handle, onGone) {
+    this.handle = handle;
+    this.onGone = onGone;
+    this.send = handle.send;
+    void this.pump();
+  }
+  /** `openDeliveryPings` iterables never reject and push() never throws, so
+   * this loop only ends when the shared stream ends (our close, or terminal). */
+  async pump() {
+    for await (const p of this.handle.pings)
+      for (const s of this.subs)
+        s.push(p);
+    this.onGone();
+  }
+  attach() {
+    const s = new PingSubscriber();
+    this.subs.add(s);
+    return s;
+  }
+  /** Idempotent: detaches and ends only `s`; the last one out closes the socket. */
+  detach(s) {
+    this.subs.delete(s);
+    s.end();
+    if (this.subs.size === 0)
+      this.onGone();
+  }
+  /** Idempotent: `openDeliveryPings().close()` is, and the set is empty after. */
+  shutdown() {
+    for (const s of this.subs)
+      s.end();
+    this.subs.clear();
+    this.handle.close();
+  }
+};
 
 // ../connect-sdk-ts/dist/mls/rest-backend.js
 function describeType(v) {
@@ -35208,6 +35358,7 @@ var ROOM_DEFAULT_READ_GRANTS = Object.freeze([
   Object.freeze({ tool: "current_time", mode: "read" })
 ]);
 var NO_TOOL_GRANTS = Object.freeze([]);
+var WS_CLOSE_SESSION_SUPERSEDED2 = 4409;
 var OWNER_REPLAY_PRUNE_INTERVAL_MS = 5 * 60 * 1e3;
 var OWNER_TURN_UNCHECKED = Object.freeze({ kind: "unchecked" });
 function ownerDmDefaultGrantsEnabled(env = process.env) {
@@ -35482,6 +35633,12 @@ function rosterFreshAt(entry, heldEpoch, heldGroupId) {
 var RoomGrantEpochMovedError = class extends Error {
 };
 var ROOM_GRANT_TRACK_MAX = 4096;
+var SessionSupersededError = class extends Error {
+  constructor() {
+    super("session_superseded: another copy of this agent took its session during start()");
+    this.name = "SessionSupersededError";
+  }
+};
 var GroupSupersededSendError = class extends Error {
   constructor(channelId, activeGroupId) {
     super(`send refused for channel ${channelId}: the channel moved to a new secure group; not sent`);
@@ -35521,9 +35678,18 @@ var BridgeAgent = class _BridgeAgent {
     const seed = hexToBytes4(cfg.signingPrivateKey);
     this.custody = SoftwareKeyCustody.fromPrivateKey("ed25519", seed);
     this.replyIdKey = deriveReplyIdKey(seed);
+    const base = deps.fetchImpl ?? fetch;
+    this.fetchImpl = (input, init) => this.sessionSuperseded ? Promise.reject(new Error("session_superseded")) : base(input, init);
     this.transport = deps.transport ?? new RestTransport({
       baseUrl: cfg.apiBase,
       bearerToken: cfg.apiKey,
+      fetchImpl: this.fetchImpl,
+      wsImpl: deps.wsImpl,
+      // A 4409 close means another copy of this agent took the session.
+      // Every other terminal close keeps today's behaviour.
+      onTerminalClose: (close) => {
+        if (close.code === WS_CLOSE_SESSION_SUPERSEDED2) this.onSessionSuperseded();
+      },
       connectIdentityId: cfg.identityId,
       // P1b: hardened delivery-ping reconnect (verify-before-terminal +
       // half-open + wake + auth war-cap). On by default for the daemon;
@@ -35537,7 +35703,7 @@ var BridgeAgent = class _BridgeAgent {
         else writeServiceLog("warn", "transport.delivery_ping_lifecycle_unknown");
       }
     });
-    this.backend = deps.backend ?? new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey });
+    this.backend = deps.backend ?? new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey, fetchImpl: this.fetchImpl });
     this.store = new SqliteMlsStateStore({
       dbPath: cfg.storePath,
       identityId: cfg.identityId,
@@ -35608,7 +35774,6 @@ var BridgeAgent = class _BridgeAgent {
       // throws (mirrors the divergence-heal signal path).
       onSupersedeUnopenable: (channelId, groupId) => this.healSupersedeUnopenable(channelId, groupId, this.drainExemptionAtCallIn())
     });
-    this.fetchImpl = deps.fetchImpl ?? fetch;
     this.home = deps.home ?? homedir4();
     this.grantWriters = {
       writeManifestPolicy: deps.grantWriters?.writeManifestPolicy ?? writeManifestPolicy,
@@ -35740,6 +35905,13 @@ var BridgeAgent = class _BridgeAgent {
   // stored for peek-then-join in ingestOnce
   custody;
   fetchImpl;
+  /** P-1: set once a 4409 close says another copy took this agent's session.
+   *  The gated fetch built in the constructor refuses every request after it. */
+  sessionSuperseded = false;
+  /** C9: who hears `session_superseded` (runMode's quiesce). */
+  sessionSupersededListeners = /* @__PURE__ */ new Set();
+  /** C9 (spec §4.1.6, low 3): the one close() run every caller shares. */
+  closing = null;
   /** Round 5: home for the managed runtime-config directory (test seam). */
   home;
   grantWriters;
@@ -36215,6 +36387,12 @@ var BridgeAgent = class _BridgeAgent {
   action;
   waiters = [];
   pingHandle;
+  /** C10 (P-15): the delivery-ping subscription start() opens at its top,
+   *  held unconsumed until startReceivePump() takes it. */
+  earlyPings = null;
+  /** C10 fix round 1: settles (never rejects) when start()'s body does; close()
+   *  awaits it, bounded, so the store never closes under a start() step. */
+  startInFlight = null;
   safetyTimer;
   /** The ingest cycle now running, if any (see ingestOnce: single-flight). */
   ingestInFlight = null;
@@ -36792,7 +36970,50 @@ var BridgeAgent = class _BridgeAgent {
       this.droppedMessages += overflow;
     }
   }
+  /**
+   * C10 (spec P-15, OQ-8 (b)): subscribe early, consume late. The
+   * delivery-ping socket opens here, before anything else, so this copy claims
+   * the device's session (and another copy gets its 4409) BEFORE this copy's
+   * boot drain runs. The pings it carries are NOT consumed until
+   * startReceivePump(), the same place as before: starting the pump first is
+   * still forbidden (DRAIN BEFORE ROTATE, startBody).
+   *
+   * A 4409 during start() (audit H-3): the gated fetch is already set (C9 step
+   * 0). start() then arms nothing more (supersededDuringStart before each
+   * timer and before the pump), runs the memoized close() quiesce, and rejects
+   * with SessionSupersededError. A step that FAILED because of the supersede
+   * (a refused fetch, a store the quiesce closed) is the same outcome.
+   */
   async start() {
+    const early = this.transport.subscribeDeliveryPings("");
+    this.earlyPings = early;
+    this.pingHandle = { close: early.close };
+    const body = this.startBody();
+    this.startInFlight = body.then(() => {
+    }, () => {
+    });
+    try {
+      await body;
+    } catch (e) {
+      if (!this.sessionSuperseded) {
+        if (this.earlyPings) {
+          this.earlyPings.close();
+          this.earlyPings = null;
+          this.pingHandle = void 0;
+        }
+        throw e;
+      }
+      if (!(e instanceof SessionSupersededError)) writeServiceLog("warn", "startup.superseded_start_error", {}, e);
+      await this.close().catch(() => {
+      });
+      throw new SessionSupersededError();
+    }
+  }
+  /** C10: true once a 4409 landed; checked before each arming step of start(). */
+  supersededDuringStart() {
+    return this.sessionSuperseded;
+  }
+  async startBody() {
     this.startedAt = Date.now();
     await this.restoreRuntimeInbox();
     await this.loadToolGrantState();
@@ -36852,10 +37073,12 @@ var BridgeAgent = class _BridgeAgent {
     await this.warmRestoredNotes();
     await this.reindexRestoredTurns();
     if (this.unifiedOn) await this.reindexUnifiedRestored();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.runtimeConfigTimer = setInterval(() => {
       void this.refetchRuntimeConfig();
     }, 6 * 60 * 60 * 1e3);
     this.runtimeConfigTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.membershipSweepTimer = setInterval(() => {
       if (this.closingDown || this.membershipSweepWork) return;
       this.membershipSweepWork = this.runMembershipSweeps().finally(() => {
@@ -36863,6 +37086,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, PURGE_SWEEP_INTERVAL_MS);
     this.membershipSweepTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.recallPruneTimer = setInterval(() => {
       if (this.closingDown || this.recallPruneWork) return;
       this.recallPruneWork = this.runRecallPruneTick().finally(() => {
@@ -36870,6 +37094,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, 60 * 60 * 1e3);
     this.recallPruneTimer.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     if (this.machinePaths) this.recallMaintenanceTimer = setInterval(() => {
       if (this.closingDown) return;
       const n = ++this.maintenanceTickN;
@@ -36880,6 +37105,7 @@ var BridgeAgent = class _BridgeAgent {
       });
     }, 1e3);
     this.recallMaintenanceTimer?.unref?.();
+    if (this.supersededDuringStart()) throw new SessionSupersededError();
     this.startReceivePump();
     if (drainedInTime) {
       this.armSelfHealSweeps();
@@ -41143,7 +41369,8 @@ var BridgeAgent = class _BridgeAgent {
     }
   }
   startReceivePump() {
-    const sub = this.transport.subscribeDeliveryPings("");
+    const sub = this.earlyPings ?? this.transport.subscribeDeliveryPings("");
+    this.earlyPings = null;
     this.pingHandle = { close: sub.close };
     void (async () => {
       try {
@@ -42728,7 +42955,42 @@ ${channelId}`;
       build: BRIDGE_VERSION
     };
   }
-  async close() {
+  /** C9: `session_superseded` once a 4409 said another copy took this
+   *  agent's session (the gated fetch already refuses every request). The
+   *  local HTTP routes read it: every route but `/healthz` answers 503. */
+  get sessionState() {
+    return this.sessionSuperseded ? "session_superseded" : "live";
+  }
+  /** C9: subscribe to `session_superseded`. runMode subscribes right after
+   *  construction, before start(), so a 4409 during start() is heard too. */
+  on(event, listener) {
+    this.sessionSupersededListeners.add(listener);
+    return () => this.sessionSupersededListeners.delete(listener);
+  }
+  /** P-1 step 0, then the event (spec §4.1.6): another copy of this agent took
+   *  the session (4409). The gated-fetch switch is set FIRST, so no HTTP
+   *  request leaves the process after this, whatever a listener does. */
+  onSessionSuperseded() {
+    this.sessionSuperseded = true;
+    for (const listener of [...this.sessionSupersededListeners]) {
+      try {
+        listener();
+      } catch (e) {
+        writeServiceLog("error", "transport.session_superseded_listener_failed", {}, e);
+      }
+    }
+  }
+  /**
+   * Idempotent (C9, spec §4.1.6 low 3): every call returns the FIRST call's
+   * promise, so a SIGTERM during or after the supersede quiesce never runs
+   * store.close() twice. A rejected close stays rejected: a retry would close
+   * the store a second time.
+   */
+  close() {
+    this.closing ??= this.closeOnce();
+    return this.closing;
+  }
+  async closeOnce() {
     this.closingDown = true;
     this.statusGate.close();
     for (const t of this.pauseRecheckTimers.values()) clearTimeout(t);
@@ -42741,6 +43003,28 @@ ${channelId}`;
     if (this.safetyTimer) clearInterval(this.safetyTimer);
     if (this.runtimeConfigTimer) clearInterval(this.runtimeConfigTimer);
     if (this.membershipSweepTimer) clearInterval(this.membershipSweepTimer);
+    const ingest = this.ingestInFlight;
+    if (ingest) {
+      let timer;
+      await Promise.race([
+        ingest.released,
+        new Promise((resolve4) => {
+          timer = setTimeout(resolve4, _BridgeAgent.GRACEFUL_DRAIN_MS);
+        })
+      ]);
+      if (timer) clearTimeout(timer);
+    }
+    const starting = this.startInFlight;
+    if (starting) {
+      let timer;
+      await Promise.race([
+        starting,
+        new Promise((resolve4) => {
+          timer = setTimeout(resolve4, _BridgeAgent.GRACEFUL_DRAIN_MS);
+        })
+      ]);
+      if (timer) clearTimeout(timer);
+    }
     if (this.membershipSweepWork) {
       let timer;
       await Promise.race([
@@ -42899,6 +43183,9 @@ var BRIDGE_ERRORS = {
   // longer holds the shared bytes or key. Terminal for that link: never fall
   // back to the current version. `detail.pin` names the refused pin.
   vault_ref_changed: { http: 422, message: "this file changed in Files after it was shared; not opened" },
+  // C9 (spec §4.1.6 step 1): another copy of this agent took its SecureComs
+  // session (WS 4409), so this copy stopped. Every local route but /healthz.
+  session_superseded: { http: 503, message: "another copy of this agent took its session; this copy stopped" },
   internal: { http: 500, message: "internal error" }
 };
 function errorBody(code, detail) {
@@ -43129,6 +43416,10 @@ function createHttpServer(agent, opts) {
       const url = new URL(req.url ?? "/", "http://localhost");
       const path = url.pathname;
       const method = req.method ?? "GET";
+      if (agent.sessionState === "session_superseded") {
+        if (method === "GET" && path === "/healthz") return json(res, 200, { state: "session_superseded" });
+        return jsonError(res, "session_superseded");
+      }
       if (method === "GET" && path === "/healthz") {
         return json(res, 200, { ...agent.health(), capabilities: capabilities(opts) });
       }
@@ -43340,6 +43631,7 @@ var PING_INTERVAL_MS = 3e4;
 var INFLIGHT_STALE_SWEEP_MS = 6e4;
 var INFLIGHT_STALE_AFTER_MS = 15 * 6e4;
 var HELLO_WAIT_MS = 2e3;
+var WS_CLOSE_SESSION_SUPERSEDED3 = 4409;
 var MEMORY_NOTES_FEATURE = "memory_notes";
 var MEMORY_RECALL_FEATURE = "memory_recall";
 var MEMORY_UNIFIED_FEATURE = "memory_unified";
@@ -43360,7 +43652,12 @@ function authedUpgrade(req, opts) {
   return true;
 }
 function attachAgentWebSocket(server, agent, opts) {
-  const wss = new WebSocketServer({ server, path: "/v1/ws" });
+  let sessionSuperseded = false;
+  const wss = new WebSocketServer({
+    server,
+    path: "/v1/ws",
+    verifyClient: (_info, done) => sessionSuperseded ? done(false, 503, "session_superseded") : done(true)
+  });
   const keepalive = setInterval(() => {
     for (const client of wss.clients) {
       const sock = client;
@@ -43500,6 +43797,7 @@ function attachAgentWebSocket(server, agent, opts) {
       if (helloTimer) clearTimeout(helloTimer);
       agent.noteSessionClose();
       unsubscribe();
+      if (sessionSuperseded) inflight.clear();
       if (inflight.size) {
         agent.requeueFailedRuntimeDeliveries(
           [...inflight.values()].filter((m) => !agent.isRuntimeMessageRetired(m.message_id))
@@ -43521,7 +43819,10 @@ function attachAgentWebSocket(server, agent, opts) {
     sock.on("close", cleanup);
     sock.on("error", cleanup);
     sock.on("message", (data) => {
-      void handleInbound(sock, agent, data, inflight, flush, session);
+      if (sessionSuperseded) return;
+      handleInbound(sock, agent, data, inflight, flush, session).catch((e) => {
+        writeServiceLog("error", "ws.inbound_failed", {}, e);
+      });
     });
     flush();
   });
@@ -43536,6 +43837,13 @@ function attachAgentWebSocket(server, agent, opts) {
         }
       }
       wss.close();
+    },
+    /** C9 (spec §4.1.6 step 1, OQ-9): close every open socket with 4409 /
+     *  `session_superseded`, and answer every later upgrade with 503. The
+     *  runtime's reconnect backoff does the rest; idempotent. */
+    enterSessionSuperseded() {
+      sessionSuperseded = true;
+      for (const client of wss.clients) client.close(WS_CLOSE_SESSION_SUPERSEDED3, "session_superseded");
     }
   };
 }
@@ -43837,11 +44145,12 @@ async function handleInbound(sock, agent, data, inflight, flush, session) {
 var LOWER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 // src/bin.ts
-import { readFileSync as readFileSync15, mkdirSync as mkdirSync7, writeFileSync as writeFileSync5, rmSync as rmSync8, existsSync as existsSync7, realpathSync as realpathSync3, readdirSync as readdirSync4, statSync as statSync7 } from "node:fs";
-import { join as join25, dirname as dirname12, isAbsolute as isAbsolute3, resolve as resolve3 } from "node:path";
+import { readFileSync as readFileSync16, mkdirSync as mkdirSync8, writeFileSync as writeFileSync5, rmSync as rmSync8, existsSync as existsSync7, realpathSync as realpathSync3, readdirSync as readdirSync4, statSync as statSync8, chmodSync as chmodSync6 } from "node:fs";
+import { join as join25, dirname as dirname13, isAbsolute as isAbsolute3, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { homedir as homedir5, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
+import { createServer as netCreateServer } from "node:net";
 
 // src/service/install.ts
 import { dirname as dirname8 } from "node:path";
@@ -43922,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));
@@ -43962,7 +44271,10 @@ ${programArgs}
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <true/>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
   <key>StandardOutPath</key>
   <string>${escapeXml(cfg.logPath)}</string>
   <key>StandardErrorPath</key>
@@ -43989,7 +44301,7 @@ Wants=network-online.target
 [Service]
 Type=simple
 ExecStart=${execStart}
-Restart=always
+Restart=on-failure
 RestartSec=5
 
 [Install]
@@ -44000,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`;
 }
@@ -44012,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");
@@ -44462,6 +44797,10 @@ ${customFacts(input)}`, wired: false, error: false };
 }
 
 // src/service/install-prep.ts
+function isDaemonRouted(h) {
+  return h != null && h.state !== "session_superseded";
+}
+var VERIFY_BUDGET_MS = BOOT_DRAIN_WAIT_MS_DEFAULT + 15e3;
 function assertReadableCredential(absPath, deps) {
   let raw;
   try {
@@ -44489,6 +44828,44 @@ function durableDir(home, slug) {
 function durableCredentialPath(home, slug) {
   return join21(durableDir(home, slug), `${slug}.json`);
 }
+var DURABLE_PREFIX = "securecoms-agent-";
+var InstallRefusedError = class extends Error {
+};
+function existingIdentityError(dir, label) {
+  return new InstallRefusedError(
+    `This agent is already installed in ${dir} with a different key. Uninstall it first: agent-bridge uninstall --label ${label}`
+  );
+}
+function refuseExistingIdentity(args2, deps) {
+  const destName = `${DURABLE_PREFIX}${args2.slug}`;
+  let names;
+  try {
+    names = deps.listDir(args2.home);
+  } catch {
+    names = [];
+  }
+  const others = names.filter((n) => n.startsWith(DURABLE_PREFIX) && n !== destName).sort();
+  for (const name of [destName, ...others]) {
+    const slug = name.slice(DURABLE_PREFIX.length);
+    const dir = join21(args2.home, name);
+    const credPath = join21(dir, `${slug}.json`);
+    if (!deps.fileExists(credPath)) continue;
+    let existing = null;
+    try {
+      const j = JSON.parse(deps.readFile(credPath));
+      if (j && typeof j === "object") existing = j;
+    } catch {
+    }
+    if (!existing || typeof existing.identity_id !== "string" || !existing.identity_id) {
+      if (deps.fileExists(join21(dir, "bridge-state.db"))) throw existingIdentityError(dir, slug);
+      continue;
+    }
+    if (existing.identity_id !== args2.parsed.identityId) continue;
+    if (name !== destName || existing.device_id !== args2.parsed.deviceId) {
+      throw existingIdentityError(dir, slug);
+    }
+  }
+}
 function takeCustody(args2, deps) {
   const dir = durableDir(args2.home, args2.slug);
   const dest = durableCredentialPath(args2.home, args2.slug);
@@ -44496,10 +44873,11 @@ function takeCustody(args2, deps) {
     if (deps.fileExists(dest) && deps.realpath(args2.sourceAbsPath) === deps.realpath(dest)) return dest;
   } catch {
   }
+  refuseExistingIdentity(args2, deps);
   if (deps.fileExists(dest)) {
     try {
       const existing = JSON.parse(deps.readFile(dest));
-      if (existing.device_id && existing.device_id !== args2.parsed.deviceId) {
+      if (existing.identity_id && existing.identity_id !== args2.parsed.identityId) {
         throw new Error(
           `install: ${dir} already belongs to a different agent (device ${existing.device_id}). Pass a distinct --label to install this agent in its own directory.`
         );
@@ -44554,21 +44932,19 @@ function selectPort(args2, deps) {
   throw new Error(`install: no free port in ${PORT_MIN}-${PORT_MAX} \u2014 stop an unused bridge or pass --port`);
 }
 async function verifyDaemonUp(args2, deps) {
-  const attempts = args2.attempts ?? 20;
   const delayMs = args2.delayMs ?? 250;
-  for (let i = 0; i < attempts; i++) {
-    if (deps.probeConnect(args2.port)) return true;
-    try {
-      if (deps.readFile(args2.logPath).includes("[bridge] listening on")) return true;
-    } catch {
-    }
+  const deadline = deps.now() + VERIFY_BUDGET_MS;
+  const maxAttempts = args2.attempts ?? Number.POSITIVE_INFINITY;
+  for (let i = 0; i < maxAttempts; i++) {
+    if (isDaemonRouted(deps.getHealth(args2.port))) return true;
+    if (deps.now() >= deadline) return false;
     await deps.sleep(delayMs);
   }
   return false;
 }
 async function orchestrateInstall(ctx) {
   const parsed = assertReadableCredential(ctx.credentialAbsPath, ctx.prepDeps);
-  const stemForSlug = ctx.label ?? ctx.credentialAbsPath.replace(/^.*[\\/]/, "").replace(/\.[^.]*$/, "");
+  const stemForSlug = ctx.label ?? ctx.credentialAbsPath.replace(/^.*[\\/]/, "").replace(/\.[^.]*$/, "").replace(/ \(\d+\)$/, "");
   const slug = slugify(stemForSlug);
   const durablePath = takeCustody(
     { home: ctx.home, slug, sourceAbsPath: ctx.credentialAbsPath, parsed },
@@ -44692,13 +45068,13 @@ function readFleet(deps) {
 // src/service/status.ts
 function readFleetStatus(deps) {
   return deps.readFleet().map((e) => {
-    const up = e.port != null && deps.probeConnect(e.port);
+    const h = e.port != null ? deps.getHealth(e.port) : null;
+    const up = isDaemonRouted(h);
     let harness = "-";
     let evictions = 0;
-    if (up && e.port != null) {
-      const h = deps.getHealth(e.port);
-      harness = (h?.agent_sessions ?? 0) >= 1 ? "attached" : "no brain";
-      evictions = h?.evictions ?? 0;
+    if (up) {
+      harness = (h.agent_sessions ?? 0) >= 1 ? "attached" : "no brain";
+      evictions = h.evictions ?? 0;
     }
     return {
       slug: e.slug,
@@ -44790,20 +45166,339 @@ function removeConnectionFileIfOwned(home, identityId, instanceId, deps = REAL_F
   }
 }
 
+// src/service/instance-lock.ts
+import { execFileSync } from "node:child_process";
+import { closeSync as closeSync4, fsyncSync, mkdirSync as mkdirSync7, openSync as openSync4, readFileSync as readFileSync13, statSync as statSync6, unlinkSync as unlinkSync3, utimesSync, writeSync as writeSync2 } from "node:fs";
+import { hostname, uptime as uptime2 } from "node:os";
+import { dirname as dirname11 } from "node:path";
+var LOCK_PARTIAL_WRITE_GRACE_MS = 1e4;
+var LOCK_TAKEOVER_GUARD_STALE_MS = 3e4;
+var BOOT_TOLERANCE_SEC = 120;
+var LOCK_HEARTBEAT_MS = 6e4;
+var LOCK_FOREIGN_STALE_MS = 10 * LOCK_HEARTBEAT_MS;
+function errno(error) {
+  const code = error?.code;
+  return typeof code === "string" ? code : void 0;
+}
+function readTrimmed(path) {
+  try {
+    const v = readFileSync13(path, "utf8").trim();
+    return v === "" ? void 0 : v;
+  } catch {
+    return void 0;
+  }
+}
+function procStartFromStat(stat) {
+  const close = stat.lastIndexOf(")");
+  if (close < 0) return void 0;
+  const rest = stat.slice(close + 1).trim().split(/\s+/);
+  const v = rest[19];
+  return v !== void 0 && /^\d+$/.test(v) ? v : void 0;
+}
+function pidAliveByKill(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errno(error) === "EPERM";
+  }
+}
+var bootIdCache;
+function readBootId() {
+  if (bootIdCache) return bootIdCache.v;
+  let v = readTrimmed("/proc/sys/kernel/random/boot_id");
+  if (v === void 0 && process.platform === "darwin") {
+    try {
+      const out = execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], {
+        encoding: "utf8",
+        timeout: 2e3,
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+      v = /^[0-9A-Fa-f-]{16,64}$/.test(out) ? out : void 0;
+    } catch {
+      v = void 0;
+    }
+  }
+  bootIdCache = { v };
+  return v;
+}
+var realLockEnv = {
+  pid: process.pid,
+  hostname: () => hostname(),
+  bootId: readBootId,
+  bootEpochSec: () => Math.round(Date.now() / 1e3 - uptime2()),
+  procStart: (pid) => {
+    const stat = readTrimmed(`/proc/${pid}/stat`);
+    return stat ? procStartFromStat(stat) : void 0;
+  },
+  pidAlive: pidAliveByKill
+};
+function parseBody(raw) {
+  try {
+    const b = JSON.parse(raw);
+    if (b && b.v === 2 && Number.isInteger(b.pid) && b.pid > 0 && typeof b.host === "string" && Number.isFinite(b.boot)) {
+      return b;
+    }
+  } catch {
+  }
+  return void 0;
+}
+var InstanceLock = class {
+  constructor(path, env = realLockEnv, log = () => {
+  }, heartbeatMs = LOCK_HEARTBEAT_MS) {
+    this.path = path;
+    this.env = env;
+    this.log = log;
+    this.heartbeatMs = heartbeatMs;
+  }
+  held = false;
+  /** 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). */
+  written;
+  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;
+  /** PID read from the lock body of the live holder behind the last `held`. */
+  holderPid;
+  body() {
+    const bootId = this.env.bootId();
+    const start = this.env.procStart(this.env.pid);
+    const b = {
+      v: 2,
+      pid: this.env.pid,
+      host: this.env.hostname(),
+      ...bootId !== void 0 ? { boot_id: bootId } : {},
+      boot: this.env.bootEpochSec(),
+      ...start !== void 0 ? { start } : {}
+    };
+    return JSON.stringify(b);
+  }
+  /** Try to hold the lock. Never throws (#808 L-e: machine reads included). */
+  acquire() {
+    this.holderPid = void 0;
+    let result;
+    try {
+      result = this.acquireUnguarded();
+    } catch (error) {
+      this.lastError = error;
+      result = "failed";
+    }
+    return result === "held" && this.holderPid !== void 0 ? { result, holderPid: this.holderPid } : { result };
+  }
+  /**
+   * 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() {
+    if (!this.held) return false;
+    let current;
+    try {
+      current = readFileSync13(this.path, "utf8");
+    } catch {
+      current = void 0;
+    }
+    if (current !== void 0 && current === this.written) return true;
+    this.drop();
+    this.log("warn", "bridge.instance_lock_lost", {});
+    return false;
+  }
+  acquireUnguarded() {
+    if (this.held) return "acquired";
+    const created = this.create();
+    if (created === "created") return this.took();
+    if (created === "failed") return "failed";
+    let raw;
+    let ageMs;
+    this.env.beforeLockRead?.();
+    try {
+      raw = readFileSync13(this.path, "utf8");
+      ageMs = Date.now() - statSync6(this.path).mtimeMs;
+    } catch (error) {
+      if (errno(error) === "ENOENT") {
+        const again = this.create();
+        return again === "created" ? this.took() : again === "failed" ? "failed" : "busy";
+      }
+      this.lastError = error;
+      return "unreadable";
+    }
+    const b = parseBody(raw);
+    if (!b) {
+      if (ageMs < LOCK_PARTIAL_WRITE_GRACE_MS) return "busy";
+      return this.takeOver(raw, void 0);
+    }
+    if (b.host !== this.env.hostname()) {
+      const bootId = this.env.bootId();
+      const sameKernel = b.boot_id !== void 0 && bootId !== void 0 && b.boot_id === bootId;
+      if (sameKernel && ageMs > LOCK_FOREIGN_STALE_MS) return this.takeOver(raw, b.pid);
+      return "foreign_host";
+    }
+    if (!this.sameBoot(b)) return this.takeOver(raw, b.pid);
+    const liveStart = this.env.procStart(b.pid);
+    const reused = b.start !== void 0 && liveStart !== void 0 && liveStart !== b.start;
+    if (b.pid === this.env.pid) {
+      if (!reused) return this.took();
+      return this.takeOver(raw, b.pid);
+    }
+    if (this.env.pidAlive(b.pid) && !reused) {
+      this.holderPid = b.pid;
+      return "held";
+    }
+    return this.takeOver(raw, b.pid);
+  }
+  /** 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() {
+    if (!this.held) return;
+    const written = this.written;
+    this.drop();
+    try {
+      if (written !== void 0 && readFileSync13(this.path, "utf8") === written) unlinkSync3(this.path);
+    } catch {
+    }
+  }
+  drop() {
+    this.held = false;
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    this.heartbeat = void 0;
+  }
+  /** We hold it: remember what we wrote (the file as it is now, ours) and
+   *  start the heartbeat. */
+  took() {
+    this.held = true;
+    try {
+      this.written = readFileSync13(this.path, "utf8");
+    } catch {
+      this.written = void 0;
+    }
+    if (!this.heartbeat && this.heartbeatMs > 0) {
+      this.heartbeat = setInterval(() => this.beat(), this.heartbeatMs);
+      this.heartbeat.unref?.();
+    }
+    return "acquired";
+  }
+  /** Refresh the mtime while the file is still ours; stop if it is not. */
+  beat() {
+    if (!this.stillHeld()) return;
+    try {
+      const now = /* @__PURE__ */ new Date();
+      utimesSync(this.path, now, now);
+    } catch {
+    }
+  }
+  sameBoot(b) {
+    const bootId = this.env.bootId();
+    if (b.boot_id !== void 0 && bootId !== void 0) return b.boot_id === bootId;
+    return Math.abs(b.boot - this.env.bootEpochSec()) <= BOOT_TOLERANCE_SEC;
+  }
+  /** 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. */
+  create() {
+    let fd;
+    try {
+      mkdirSync7(dirname11(this.path), { recursive: true, mode: 448 });
+      fd = openSync4(this.path, "wx", 384);
+    } catch (error) {
+      if (errno(error) === "EEXIST") return "exists";
+      this.lastError = error;
+      return "failed";
+    }
+    try {
+      writeSync2(fd, this.body());
+      fsyncSync(fd);
+    } catch (error) {
+      try {
+        closeSync4(fd);
+      } catch {
+      }
+      try {
+        unlinkSync3(this.path);
+      } catch {
+      }
+      this.lastError = error;
+      return "failed";
+    }
+    closeSync4(fd);
+    return "created";
+  }
+  /**
+   * 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.
+   */
+  takeOver(staleRaw, stalePid, retryGuard = true) {
+    const guard = `${this.path}.takeover`;
+    let fd;
+    try {
+      fd = openSync4(guard, "wx", 384);
+    } catch (error) {
+      if (errno(error) !== "EEXIST") return "failed";
+      let crashed = false;
+      try {
+        crashed = Date.now() - statSync6(guard).mtimeMs > LOCK_TAKEOVER_GUARD_STALE_MS;
+        if (crashed) unlinkSync3(guard);
+      } catch {
+        crashed = false;
+      }
+      if (crashed && retryGuard) return this.takeOver(staleRaw, stalePid, false);
+      return "busy";
+    }
+    closeSync4(fd);
+    try {
+      this.env.beforeTakeoverReread?.();
+      let current;
+      try {
+        current = readFileSync13(this.path, "utf8");
+      } catch {
+        current = void 0;
+      }
+      if (current !== void 0 && current !== staleRaw) {
+        this.holderPid = parseBody(current)?.pid;
+        return "held";
+      }
+      if (current !== void 0) unlinkSync3(this.path);
+      this.env.beforeTakeoverCreate?.();
+      const created = this.create();
+      if (created !== "created") {
+        if (created === "failed") return "failed";
+        try {
+          this.holderPid = parseBody(readFileSync13(this.path, "utf8"))?.pid;
+        } catch {
+        }
+        return "held";
+      }
+      this.log("warn", "bridge.instance_lock_stale_taken_over", stalePid !== void 0 ? { stale_pid: stalePid } : {});
+      return this.took();
+    } catch (error) {
+      this.lastError = error;
+      return "failed";
+    } finally {
+      try {
+        unlinkSync3(guard);
+      } catch {
+      }
+    }
+  }
+};
+
 // src/grants/pin-command.ts
 import {
-  closeSync as closeSync4,
+  closeSync as closeSync5,
   fchmodSync,
-  fsyncSync,
+  fsyncSync as fsyncSync2,
   lstatSync as lstatSync8,
-  openSync as openSync4,
-  readFileSync as readFileSync13,
+  openSync as openSync5,
+  readFileSync as readFileSync14,
   realpathSync as realpathSync2,
   renameSync as renameSync5,
-  unlinkSync as unlinkSync3,
-  writeSync as writeSync2
+  unlinkSync as unlinkSync4,
+  writeSync as writeSync3
 } from "node:fs";
-import { dirname as dirname11, join as join23, resolve as resolve2 } from "node:path";
+import { dirname as dirname12, join as join23, resolve as resolve2 } from "node:path";
 var PIN_COPY = Object.freeze({
   saved: "pin saved. Restart the Connector to use it.",
   // [COPY, approved by Eric 2026-10-12]
@@ -44834,27 +45529,27 @@ function isSymlink(path) {
   }
 }
 function readJson(path) {
-  return JSON.parse(readFileSync13(path, "utf8"));
+  return JSON.parse(readFileSync14(path, "utf8"));
 }
 function publicKeyOf(v) {
   const r = parsePinObject(v);
   return r.ok ? r.pin.publicKeyB64 : null;
 }
 function writeTemp(path, bytes) {
-  const fd = openSync4(path, "wx", 384);
+  const fd = openSync5(path, "wx", 384);
   try {
     fchmodSync(fd, 384);
-    writeSync2(fd, bytes);
-    fsyncSync(fd);
+    writeSync3(fd, bytes);
+    fsyncSync2(fd);
   } finally {
-    closeSync4(fd);
+    closeSync5(fd);
   }
 }
 function runPinCommand(opts) {
-  const credDir = dirname11(resolve2(opts.credentialPath));
+  const credDir = dirname12(resolve2(opts.credentialPath));
   const target = join23(credDir, PIN_FILE_NAME);
   try {
-    if (realpathSync2(dirname11(resolve2(opts.pinSourcePath))) !== realpathSync2(credDir)) return refuse("directory_mismatch");
+    if (realpathSync2(dirname12(resolve2(opts.pinSourcePath))) !== realpathSync2(credDir)) return refuse("directory_mismatch");
   } catch {
     return refuse("io_error");
   }
@@ -44901,7 +45596,7 @@ function runPinCommand(opts) {
   const fail = () => {
     for (const p of created) {
       try {
-        unlinkSync3(p);
+        unlinkSync4(p);
       } catch {
       }
     }
@@ -44937,11 +45632,11 @@ function runPinCommand(opts) {
   created.splice(created.indexOf(credTmp), 1);
   step("cred_renamed");
   try {
-    const dfd = openSync4(credDir, "r");
+    const dfd = openSync5(credDir, "r");
     try {
-      fsyncSync(dfd);
+      fsyncSync2(dfd);
     } finally {
-      closeSync4(dfd);
+      closeSync5(dfd);
     }
   } catch {
   }
@@ -44979,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;
@@ -44997,7 +45706,7 @@ function parseVerb(argv) {
   return v === "install" || v === "uninstall" || v === "status" || v === "wire" || v === "unwire" || v === "models" || v === "pin" ? v : null;
 }
 function slugFromCredentialPath(credentialPath) {
-  const dir = dirname12(credentialPath);
+  const dir = dirname13(credentialPath);
   const base = dir.split(/[\\/]/).pop() ?? "";
   const m = base.match(/^securecoms-agent-(.+)$/);
   if (m) return m[1];
@@ -45013,17 +45722,24 @@ function realServiceDeps() {
     },
     writeFile: (p, data) => writeFileSync5(p, data, { mode: 420 }),
     removeFile: (p) => rmSync8(p, { force: true }),
-    mkdirp: (p) => mkdirSync7(p, { recursive: 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;
@@ -45057,10 +45773,10 @@ function realResolveDeps() {
 }
 function realPrepDeps() {
   return {
-    readFile: (p) => readFileSync15(p, "utf8"),
+    readFile: (p) => readFileSync16(p, "utf8"),
     writeFileMode: (p, data, mode) => writeFileSync5(p, data, { mode }),
     mkdirp: (p, mode) => {
-      mkdirSync7(p, { recursive: true, mode: mode ?? 493 });
+      mkdirSync8(p, { recursive: true, mode: mode ?? 493 });
     },
     fileExists: (p) => existsSync7(p),
     realpath: (p) => realpathSync3(p),
@@ -45080,25 +45796,22 @@ function realPrepDeps() {
       ]);
       return r.status === 0;
     },
-    probeConnect: (port) => {
-      const r = spawnSync(process.execPath, [
-        "-e",
-        `const s=require('net').connect(${port},'127.0.0.1');s.once('connect',()=>{s.destroy();process.exit(0)});s.once('error',()=>process.exit(1));setTimeout(()=>process.exit(1),500);`
-      ]);
-      return r.status === 0;
-    },
+    getHealth: realGetHealth,
     // No unref: an unref'd timer would let the process exit mid-verification.
-    sleep: (ms) => new Promise((res) => setTimeout(res, ms))
+    sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+    now: () => Date.now()
   };
 }
 function realGetHealth(port) {
   const r = spawnSync(process.execPath, [
     "-e",
-    `const http=require('http');const q=http.get({host:'127.0.0.1',port:${port},path:'/healthz',timeout:800},res=>{let d='';res.on('data',c=>d+=c);res.on('end',()=>{process.stdout.write(d);process.exit(0)})});q.on('error',()=>process.exit(1));q.on('timeout',()=>process.exit(1));`
-  ], { encoding: "utf8" });
+    `const http=require('http');const q=http.get({host:'127.0.0.1',port:${port},path:'/healthz',timeout:800},res=>{let d='';res.on('data',c=>d+=c);res.on('end',()=>{process.stdout.write(res.statusCode+'\\n'+d);process.exit(0)})});q.on('error',()=>process.exit(1));q.on('timeout',()=>process.exit(1));`
+  ], { encoding: "utf8", timeout: 2e3 });
   if (r.status !== 0) return null;
+  const nl = r.stdout.indexOf("\n");
+  if (nl < 0 || r.stdout.slice(0, nl) !== "200") return null;
   try {
-    return JSON.parse(r.stdout);
+    return JSON.parse(r.stdout.slice(nl + 1));
   } catch {
     return null;
   }
@@ -45113,19 +45826,12 @@ function realReadFleet() {
         return [];
       }
     },
-    readFile: (p) => readFileSync15(p, "utf8")
+    readFile: (p) => readFileSync16(p, "utf8")
   });
 }
 function runStatus() {
   const deps = {
     readFleet: realReadFleet,
-    probeConnect: (port) => {
-      const r = spawnSync(process.execPath, [
-        "-e",
-        `const s=require('net').connect(${port},'127.0.0.1');s.once('connect',()=>{s.destroy();process.exit(0)});s.once('error',()=>process.exit(1));setTimeout(()=>process.exit(1),500);`
-      ]);
-      return r.status === 0;
-    },
     getHealth: realGetHealth
   };
   const rows = readFleetStatus(deps);
@@ -45135,26 +45841,26 @@ function runStatus() {
 }
 function realCopyConnector(srcDir, dstDir, harness) {
   const allowedExt = CONNECTOR_FILE_EXTENSIONS[harness];
-  mkdirSync7(dstDir, { recursive: true });
+  mkdirSync8(dstDir, { recursive: true });
   for (const name of readdirSync4(srcDir)) {
     const srcPath = join25(srcDir, name);
-    if (statSync7(srcPath).isDirectory()) {
+    if (statSync8(srcPath).isDirectory()) {
       if (CONNECTOR_SKIP_DIRS.has(name)) continue;
       realCopyConnector(srcPath, join25(dstDir, name), harness);
       continue;
     }
     if (name.includes(".test.")) continue;
     if (!allowedExt.some((ext) => name.endsWith(ext))) continue;
-    writeFileSync5(join25(dstDir, name), readFileSync15(srcPath));
+    writeFileSync5(join25(dstDir, name), readFileSync16(srcPath));
   }
 }
 function realWriteBinding(dstDir, identityId) {
-  mkdirSync7(dstDir, { recursive: true });
+  mkdirSync8(dstDir, { recursive: true });
   writeFileSync5(join25(dstDir, "securecoms.binding.json"), JSON.stringify({ identity_id: identityId }) + "\n", { mode: 384 });
 }
 function realReadBinding(dstDir) {
   try {
-    const parsed = JSON.parse(readFileSync15(join25(dstDir, "securecoms.binding.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync16(join25(dstDir, "securecoms.binding.json"), "utf8"));
     return parsed.identity_id ?? null;
   } catch {
     return null;
@@ -45165,14 +45871,14 @@ function realRemoveBinding(dstDir) {
 }
 function realStatDir(p) {
   try {
-    return statSync7(p).isDirectory();
+    return statSync8(p).isDirectory();
   } catch {
     return false;
   }
 }
 function realReadHermesConfig(p) {
   try {
-    return readFileSync15(p, "utf8");
+    return readFileSync16(p, "utf8");
   } catch {
     return null;
   }
@@ -45213,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}
 `);
@@ -45293,12 +46007,15 @@ async function runServiceVerb(verb) {
     }
     process.exit(0);
   } catch (e) {
-    const raw = e instanceof ServiceUnsupportedError || e instanceof GlobalInstallPermissionError;
-    process.stderr.write(`${raw ? e.message : `service ${verb} failed: ${e.message ?? e}`}
-`);
+    process.stderr.write(formatServiceError(verb, e));
     process.exit(1);
   }
 }
+function formatServiceError(verb, e) {
+  const raw = e instanceof ServiceUnsupportedError || e instanceof GlobalInstallPermissionError || e instanceof InstallRefusedError;
+  return `${raw ? e.message : `service ${verb} failed: ${e.message ?? e}`}
+`;
+}
 async function startThenServe(agent, opts) {
   await agent.start();
   const tls = opts.readTls();
@@ -45330,55 +46047,237 @@ async function runModelsVerb() {
 function runPinVerb() {
   process.exit(runPinCli(process.argv, { out: (l) => process.stdout.write(l + "\n"), err: (l) => process.stderr.write(l + "\n") }));
 }
-async function main() {
-  if (!nodeMajorOk(process.versions.node)) {
-    writeServiceLog("error", "startup.node_unsupported");
-    process.exit(1);
-  }
-  const verb = parseVerb(process.argv);
-  if (verb === "pin") {
-    runPinVerb();
-    return;
-  }
-  if (verb === "status") {
-    runStatus();
-    return;
-  }
-  if (verb === "wire" || verb === "unwire") {
-    runWireVerb(verb);
-    return;
-  }
-  if (verb === "models") {
-    await runModelsVerb();
-    return;
-  }
-  if (verb) {
-    await runServiceVerb(verb);
-    return;
-  }
-  const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
-  if (!credentialPath) {
-    writeServiceLog("error", "startup.credential_required.use_--credential");
-    process.exit(2);
+var CANONICAL_UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+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;
   }
-  const storePath = argOrEnv("--store", "SECURECOMS_STORE");
+}
+function realRunModeDeps(credentialPath, storePath) {
+  return {
+    credentialPath,
+    storePath,
+    argv: process.argv,
+    env: process.env,
+    home: homedir5(),
+    newLock: (path) => new InstanceLock(path, void 0, writeServiceLog),
+    // 7b Task 19 fix M2: the production construction owns the machine paths (heartbeat, model marker and GC).
+    newAgent: (cfg) => new BridgeAgent(cfg, { hostMachine: true }),
+    net: { createServer: netCreateServer },
+    serve: startThenServe,
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    setHardExitTimer: (cb, ms) => {
+      const t = setTimeout(cb, ms);
+      t.unref?.();
+      return () => clearTimeout(t);
+    },
+    onSignal: (signal, handler) => {
+      process.on(signal, handler);
+    },
+    onExit: (handler) => {
+      process.once("exit", handler);
+    },
+    exit: (code) => process.exit(code),
+    print: (line) => {
+      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(process.argv, process.env);
+    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) {
-    writeServiceLog("error", "startup.config_invalid", {}, e);
-    process.exit(1);
+    refuse2("bind_refused", {}, e);
+    return deps.exit(1);
+  }
+  if (!CANONICAL_UUID2.test(cfg.identityId)) {
+    refuse2("identity_id_invalid", { field: "identity_id" });
+    return deps.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join25(dirname12(credentialPath), "bridge-token");
+  const lockDir = join25(deps.home, ".securecoms", "locks");
+  const lockPath = join25(lockDir, `${cfg.identityId.toLowerCase()}.lock`);
+  try {
+    mkdirSync8(lockDir, { recursive: true, mode: 448 });
+    chmodSync6(lockDir, 448);
+  } catch (e) {
+    log("error", "startup.instance_lock_failed", {}, e);
+    return deps.exit(1);
+  }
+  const lock = deps.newLock(lockPath);
+  let got = lock.acquire();
+  const pollStart = deps.now();
+  while (got.result === "held" && deps.now() - pollStart < HELD_POLL_TOTAL_MS) {
+    await deps.sleep(HELD_POLL_INTERVAL_MS);
+    got = lock.acquire();
+  }
+  for (let i = 0; i < HELD_NO_PID_REACQUIRES && got.result === "held" && got.holderPid === void 0; i++) {
+    await deps.sleep(HELD_POLL_INTERVAL_MS);
+    got = lock.acquire();
+  }
+  switch (got.result) {
+    case "acquired":
+      break;
+    case "held":
+      if (got.holderPid === void 0) {
+        log("error", "startup.instance_lock_busy");
+        return deps.exit(1);
+      }
+      log("info", "startup.already_running");
+      deps.print(`This agent is already running on this computer (process ${got.holderPid}). Stop that copy first, or run: agent-bridge status`);
+      return deps.exit(0);
+    case "foreign_host":
+      log("error", "startup.instance_lock_foreign_host", {
+        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(
+        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);
+      return deps.exit(1);
+    case "busy":
+      log("error", "startup.instance_lock_busy");
+      return deps.exit(1);
+    case "failed":
+      log("error", "startup.instance_lock_failed", {}, lock.lastError);
+      return deps.exit(1);
+  }
+  deps.onExit(() => lock.release());
+  const tokenFile = daemon.tokenFile ?? join25(dirname13(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
-  const agent = new BridgeAgent(cfg, { hostMachine: true });
-  const { server, closeAllSseStreams, agentWs } = await startThenServe(agent, {
-    token,
-    allowOrigins: daemon.allowOrigins,
-    readTls: () => daemon.tls ? { cert: readFileSync15(daemon.tlsCert, "utf8"), key: readFileSync15(daemon.tlsKey, "utf8") } : void 0
+  const preBound = deps.net.createServer((sock) => sock.destroy());
+  const bindError = await new Promise((resolveBind) => {
+    const onError = (e) => resolveBind(e);
+    preBound.once("error", onError);
+    preBound.listen(daemon.port, daemon.bind, () => {
+      preBound.removeListener("error", onError);
+      resolveBind(void 0);
+    });
+  });
+  if (bindError) {
+    if (bindError.code === "EADDRINUSE") {
+      log("error", "startup.port_in_use", { port: daemon.port });
+      deps.print(`Port ${daemon.port} is already in use by another program on this computer, so the agent did not start.`);
+    } else {
+      log("error", "startup.listen_failed", {}, bindError);
+    }
+    lock.release();
+    return deps.exit(1);
+  }
+  const agent = deps.newAgent(cfg);
+  const instanceId = newInstanceId();
+  const identityId = cfg.identityId;
+  let served = null;
+  let superseded = false;
+  const stopIngress = (s) => {
+    s.agentWs.enterSessionSuperseded();
+    s.closeAllSseStreams();
+  };
+  agent.on("session_superseded", () => {
+    if (superseded) return;
+    superseded = true;
+    if (served) stopIngress(served);
+    log("warn", "transport.session_superseded");
+    deps.print("This agent connected from another place, so this copy stopped. Stop the other copy, then restart this one.");
+    void (async () => {
+      try {
+        await agent.close();
+      } catch (e) {
+        log("error", "transport.session_superseded_close_failed", {}, e);
+      }
+      removeConnectionFileIfOwned(deps.home, identityId, instanceId);
+    })();
   });
+  let exiting = false;
+  const closeReleaseExit = () => {
+    if (exiting) return;
+    exiting = true;
+    const cancelHard = deps.setHardExitTimer(() => {
+      lock.release();
+      deps.exit(0);
+    }, SHUTDOWN_HARD_EXIT_MS);
+    void agent.close().finally(() => {
+      cancelHard();
+      lock.release();
+      deps.exit(0);
+    });
+  };
+  try {
+    served = await deps.serve(agent, {
+      token,
+      allowOrigins: daemon.allowOrigins,
+      readTls: () => daemon.tls ? { cert: readFileSync16(daemon.tlsCert, "utf8"), key: readFileSync16(daemon.tlsKey, "utf8") } : void 0
+    });
+  } catch (e) {
+    if (!(e instanceof SessionSupersededError)) throw e;
+    deps.onSignal("SIGINT", closeReleaseExit);
+    deps.onSignal("SIGTERM", closeReleaseExit);
+    return;
+  }
+  if (superseded) stopIngress(served);
+  const { server, closeAllSseStreams, agentWs } = served;
   let down = false;
   const shutdown = () => {
     if (down) return;
@@ -45386,26 +46285,20 @@ async function main() {
     agentWs.close();
     server.close();
     closeAllSseStreams();
-    const hard = setTimeout(() => process.exit(0), 8e3);
-    hard.unref?.();
-    void agent.close().finally(() => {
-      clearTimeout(hard);
-      process.exit(0);
-    });
+    closeReleaseExit();
   };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-  const instanceId = newInstanceId();
-  const identityId = agent.health().identity_id;
+  deps.onSignal("SIGINT", shutdown);
+  deps.onSignal("SIGTERM", shutdown);
   const slug = slugFromCredentialPath(credentialPath);
-  process.once("exit", () => removeConnectionFileIfOwned(homedir5(), identityId, instanceId));
-  server.listen(daemon.port, daemon.bind, () => {
-    writeServiceLog("info", "startup.listening", { port: daemon.port, tls: !!daemon.tls });
-    writeServiceLog("info", "startup.token_loaded");
+  deps.onExit(() => removeConnectionFileIfOwned(deps.home, identityId, instanceId));
+  server.listen(preBound, () => {
+    log("info", "startup.listening", { port: daemon.port, tls: !!daemon.tls });
+    log("info", "startup.token_loaded");
     const addr = server.address();
     const boundPort = typeof addr === "object" && addr ? addr.port : daemon.port;
+    if (superseded) return;
     try {
-      writeConnectionFile(homedir5(), buildConnectionFile({
+      writeConnectionFile(deps.home, buildConnectionFile({
         identityId,
         port: boundPort,
         tokenFile,
@@ -45414,12 +46307,52 @@ async function main() {
         instanceId,
         now: (/* @__PURE__ */ new Date()).toISOString()
       }));
-      writeServiceLog("info", "startup.connection_file_written");
+      log("info", "startup.connection_file_written");
     } catch (e) {
-      writeServiceLog("warn", "startup.connection_file_write_failed", {}, e);
+      log("warn", "startup.connection_file_write_failed", {}, e);
     }
   });
 }
+function printNoCredentialRunLine() {
+  process.stderr.write(`${noCredentialLine("run")}
+`);
+}
+async function main() {
+  if (!nodeMajorOk(process.versions.node)) {
+    writeServiceLog("error", "startup.node_unsupported");
+    process.exit(1);
+  }
+  const verb = parseVerb(process.argv);
+  if (verb === "pin") {
+    runPinVerb();
+    return;
+  }
+  if (verb === "status") {
+    runStatus();
+    return;
+  }
+  if (verb === "wire" || verb === "unwire") {
+    runWireVerb(verb);
+    return;
+  }
+  if (verb === "models") {
+    await runModelsVerb();
+    return;
+  }
+  if (verb) {
+    await runServiceVerb(verb);
+    return;
+  }
+  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));
+}
 var here = fileURLToPath4(import.meta.url);
 var isMain = !!process.argv[1] && refersToSameFile(here, process.argv[1], realpathSync3);
 if (isMain) {
@@ -45429,10 +46362,18 @@ if (isMain) {
   });
 }
 export {
+  HELD_NO_PID_REACQUIRES,
+  HELD_POLL_INTERVAL_MS,
+  HELD_POLL_TOTAL_MS,
+  SHUTDOWN_HARD_EXIT_MS,
   chooseInstallExecPath,
+  configErrorLine,
+  formatServiceError,
   nodeMajorOk,
   parseVerb,
   realCopyConnector,
+  realGetHealth,
+  runMode,
   slugFromCredentialPath,
   startThenServe,
   tokenFingerprint