@securecoms/agent-bridge 0.15.0 → 0.16.0

package/README.md

@@ -359,6 +359,7 @@ pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
 - Install **verifies the daemon actually came up** and fails loudly with the log path if it didn't — no silent crash-loops.
 - Install echoes the credential's `device_id`, `issued_at`, and a redacted api-key fingerprint so you can confirm you installed the newest download. **Re-running install is the only way to update a live (e.g. rotated) credential** — replacing the downloaded file alone does nothing.
 - Optional `--harness openclaw|hermes|custom` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output).
+- **One harness gateway serves one agent.** The connector registers a single platform and resolves a single bound identity for the life of the gateway process, so a connector directory (`~/.hermes/plugins/securecoms`, `~/.openclaw/local-plugins/securecoms`) holds exactly one agent. Install and `wire` therefore **refuse** to overwrite a binding that names a different agent — doing so would take the harness away from that agent, not add one alongside it. To run two agents on one host, give each its own harness profile with its own connector directory and binding. To deliberately move a harness to a different agent, pass `--rebind`.
 
 ---
 

package/connectors/hermes/adapter.py

@@ -132,7 +132,17 @@ class SecureComsAdapter(BasePlatformAdapter):
 
     # ── Connection lifecycle ──────────────────────────────────────────────
 
-    async def connect(self) -> bool:
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        """Connect to the local daemon.
+
+        ``is_reconnect`` mirrors BasePlatformAdapter.connect's signature —
+        gateway/run.py passes it as a keyword on EVERY call, cold boot
+        included, so an adapter that omits it raises TypeError and the
+        platform never attaches. SecureComs holds no server-side update
+        queue to preserve across an outage (the daemon is a local WS the
+        supervisor re-opens), so the flag carries no behaviour here.
+        """
+        del is_reconnect  # accepted for contract parity; nothing to preserve
         self._stopped = False
 
         # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -539,3 +539,36 @@ class TestCheckRequirementsWiring:
         monkeypatch.setenv("SECURECOMS_CONNECTION_FILE", str(tmp_path / "does-not-exist.json"))
 
         assert adapter.check_requirements() is False
+
+
+# ---------------------------------------------------------------------------
+# (6) connect() signature contract with BasePlatformAdapter
+# ---------------------------------------------------------------------------
+
+
+class TestConnectSignatureContract:
+    """gateway/run.py ALWAYS calls `adapter.connect(is_reconnect=...)` — on the
+    cold first boot as well as on every reconnect. An adapter whose connect()
+    does not accept that keyword raises TypeError inside the gateway's
+    connect helper, which the reconnect watcher reports as a platform error
+    and retries forever: the daemon looks connected to the SecureComs server
+    while the harness side never attaches and the agent never answers.
+    """
+
+    def test_connect_accepts_is_reconnect_keyword(self):
+        import inspect
+
+        sig = inspect.signature(adapter.SecureComsAdapter.connect)
+        param = sig.parameters.get("is_reconnect")
+        assert param is not None, "connect() must accept the is_reconnect keyword"
+        assert param.kind is inspect.Parameter.KEYWORD_ONLY
+        assert param.default is False
+
+    @pytest.mark.asyncio
+    async def test_connect_is_reconnect_true_reaches_the_unwired_path(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch, files={})  # no binding file -> unwired
+        ok = await a.connect(is_reconnect=True)
+        assert ok is False
+        code, _message, retryable = a.fatal_errors[-1]
+        assert code == "unwired"
+        assert retryable is False

package/dist/bin.js

@@ -1409,9 +1409,7 @@ var SUITE2 = "xchacha20poly1305";
 var AAD = new TextEncoder().encode("kekset");
 var enc = new TextEncoder();
 var dec = new TextDecoder();
-function unb64(s) {
-  return new Uint8Array(Buffer.from(s, "base64"));
-}
+var unb64 = base64ToBytes;
 function headerObject(h) {
   return {
     enclaveId: h.enclaveId,
@@ -11000,6 +10998,16 @@ function connectorTargetDir(home, harness) {
   if (harness === "openclaw") return `${home}/.openclaw/local-plugins/securecoms`;
   return `${home}/.hermes/plugins/securecoms`;
 }
+function checkBindingConflict(prev, next, allowRebind) {
+  if (!prev || prev === next) return { ok: true, rebindFrom: null };
+  if (allowRebind) return { ok: true, rebindFrom: prev };
+  return {
+    ok: false,
+    message: `refusing to rebind: this harness connector is already bound to ${prev}, not ${next}. A harness gateway serves ONE agent, so this would take the harness away from ${prev} rather than add ${next} alongside it.
+  To run both agents, give each one its own harness profile (its own connector dir + binding).
+  To deliberately move THIS harness to ${next}, re-run with --rebind.`
+  };
+}
 function connectorsSrcDir(importMetaUrl, harness) {
   const pkgRoot = dirname5(dirname5(fileURLToPath(importMetaUrl)));
   return join9(pkgRoot, "connectors", harness);
@@ -11061,8 +11069,18 @@ function runWire(deps) {
   if (!resolved) return 1;
   const { entry, harness } = resolved;
   const targetDir = connectorTargetDir(deps.home, harness);
+  const guard = checkBindingConflict(
+    deps.readBinding(targetDir),
+    entry.identityId,
+    deps.argv.includes("--rebind")
+  );
+  if (!guard.ok) {
+    deps.log(`wire: ${guard.message}`);
+    return 1;
+  }
   deps.copyConnector(deps.connectorsSrcDir(harness), targetDir, harness);
   deps.writeBinding(targetDir, entry.identityId);
+  if (guard.rebindFrom) deps.log(`wire: rebind: ${guard.rebindFrom} -> ${entry.identityId}`);
   if (harness === "hermes") {
     const enabled = enableHermesConfig(deps.home, deps);
     deps.log(`[securecoms] ${enabled.message}`);
@@ -11129,12 +11147,19 @@ function autoWireHarness(input, deps) {
       };
     }
     const targetDir = connectorTargetDir(input.home, "openclaw");
+    const guard = checkBindingConflict(deps.readBinding(targetDir), input.identityId, input.allowRebind ?? false);
+    if (!guard.ok) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but the OpenClaw connector was NOT wired: ${guard.message}`,
+        wired: false,
+        error: true
+      };
+    }
     try {
-      const prev = deps.readBinding(targetDir);
       deps.copyConnector(input.connectorsSrcDir, targetDir, "openclaw");
       deps.writeBinding(targetDir, input.identityId);
-      const rebind = prev && prev !== input.identityId ? `
-  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      const rebind = guard.rebindFrom ? `
+  rebind: ${guard.rebindFrom} \u2192 ${input.identityId}` : "";
       return {
         echo: `[securecoms] OpenClaw connector installed and bound to identity ${input.identityId}.${rebind}
   Now restart OpenClaw to pick up the connector.`,
@@ -11163,8 +11188,15 @@ function autoWireHarness(input, deps) {
       };
     }
     const targetDir = connectorTargetDir(input.home, "hermes");
+    const guard = checkBindingConflict(deps.readBinding(targetDir), input.identityId, input.allowRebind ?? false);
+    if (!guard.ok) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but the Hermes connector was NOT wired: ${guard.message}`,
+        wired: false,
+        error: true
+      };
+    }
     try {
-      const prev = deps.readBinding(targetDir);
       deps.copyConnector(input.connectorsSrcDir, targetDir, "hermes");
       deps.writeBinding(targetDir, input.identityId);
       const enabled = enableHermesConfig(input.home, deps);
@@ -11176,8 +11208,8 @@ function autoWireHarness(input, deps) {
           error: true
         };
       }
-      const rebind = prev && prev !== input.identityId ? `
-  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      const rebind = guard.rebindFrom ? `
+  rebind: ${guard.rebindFrom} \u2192 ${input.identityId}` : "";
       return {
         echo: `[securecoms] Hermes connector installed and bound to identity ${input.identityId}.${rebind}
   ${enabled.message}
@@ -11342,6 +11374,7 @@ async function orchestrateInstall(ctx) {
       identityId: parsed.identityId,
       slug,
       port,
+      allowRebind: ctx.allowRebind,
       home: ctx.home,
       tokenFilePath: result.tokenHint,
       connectorsSrcDir: ctx.connectorsSrcDir
@@ -11741,6 +11774,8 @@ function realWireDeps() {
     argv: realWireArgv(),
     readFleet: realReadFleet,
     copyConnector: realCopyConnector,
+    readBinding: realReadBinding,
+    // bin.ts:252 — feeds checkBindingConflict
     writeBinding: realWriteBinding,
     removeBinding: realRemoveBinding,
     getHealth: realGetHealth,
@@ -11786,6 +11821,7 @@ async function runServiceVerb(verb) {
         label,
         explicitPort: portStr ? Number(portStr) : void 0,
         harness: installHarness,
+        allowRebind: process.argv.includes("--rebind"),
         home: homedir2(),
         connectorsSrcDir: connectorsSrcDir(import.meta.url, installHarness === "hermes" ? "hermes" : "openclaw"),
         autoWireDeps: {

package/dist/index.js

@@ -1121,9 +1121,7 @@ var SUITE2 = "xchacha20poly1305";
 var AAD = new TextEncoder().encode("kekset");
 var enc = new TextEncoder();
 var dec = new TextDecoder();
-function unb64(s) {
-  return new Uint8Array(Buffer.from(s, "base64"));
-}
+var unb64 = base64ToBytes;
 function headerObject(h) {
   return {
     enclaveId: h.enclaveId,

package/dist/service/harness-wire.d.ts

@@ -7,6 +7,10 @@ export interface AutoWireInput {
     home: string;
     tokenFilePath: string;
     connectorsSrcDir: string;
+    /** Deliberate consent to move an already-bound harness to this identity
+     *  (`install --rebind`). Absent/false, a conflicting binding REFUSES —
+     *  see checkBindingConflict in wire.ts for why. */
+    allowRebind?: boolean;
 }
 export interface AutoWireDeps extends HermesConfigIoDeps {
     statDir: (p: string) => boolean;

package/dist/service/install-prep.d.ts

@@ -43,6 +43,7 @@ export interface OrchestrateInstallCtx {
     label?: string;
     explicitPort?: number;
     harness?: string;
+    allowRebind?: boolean;
     home: string;
     launchAgentsDir?: string;
     systemdDir?: string;

package/dist/service/wire.d.ts

@@ -38,6 +38,10 @@ export interface WireDeps extends HermesConfigIoDeps {
     argv: string[];
     readFleet: () => AgentFleetEntry[];
     copyConnector: (srcDir: string, dstDir: string, harness: Harness) => void;
+    /** The identity the target dir is ALREADY bound to, or null when nothing
+     *  is bound / the file is missing or malformed. Read BEFORE any write so
+     *  `checkBindingConflict` can refuse without having touched disk. */
+    readBinding: (dstDir: string) => string | null;
     writeBinding: (dstDir: string, identityId: string) => void;
     removeBinding: (dstDir: string) => void;
     getHealth: (port: number) => {
@@ -72,6 +76,32 @@ export declare function detectHarness(home: string, statDir: (p: string) => bool
  * placeholder value, never the real one).
  */
 export declare function connectorTargetDir(home: string, harness: Harness): string;
+/**
+ * The binding guard, shared by `wire` and by `install`'s auto-wire.
+ *
+ * A harness connector registers ONE platform and resolves ONE bound identity
+ * for the life of the gateway process (connectors/hermes/adapter.py's
+ * `register` + `_bound_identity`), so a connector directory holds exactly one
+ * agent. Writing a different identity over an existing binding therefore does
+ * not ADD an agent — it silently takes the harness away from whichever agent
+ * was already using it, leaving that agent dark while two gateways race for
+ * one daemon socket. Observed in the field 2026-09-08: installing a second
+ * Hermes agent rebound `~/.hermes/plugins/securecoms` away from the agent the
+ * default-profile gateway was serving.
+ *
+ * So an overwrite must be a deliberate act (`--rebind`), exactly like the
+ * binding itself is a deliberate act (audit C1). A first wire and an
+ * idempotent same-identity re-wire are always allowed.
+ *
+ * Pure: callers do the reading and the refusing.
+ */
+export declare function checkBindingConflict(prev: string | null, next: string, allowRebind: boolean): {
+    ok: true;
+    rebindFrom: string | null;
+} | {
+    ok: false;
+    message: string;
+};
 /**
  * Resolves a connector's SOURCE dir at runtime, keyed by harness (`connectors/
  * <harness>`) — `connectors/` is shipped SOURCE (not compiled — H2), so this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",