@securecoms/agent-bridge 0.16.0 → 0.18.0

package/README.md

@@ -305,6 +305,65 @@ Pick one receive mode — WebSocket, SSE, or long-poll — and stick with it. Th
 
 ---
 
+## Bring your own agent
+
+The daemon has no approved-framework list. It checks a bearer token and nothing else, so there is exactly one requirement:
+
+> **You must be able to add code to a process that stays running.**
+
+That is the whole test. If your agent is a program you control, it can hold a SecureComs channel in about fifty lines — see [`examples/ws-agent-client.mjs`](./examples/ws-agent-client.mjs) and [`ws-agent-client.py`](./examples/ws-agent-client.py), which are runnable as-is.
+
+To check your own connector against every rule in this section, run [`examples/byo-conformance.mjs`](./examples/byo-conformance.mjs) — a zero-dependency agent that follows the section literally and prints a pass/fail line per rule:
+
+```sh
+node examples/byo-conformance.mjs <your agent's identity_id>
+```
+
+**This fits.** Anything you build yourself, in any language: LangChain, LangGraph, CrewAI, AutoGen, Pydantic AI, the OpenAI or Anthropic agent SDKs, LlamaIndex — or a plain script calling an LLM API with no framework at all. You already own the process; you add a socket to it.
+
+**This does not fit.** Consumer chat products (claude.ai, ChatGPT, the Gemini app) have no extension point. Session-based coding CLIs have no always-on loop to attach to. A fully hosted agent you cannot run code beside cannot reach the daemon.
+
+**A platform you run but did not write** (Dify, Flowise, n8n, and the like) fits only if it lets you run persistent custom code. If it does, what you are writing is a plugin for that platform — the same job the bundled `openclaw` and `hermes` connectors do.
+
+Install with `--harness universal` to skip connector wiring and print the details your agent needs. (`--harness custom` is the old name for the same thing and still works.) Running `install` with no `--harness` at all does the same thing when neither OpenClaw nor Hermes is present.
+
+### Where your agent runs
+
+Same machine by default — the daemon binds `127.0.0.1`. Another machine works too, over TLS (see **Cross-host use** under Security). One caveat: a delivered attachment gives you a **local file path** on the daemon's machine, so an off-host agent can receive text, status, vault and A2A traffic but cannot read attachment bytes.
+
+### The five rules
+
+1. **Ack everything.** Delivery is at-least-once. Send `{type:"ack", message_id}` once you have durably handled a message, and dedup by `message_id`.
+2. **One consumer per daemon.** A second `/v1/ws` closes the first. Two clients will evict each other in a loop.
+3. **Answer the pings.** The daemon pings every 30s and reaps a socket that misses a pong. Standard WebSocket clients do this for you.
+4. **Read the token from its file, never from an environment value.** An env *value* is inherited by child processes and visible in `ps eww` and crash dumps. A path is not.
+5. **Check the identity gate before you attach.** Details below.
+
+### The identity gate
+
+Skip this and a single-agent host still works. The failure appears later, when a second agent is installed on the same machine, and it is silent.
+
+The daemon rewrites `~/.securecoms/connections/<identity_id>.json` on every start, giving you its current port and token-file path — so a moved port is picked up automatically. But if your connector reads the *wrong* agent's file, everything looks consistent: it authenticates successfully to that agent's daemon, drives that agent's identity, and evicts that agent's real connector.
+
+The bearer token does not catch this. It rejects a caller with *no* valid token; it does nothing against a caller holding a *valid but wrong* pair.
+
+So, before opening the WebSocket:
+
+1. Know which agent you are meant to serve — a fixed `identity_id`, from your own config. **Never** infer it by scanning the connections directory: on a multi-agent host a slow-starting daemon can leave exactly one file present at the moment you look, and you will bind to the wrong agent.
+2. Read that agent's connection file for `bridge_url` and `token_file`.
+3. `GET /healthz` (no token needed) and require **both**: the file's `identity_id` and your own fixed `identity_id` each equal `healthz.identity_id`.
+4. Any mismatch: do not open the socket. Back off with jitter and retry from step 2 — the port may have moved.
+
+On reconnect, re-read the connection file and the token, but **not** your identity. Re-deriving it on every reconnect lets a file appearing or disappearing silently re-bind a running connector to a different agent.
+
+The bundled `openclaw` and `hermes` connectors implement all of this; read either one as a worked example.
+
+### Separate compartments need separate OS uids
+
+The gate prevents honest mistakes. It is not a tenant boundary. The hop from daemon to agent carries plaintext, and the token and sealed store are readable by anyone sharing the uid — so any agent under the same uid can already drive another's daemon directly. **Agents in different orgs or enclaves that must not cross MUST run under different OS uids, or on different hosts.**
+
+---
+
 ## Run as a service
 
 For an autonomous agent running on a server, keep the daemon up with systemd so it restarts on failure and starts on boot. A sleeping or crashed daemon means its WebSocket/SSE connections drop and messages queue on the server until the daemon reconnects; they replay losslessly on wake. The daemon can't wake a sleeping machine.
@@ -358,7 +417,7 @@ pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
 - A **free port is auto-selected** from `7077-7276` (lowest free wins; sibling service definitions and live binds both count as taken). Pass `--port N` to override; the explicit port is honored as-is.
 - 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).
+- Optional `--harness openclaw|hermes|universal` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output). (`--harness custom` is an accepted alias for `universal`.)
 - **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/dist/bin.js

@@ -4834,6 +4834,9 @@ var FRAME_PARSERS = {
   }),
   voice_settings_changed: (d) => ({
     voiceSettingsChanged: { identityId: str(d?.identity_id), version: Number(d?.version ?? 0) }
+  }),
+  runtime_config_changed: (d) => ({
+    runtimeConfigChanged: { identityId: str(d?.identity_id), version: Number(d?.version ?? 0) }
   })
 };
 var S2C_FRAME_NAMES = new Set(Object.keys(FRAME_PARSERS));
@@ -6388,7 +6391,7 @@ var SqliteMlsStateStore = class {
 
 // src/bridge-agent.ts
 import { decryptFile as decryptFile2, encryptFile as encryptFile2, computeFileDigest as computeFileDigest2, base64ToBytes as base64ToBytes4, bytesToBase64 as bytesToBase644 } from "@agentvault/crypto";
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // src/service/resolve-bin.ts
 import { join as join2, dirname as dirname2 } from "node:path";
@@ -6441,7 +6444,7 @@ function loadPackageMeta(importMetaUrl) {
 
 // src/bridge-agent.ts
 import { promises as fsp } from "node:fs";
-import { join as join8, dirname as dirname3 } from "node:path";
+import { join as join9, dirname as dirname3 } from "node:path";
 
 // src/latency.ts
 var DEFAULT_CAPACITY = 1024;
@@ -7461,7 +7464,135 @@ async function runSummarize(opts) {
   }
 }
 
+// src/service/runtime-config-dir.ts
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync as readFileSync6,
+  renameSync,
+  statSync as statSync3,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { basename as basename2, join as join8 } from "node:path";
+var MEMORY_FILE = "MEMORY.md";
+var REAL_FS = {
+  mkdir: (p, mode) => mkdirSync(p, { recursive: true, mode }),
+  chmod: (p, mode) => chmodSync(p, mode),
+  writeFile: (p, data, mode) => writeFileSync(p, data, { mode }),
+  rename: (a, b) => renameSync(a, b),
+  readFile: (p) => readFileSync6(p, "utf8"),
+  unlink: (p) => unlinkSync(p)
+};
+function runtimeConfigDir(home, identityId) {
+  return join8(home, ".securecoms", "runtime-config", identityId);
+}
+function assertManagedName(name) {
+  if (!name || name.includes("/") || name.includes("\\") || name === "." || name === ".." || name !== basename2(name)) {
+    throw new Error(`refusing managed config file name ${JSON.stringify(name)}: not a plain filename`);
+  }
+}
+function atomicWrite(path, body, deps) {
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  deps.writeFile(tmp, body, 384);
+  deps.chmod(tmp, 384);
+  try {
+    deps.rename(tmp, path);
+  } catch (err) {
+    try {
+      deps.unlink(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+function writeManagedFiles(home, identityId, files, deps = REAL_FS) {
+  const entries = Object.entries(files);
+  for (const [name] of entries) assertManagedName(name);
+  const parent2 = join8(home, ".securecoms", "runtime-config");
+  const dir = runtimeConfigDir(home, identityId);
+  for (const d of [join8(home, ".securecoms"), parent2, dir]) {
+    deps.mkdir(d, 448);
+    deps.chmod(d, 448);
+  }
+  for (const [name, body] of entries) atomicWrite(join8(dir, name), body, deps);
+}
+function checkConfiguredPaths(skillsJson, statFn = (p) => {
+  const s = statSync3(p);
+  return { mode: s.mode, size: s.size };
+}) {
+  const paths = [];
+  const endpoints = skillsJson.endpoints ?? {};
+  for (const e of Object.values(endpoints)) if (e?.headersFile) paths.push(e.headersFile);
+  const databases = skillsJson.databases ?? {};
+  for (const d of Object.values(databases)) {
+    if (d?.sqlite) paths.push(d.sqlite);
+    if (d?.postgresUrlFile) paths.push(d.postgresUrlFile);
+  }
+  return paths.map((path) => {
+    let st;
+    try {
+      st = statFn(path);
+    } catch {
+      return { path, ok: false, why: "not found" };
+    }
+    if ((st.mode & 63) !== 0) {
+      return { path, ok: false, why: "readable by other users on this machine \u2014 tighten its permissions to owner-only" };
+    }
+    if (st.size === 0) return { path, ok: false, why: "the file is empty" };
+    return { path, ok: true, why: "" };
+  });
+}
+function lineHash(line) {
+  return createHash("sha256").update(line.trim(), "utf8").digest("hex");
+}
+var LOCAL_REPORT_FILE = "local-config.json";
+function readLocalReport(home, identityId) {
+  const p = join8(runtimeConfigDir(home, identityId), LOCAL_REPORT_FILE);
+  if (!existsSync(p)) return null;
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync6(p, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  const hasSearchKey = doc.has_search_key === true;
+  const raw = doc.persona;
+  const persona = raw && typeof raw === "object" && !Array.isArray(raw) ? Object.fromEntries(
+    Object.entries(raw).filter(([, v]) => typeof v === "string")
+  ) : {};
+  return { persona, has_search_key: hasSearchKey };
+}
+function readManagedMemory(home, identityId) {
+  const p = join8(runtimeConfigDir(home, identityId), MEMORY_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    const body = readFileSync6(p, "utf8").trim();
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+function pruneManagedMemory(home, identityId, hashes, deps = REAL_FS) {
+  const dir = runtimeConfigDir(home, identityId);
+  const path = join8(dir, MEMORY_FILE);
+  if (!existsSync(path)) return 0;
+  const drop = new Set(hashes);
+  const before = deps.readFile(path).split("\n");
+  const kept = before.filter((l) => l.trim() === "" || !drop.has(lineHash(l)));
+  const removed = before.filter((l) => l.trim() !== "" && drop.has(lineHash(l))).length;
+  if (removed === 0) return 0;
+  const body = kept.filter((l, i) => l.trim() !== "" || i < kept.length - 1).join("\n").trimEnd();
+  atomicWrite(path, body ? `${body}
+` : "", deps);
+  return removed;
+}
+
 // src/bridge-agent.ts
+import { homedir as homedir2 } from "node:os";
 var VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 var FAST_PATH_SPOKEN_GUIDANCE = "A one-sentence spoken acknowledgement has already been sent for this turn. Reply only with information it did not contain, in one or two short sentences; if there is nothing to add, send nothing.";
 var ROOM_VOICE_GUIDANCE_MENTION_ONLY = "You are in a group voice room. Reply ONLY when a message @mentions your display name. Keep replies to one short sentence. When you should not reply, send nothing.";
@@ -7516,7 +7647,7 @@ function resolveMessageId(messageId) {
   return messageId;
 }
 function fastReplyId(messageId) {
-  const h = createHash("sha256").update(`fast:${messageId}`).digest();
+  const h = createHash2("sha256").update(`fast:${messageId}`).digest();
   h[6] = h[6] & 15 | 64;
   h[8] = h[8] & 63 | 128;
   const x = h.subarray(0, 16).toString("hex");
@@ -7646,6 +7777,7 @@ var BridgeAgent = class _BridgeAgent {
       onSupersedeUnopenable: (channelId, groupId) => this.healSupersedeUnopenable(channelId, groupId)
     });
     this.fetchImpl = deps.fetchImpl ?? fetch;
+    this.home = deps.home ?? homedir2();
     this.injectedFastLlm = !!deps.fastLlm;
     this.fileVoiceConfig = cfg.voice;
     this.fastLlm = deps.fastLlm ?? (cfg.voice?.fastPath.enabled ? new FastLlmClient(cfg.voice.fastPath, this.fetchImpl) : void 0);
@@ -7678,8 +7810,8 @@ var BridgeAgent = class _BridgeAgent {
       const j = await res.json();
       return String(j.attachment_id);
     };
-    this.attachmentsDirImpl = deps.attachmentsDir ?? join8(dirname3(cfg.storePath), "attachments");
-    this.vaultOwnerStoreImpl = deps.vaultOwnerStore ?? new FileOwnerAuthorityStore(join8(dirname3(cfg.storePath), "vault-owner-pins.json"));
+    this.attachmentsDirImpl = deps.attachmentsDir ?? join9(dirname3(cfg.storePath), "attachments");
+    this.vaultOwnerStoreImpl = deps.vaultOwnerStore ?? new FileOwnerAuthorityStore(join9(dirname3(cfg.storePath), "vault-owner-pins.json"));
     this.action = {
       begin: (channelId) => this.actionBegin(channelId),
       start: (opts) => this.actionStart(opts),
@@ -7695,6 +7827,8 @@ var BridgeAgent = class _BridgeAgent {
   // stored for peek-then-join in ingestOnce
   custody;
   fetchImpl;
+  /** Round 5: home for the managed runtime-config directory (test seam). */
+  home;
   joinState = /* @__PURE__ */ new Map();
   /**
    * Phase 2: lazy channel-metadata cache (channel_id → { is_dm, name, at }) used
@@ -8036,6 +8170,84 @@ var BridgeAgent = class _BridgeAgent {
       if (this.voiceSettingsSource === "backend") return;
       process.stderr.write(
         `[bridge] voice settings unavailable (${e.message}); using ${this.voiceSettingsSource}
+`
+      );
+    }
+  }
+  /**
+   * Fetch this agent's runtime config and apply it to the managed directory the
+   * runtime reads (spec §8). Safe to call any time — at start(), or from the
+   * receive pump on a `runtime_config_changed` ping — and never throws: a save
+   * the owner already made must not be undone by a network blip here, and no
+   * shape the backend can send may take the daemon down.
+   *
+   * Order matters. Prunes are applied BEFORE the memory is read back, so the
+   * report the owner sees next is the file as it now stands.
+   *
+   * Every cycle rewrites, even at an unchanged version: directory permissions
+   * are repaired only on a write, so skipping would leave a loosened directory
+   * loose until the next save.
+   */
+  async refetchRuntimeConfig() {
+    const base = `${this.cfg.apiBase}/api/v1/agents/${encodeURIComponent(this.cfg.identityId)}/runtime-config`;
+    try {
+      const res = await this.fetchImpl(`${base}/files`, {
+        headers: { authorization: `Bearer ${this.cfg.apiKey}` }
+      });
+      if (!res.ok) throw new Error(`runtime-config ${res.status}`);
+      const payload = await res.json();
+      if (!payload || !payload.version) {
+        process.stderr.write(
+          `[bridge] runtime config not applied (version ${JSON.stringify(payload?.version ?? null)} \u2014 no saved config)
+`
+        );
+        return;
+      }
+      const skillsJson = payload.skills_json ?? {};
+      writeManagedFiles(this.home, this.cfg.identityId, {
+        ...payload.files ?? {},
+        "skills.json": `${JSON.stringify(skillsJson, null, 2)}
+`
+      });
+      if (payload.memory_prunes?.length) {
+        pruneManagedMemory(this.home, this.cfg.identityId, payload.memory_prunes);
+      }
+      const local = readLocalReport(this.home, this.cfg.identityId);
+      const report = {
+        applied_version: payload.version,
+        paths: checkConfiguredPaths(skillsJson),
+        // Read AFTER the prunes above, so the owner's next view of memory is
+        // the file as it now stands, not the one they just pruned from.
+        memory: readManagedMemory(this.home, this.cfg.identityId),
+        // E13: pass through what the runtime reported. The daemon does not
+        // interpret any of it.
+        local_persona: local?.persona ?? null,
+        // Only the runtime knows whether a search key file is configured — it
+        // is an environment value on that process, invisible to the daemon and
+        // to the backend. The backend needs it to generate a truthful tool
+        // paragraph, so it rides along here.
+        has_search_key: local?.has_search_key ?? false
+      };
+      const posted = await this.fetchImpl(`${base}/report`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.cfg.apiKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(report)
+      });
+      if (!posted.ok) {
+        process.stderr.write(
+          `[bridge] runtime config v${payload.version} written, but reporting it failed (${posted.status}) \u2014 the console will keep showing it as not applied until the next cycle
+`
+        );
+        return;
+      }
+      process.stderr.write(`[bridge] runtime config v${payload.version} applied
+`);
+    } catch (e) {
+      process.stderr.write(
+        `[bridge] runtime config refetch failed: ${e?.message ?? e}
 `
       );
     }
@@ -8067,6 +8279,7 @@ var BridgeAgent = class _BridgeAgent {
     }
     await this.provider.publishKeyPackage();
     await this.refetchVoiceSettings();
+    await this.refetchRuntimeConfig();
     this.startReceivePump();
     if (this.selfHealSweepEnabled) {
       this.bootSweepTimer = setTimeout(
@@ -9551,11 +9764,16 @@ var BridgeAgent = class _BridgeAgent {
           this.pingsReceived++;
           if (ping?.reconnected) {
             process.stderr.write("[bridge] delivery-ping WS (re)connected \u2014 push inbound active\n");
+            await this.refetchRuntimeConfig();
           }
           if (ping?.voiceSettingsChanged) {
             await this.refetchVoiceSettings();
             continue;
           }
+          if (ping?.runtimeConfigChanged) {
+            await this.refetchRuntimeConfig();
+            continue;
+          }
           await this.ingestOnce();
         }
       } catch {
@@ -9994,13 +10212,13 @@ var BridgeAgent = class _BridgeAgent {
 
 // src/auth.ts
 import { randomBytes as randomBytes3, timingSafeEqual } from "node:crypto";
-import { existsSync, readFileSync as readFileSync6, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
 function resolveToken(opts) {
   if (opts.token) return opts.token;
   const f = opts.tokenFile;
-  if (f && existsSync(f)) return readFileSync6(f, "utf8").trim();
+  if (f && existsSync2(f)) return readFileSync7(f, "utf8").trim();
   const tok = randomBytes3(32).toString("base64url");
-  if (f) writeFileSync(f, tok, { mode: 384 });
+  if (f) writeFileSync2(f, tok, { mode: 384 });
   return tok;
 }
 function tokenMatches(provided, expected) {
@@ -10621,17 +10839,17 @@ async function handleInbound(sock, agent, data, inflight) {
 }
 
 // src/bin.ts
-import { readFileSync as readFileSync8, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, rmSync, existsSync as existsSync2, realpathSync, readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
-import { join as join12, dirname as dirname7, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
+import { readFileSync as readFileSync9, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, rmSync, existsSync as existsSync3, realpathSync, readdirSync as readdirSync2, statSync as statSync4 } from "node:fs";
+import { join as join13, dirname as dirname7, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { homedir as homedir2, userInfo } from "node:os";
+import { homedir as homedir3, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 
 // src/service/install.ts
 import { dirname as dirname4 } from "node:path";
 
 // src/service/config.ts
-import { basename as basename2, extname, isAbsolute, resolve } from "node:path";
+import { basename as basename3, extname, isAbsolute, resolve } from "node:path";
 
 // src/service/resolve-node.ts
 var REQUIRED_NODE_MAJOR = 24;
@@ -10709,7 +10927,7 @@ function deriveServiceConfig(input) {
       `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>.`
     );
   }
-  const stem = input.label ?? basename2(input.credentialPath, extname(input.credentialPath));
+  const stem = input.label ?? basename3(input.credentialPath, extname(input.credentialPath));
   const slug = slugify(stem);
   const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
   const args2 = ["--credential", cred];
@@ -10831,10 +11049,10 @@ function uninstallService(input, deps) {
 }
 
 // src/service/install-prep.ts
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 
 // src/service/wire.ts
-import { join as join9, dirname as dirname5 } from "node:path";
+import { join as join10, dirname as dirname5 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/service/hermes-config.ts
@@ -11010,7 +11228,7 @@ function checkBindingConflict(prev, next, allowRebind) {
 }
 function connectorsSrcDir(importMetaUrl, harness) {
   const pkgRoot = dirname5(dirname5(fileURLToPath(importMetaUrl)));
-  return join9(pkgRoot, "connectors", harness);
+  return join10(pkgRoot, "connectors", harness);
 }
 function hermesConfigPath(home) {
   return `${home}/.hermes/config.yaml`;
@@ -11125,15 +11343,30 @@ function runUnwire(deps) {
 function customFacts(input) {
   const ws = `ws://127.0.0.1:${input.port ?? "<PORT>"}/v1/ws`;
   return [
-    `  bridge WS:   ${ws}`,
-    `  token file:  ${input.tokenFilePath}`,
+    `  bridge WS:     ${ws}`,
+    `  token file:    ${input.tokenFilePath}`,
+    `  agent id:      ${input.identityId}`,
+    `  discovery:     ~/.securecoms/connections/${input.identityId}.json (rewritten on every daemon start)`,
     `  Bring your own connector: open the WS with the bearer token read from that file.`,
+    `  Ack every message you receive; delivery is at-least-once, so dedup by message_id.`,
+    `  Before you attach, check the identity gate: the daemon's /healthz identity_id MUST equal`,
+    `    the agent id above. Skipping it means a second agent on this host can silently`,
+    `    drive the wrong daemon. See "Bring your own agent" in the agent-bridge README.`,
     `  Protocol reference: the "WebSocket" section of the agent-bridge README.`
   ].join("\n");
 }
 function autoWireHarness(input, deps) {
   const h = input.harness;
-  if (!h || h === "none") return { echo: "", wired: false, error: false };
+  if (h === "none") return { echo: "", wired: false, error: false };
+  if (!h) {
+    return {
+      echo: `[securecoms] No agent harness detected (no ~/.openclaw, no ~/.hermes) \u2014 the bridge service is installed and running, but nothing is attached to it yet.
+  Bring your own agent:
+${customFacts(input)}`,
+      wired: false,
+      error: false
+    };
+  }
   if (h === "openclaw") {
     const retry = `agent-bridge wire --harness openclaw --identity ${input.slug}`;
     const parent2 = `${input.home}/.openclaw`;
@@ -11141,7 +11374,7 @@ function autoWireHarness(input, deps) {
       return {
         echo: `[securecoms] OpenClaw not found at ~/.openclaw \u2014 the bridge service is installed, but the harness was NOT wired.
   Install OpenClaw, then re-run install, or run: ${retry}
-  (or re-run install with --harness custom).`,
+  (or re-run install with --harness universal).`,
         wired: false,
         error: true
       };
@@ -11182,7 +11415,7 @@ function autoWireHarness(input, deps) {
       return {
         echo: `[securecoms] Hermes not found at ~/.hermes \u2014 the bridge service is installed, but the harness was NOT wired.
   Install Hermes, then re-run install, or run: ${retry}
-  (or re-run install with --harness custom).`,
+  (or re-run install with --harness universal).`,
         wired: false,
         error: true
       };
@@ -11226,7 +11459,7 @@ function autoWireHarness(input, deps) {
       };
     }
   }
-  return { echo: `[securecoms] Custom harness \u2014 bring your own connector:
+  return { echo: `[securecoms] Universal \u2014 bring your own agent:
 ${customFacts(input)}`, wired: false, error: false };
 }
 
@@ -11253,10 +11486,10 @@ function assertReadableCredential(absPath, deps) {
   return { deviceId: json2.device_id, identityId: json2.identity_id, issuedAt };
 }
 function durableDir(home, slug) {
-  return join10(home, `securecoms-agent-${slug}`);
+  return join11(home, `securecoms-agent-${slug}`);
 }
 function durableCredentialPath(home, slug) {
-  return join10(durableDir(home, slug), `${slug}.json`);
+  return join11(durableDir(home, slug), `${slug}.json`);
 }
 function takeCustody(args2, deps) {
   const dir = durableDir(args2.home, args2.slug);
@@ -11303,7 +11536,7 @@ function readSiblingDefs(dir, prefix, deps) {
   for (const n of names) {
     if (!n.startsWith(prefix)) continue;
     try {
-      out.push(deps.readFile(join10(dir, n)));
+      out.push(deps.readFile(join11(dir, n)));
     } catch {
     }
   }
@@ -11498,34 +11731,34 @@ function renderStatusTable(rows) {
 
 // src/service/connection-file.ts
 import {
-  chmodSync,
-  mkdirSync,
-  readFileSync as readFileSync7,
-  renameSync,
-  unlinkSync,
-  writeFileSync as writeFileSync2
+  chmodSync as chmodSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync8,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { join as join11 } from "node:path";
-var REAL_FS = {
-  mkdir: (p, mode) => mkdirSync(p, { recursive: true, mode }),
-  chmod: (p, mode) => chmodSync(p, mode),
-  writeFile: (p, data, mode) => writeFileSync2(p, data, { mode }),
-  rename: (a, b) => renameSync(a, b),
-  readFile: (p) => readFileSync7(p, "utf8"),
-  unlink: (p) => unlinkSync(p)
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { join as join12 } from "node:path";
+var REAL_FS2 = {
+  mkdir: (p, mode) => mkdirSync2(p, { recursive: true, mode }),
+  chmod: (p, mode) => chmodSync2(p, mode),
+  writeFile: (p, data, mode) => writeFileSync3(p, data, { mode }),
+  rename: (a, b) => renameSync2(a, b),
+  readFile: (p) => readFileSync8(p, "utf8"),
+  unlink: (p) => unlinkSync2(p)
 };
 function securecomsDir(home) {
-  return join11(home, ".securecoms");
+  return join12(home, ".securecoms");
 }
 function connectionsDir(home) {
-  return join11(securecomsDir(home), "connections");
+  return join12(securecomsDir(home), "connections");
 }
 function connectionFilePath(home, identityId) {
-  return join11(connectionsDir(home), `${identityId}.json`);
+  return join12(connectionsDir(home), `${identityId}.json`);
 }
 function newInstanceId() {
-  return randomUUID();
+  return randomUUID2();
 }
 function buildConnectionFile(args2) {
   return {
@@ -11539,18 +11772,18 @@ function buildConnectionFile(args2) {
     written_at: args2.now
   };
 }
-function writeConnectionFile(home, doc, deps = REAL_FS) {
+function writeConnectionFile(home, doc, deps = REAL_FS2) {
   deps.mkdir(securecomsDir(home), 448);
   deps.chmod(securecomsDir(home), 448);
   deps.mkdir(connectionsDir(home), 448);
   deps.chmod(connectionsDir(home), 448);
   const path = connectionFilePath(home, doc.identity_id);
-  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const tmp = `${path}.${process.pid}.${randomUUID2()}.tmp`;
   deps.writeFile(tmp, JSON.stringify(doc, null, 2) + "\n", 384);
   deps.chmod(tmp, 384);
   deps.rename(tmp, path);
 }
-function removeConnectionFileIfOwned(home, identityId, instanceId, deps = REAL_FS) {
+function removeConnectionFileIfOwned(home, identityId, instanceId, deps = REAL_FS2) {
   const path = connectionFilePath(home, identityId);
   try {
     const cur = JSON.parse(deps.readFile(path));
@@ -11591,10 +11824,10 @@ function realServiceDeps() {
       const r = spawnSync(cmd, args2, { encoding: "utf8" });
       return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
     },
-    writeFile: (p, data) => writeFileSync3(p, data, { mode: 420 }),
+    writeFile: (p, data) => writeFileSync4(p, data, { mode: 420 }),
     removeFile: (p) => rmSync(p, { force: true }),
-    mkdirp: (p) => mkdirSync2(p, { recursive: true }),
-    fileExists: (p) => existsSync2(p),
+    mkdirp: (p) => mkdirSync3(p, { recursive: true }),
+    fileExists: (p) => existsSync3(p),
     user: userInfo().username
   };
 }
@@ -11617,7 +11850,7 @@ function realResolveNodeDeps() {
   };
   return {
     realpath: (p) => realpathSync(p),
-    fileExists: (p) => existsSync2(p),
+    fileExists: (p) => existsSync3(p),
     nodeMajorOf: majorOf,
     arch: () => process.arch,
     archOf: (p) => {
@@ -11632,17 +11865,17 @@ function realResolveDeps() {
       const r = spawnSync(cmd, args2, { encoding: "utf8" });
       return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
     },
-    fileExists: (p) => existsSync2(p)
+    fileExists: (p) => existsSync3(p)
   };
 }
 function realPrepDeps() {
   return {
-    readFile: (p) => readFileSync8(p, "utf8"),
-    writeFileMode: (p, data, mode) => writeFileSync3(p, data, { mode }),
+    readFile: (p) => readFileSync9(p, "utf8"),
+    writeFileMode: (p, data, mode) => writeFileSync4(p, data, { mode }),
     mkdirp: (p, mode) => {
-      mkdirSync2(p, { recursive: true, mode: mode ?? 493 });
+      mkdirSync3(p, { recursive: true, mode: mode ?? 493 });
     },
-    fileExists: (p) => existsSync2(p),
+    fileExists: (p) => existsSync3(p),
     realpath: (p) => realpathSync(p),
     listDir: (p) => {
       try {
@@ -11685,7 +11918,7 @@ function realGetHealth(port) {
 }
 function realReadFleet() {
   return readFleet({
-    home: homedir2(),
+    home: homedir3(),
     listDir: (p) => {
       try {
         return readdirSync2(p);
@@ -11693,7 +11926,7 @@ function realReadFleet() {
         return [];
       }
     },
-    readFile: (p) => readFileSync8(p, "utf8")
+    readFile: (p) => readFileSync9(p, "utf8")
   });
 }
 function runStatus() {
@@ -11715,62 +11948,62 @@ function runStatus() {
 }
 function realCopyConnector(srcDir, dstDir, harness) {
   const allowedExt = CONNECTOR_FILE_EXTENSIONS[harness];
-  mkdirSync2(dstDir, { recursive: true });
+  mkdirSync3(dstDir, { recursive: true });
   for (const name of readdirSync2(srcDir)) {
-    const srcPath = join12(srcDir, name);
-    if (statSync3(srcPath).isDirectory()) {
+    const srcPath = join13(srcDir, name);
+    if (statSync4(srcPath).isDirectory()) {
       if (CONNECTOR_SKIP_DIRS.has(name)) continue;
-      realCopyConnector(srcPath, join12(dstDir, name), harness);
+      realCopyConnector(srcPath, join13(dstDir, name), harness);
       continue;
     }
     if (name.includes(".test.")) continue;
     if (!allowedExt.some((ext) => name.endsWith(ext))) continue;
-    writeFileSync3(join12(dstDir, name), readFileSync8(srcPath));
+    writeFileSync4(join13(dstDir, name), readFileSync9(srcPath));
   }
 }
 function realWriteBinding(dstDir, identityId) {
-  mkdirSync2(dstDir, { recursive: true });
-  writeFileSync3(join12(dstDir, "securecoms.binding.json"), JSON.stringify({ identity_id: identityId }) + "\n", { mode: 384 });
+  mkdirSync3(dstDir, { recursive: true });
+  writeFileSync4(join13(dstDir, "securecoms.binding.json"), JSON.stringify({ identity_id: identityId }) + "\n", { mode: 384 });
 }
 function realReadBinding(dstDir) {
   try {
-    const parsed = JSON.parse(readFileSync8(join12(dstDir, "securecoms.binding.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync9(join13(dstDir, "securecoms.binding.json"), "utf8"));
     return parsed.identity_id ?? null;
   } catch {
     return null;
   }
 }
 function realRemoveBinding(dstDir) {
-  rmSync(join12(dstDir, "securecoms.binding.json"), { force: true });
+  rmSync(join13(dstDir, "securecoms.binding.json"), { force: true });
 }
 function realStatDir(p) {
   try {
-    return statSync3(p).isDirectory();
+    return statSync4(p).isDirectory();
   } catch {
     return false;
   }
 }
 function realReadHermesConfig(p) {
   try {
-    return readFileSync8(p, "utf8");
+    return readFileSync9(p, "utf8");
   } catch {
     return null;
   }
 }
 function realBackupHermesConfig(p, originalText) {
-  writeFileSync3(hermesConfigBackupPath(p, Date.now(), process.pid), originalText, "utf8");
+  writeFileSync4(hermesConfigBackupPath(p, Date.now(), process.pid), originalText, "utf8");
 }
 function realWriteHermesConfig(p, newText) {
-  writeFileSync3(p, newText, "utf8");
+  writeFileSync4(p, newText, "utf8");
 }
 function realWireArgv() {
   if (process.argv.includes("--harness")) return process.argv;
-  const detected = detectHarness(homedir2(), realStatDir);
+  const detected = detectHarness(homedir3(), realStatDir);
   return detected ? [...process.argv, "--harness", detected] : process.argv;
 }
 function realWireDeps() {
   return {
-    home: homedir2(),
+    home: homedir3(),
     argv: realWireArgv(),
     readFleet: realReadFleet,
     copyConnector: realCopyConnector,
@@ -11797,7 +12030,7 @@ async function runServiceVerb(verb) {
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
   if (verb === "install" ? !credentialPath : !credentialPath && !label) {
     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|custom]${execPathUsage}
+    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|universal]${execPathUsage}
 `);
     process.exit(2);
   }
@@ -11822,7 +12055,7 @@ async function runServiceVerb(verb) {
         explicitPort: portStr ? Number(portStr) : void 0,
         harness: installHarness,
         allowRebind: process.argv.includes("--rebind"),
-        home: homedir2(),
+        home: homedir3(),
         connectorsSrcDir: connectorsSrcDir(import.meta.url, installHarness === "hermes" ? "hermes" : "openclaw"),
         autoWireDeps: {
           statDir: realStatDir,
@@ -11849,7 +12082,7 @@ async function runServiceVerb(verb) {
           label,
           execPath: installExecPath,
           binScript,
-          home: homedir2(),
+          home: homedir3(),
           uid: userInfo().uid
         })
       });
@@ -11863,7 +12096,7 @@ async function runServiceVerb(verb) {
         label,
         execPath: process.execPath,
         binScript,
-        home: homedir2(),
+        home: homedir3(),
         uid: userInfo().uid
       };
       const r = uninstallService(input, realServiceDeps());
@@ -11914,11 +12147,11 @@ async function main() {
 `);
     process.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join12(dirname7(credentialPath), "bridge-token");
+  const tokenFile = daemon.tokenFile ?? join13(dirname7(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
   const agent = new BridgeAgent(cfg);
   await agent.start();
-  const tls = daemon.tls ? { cert: readFileSync8(daemon.tlsCert, "utf8"), key: readFileSync8(daemon.tlsKey, "utf8") } : void 0;
+  const tls = daemon.tls ? { cert: readFileSync9(daemon.tlsCert, "utf8"), key: readFileSync9(daemon.tlsKey, "utf8") } : void 0;
   const { server, closeAllSseStreams } = createHttpServer(agent, { token, allowOrigins: daemon.allowOrigins, tls, websocket: true });
   const agentWs = attachAgentWebSocket(server, agent, { token, allowOrigins: daemon.allowOrigins });
   let down = false;
@@ -11940,7 +12173,7 @@ async function main() {
   const instanceId = newInstanceId();
   const identityId = agent.health().identity_id;
   const slug = slugFromCredentialPath(credentialPath);
-  process.once("exit", () => removeConnectionFileIfOwned(homedir2(), identityId, instanceId));
+  process.once("exit", () => removeConnectionFileIfOwned(homedir3(), identityId, instanceId));
   server.listen(daemon.port, daemon.bind, () => {
     const scheme = tls ? "https" : "http";
     const wsScheme = tls ? "wss" : "ws";
@@ -11951,7 +12184,7 @@ async function main() {
     const addr = server.address();
     const boundPort = typeof addr === "object" && addr ? addr.port : daemon.port;
     try {
-      writeConnectionFile(homedir2(), buildConnectionFile({
+      writeConnectionFile(homedir3(), buildConnectionFile({
         identityId,
         port: boundPort,
         tokenFile,

package/dist/bridge-agent.d.ts

@@ -144,6 +144,13 @@ export interface BridgeAgentDeps {
     transport?: any;
     backend?: any;
     fetchImpl?: typeof fetch;
+    /**
+     * Round 5 (runtime config delivery): the home directory under which the
+     * managed runtime-config directory lives. Injected only by tests, so they can
+     * write into a temp dir instead of the developer's real ~; production leaves
+     * it undefined and gets homedir().
+     */
+    home?: string;
     /** Injectable so tests can assert recorded stages; defaults to a fresh one. */
     latency?: LatencyRecorder;
     /**
@@ -341,6 +348,8 @@ export declare class BridgeAgent {
     private readonly backend;
     private readonly custody;
     private readonly fetchImpl;
+    /** Round 5: home for the managed runtime-config directory (test seam). */
+    private readonly home;
     private readonly joinState;
     /**
      * Phase 2: lazy channel-metadata cache (channel_id → { is_dm, name, at }) used
@@ -642,6 +651,21 @@ export declare class BridgeAgent {
      * `voice_settings_changed` ping); never throws.
      */
     refetchVoiceSettings(): Promise<void>;
+    /**
+     * Fetch this agent's runtime config and apply it to the managed directory the
+     * runtime reads (spec §8). Safe to call any time — at start(), or from the
+     * receive pump on a `runtime_config_changed` ping — and never throws: a save
+     * the owner already made must not be undone by a network blip here, and no
+     * shape the backend can send may take the daemon down.
+     *
+     * Order matters. Prunes are applied BEFORE the memory is read back, so the
+     * report the owner sees next is the file as it now stands.
+     *
+     * Every cycle rewrites, even at an unchanged version: directory permissions
+     * are repaired only on a write, so skipping would leave a loosened directory
+     * loose until the next save.
+     */
+    refetchRuntimeConfig(): Promise<void>;
     /**
      * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
      *

package/dist/index.js

@@ -4546,6 +4546,9 @@ var FRAME_PARSERS = {
   }),
   voice_settings_changed: (d) => ({
     voiceSettingsChanged: { identityId: str(d?.identity_id), version: Number(d?.version ?? 0) }
+  }),
+  runtime_config_changed: (d) => ({
+    runtimeConfigChanged: { identityId: str(d?.identity_id), version: Number(d?.version ?? 0) }
   })
 };
 var S2C_FRAME_NAMES = new Set(Object.keys(FRAME_PARSERS));
@@ -6100,7 +6103,7 @@ var SqliteMlsStateStore = class {
 
 // src/bridge-agent.ts
 import { decryptFile as decryptFile2, encryptFile as encryptFile2, computeFileDigest as computeFileDigest2, base64ToBytes as base64ToBytes4, bytesToBase64 as bytesToBase644 } from "@agentvault/crypto";
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // src/service/resolve-bin.ts
 import { createRequire } from "node:module";
@@ -6112,7 +6115,7 @@ function loadPackageMeta(importMetaUrl) {
 
 // src/bridge-agent.ts
 import { promises as fsp } from "node:fs";
-import { join as join6, dirname } from "node:path";
+import { join as join7, dirname } from "node:path";
 
 // src/latency.ts
 var DEFAULT_CAPACITY = 1024;
@@ -7308,7 +7311,135 @@ async function runSummarize(opts) {
   }
 }
 
+// src/service/runtime-config-dir.ts
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync as readFileSync5,
+  renameSync,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { basename as basename2, join as join6 } from "node:path";
+var MEMORY_FILE = "MEMORY.md";
+var REAL_FS = {
+  mkdir: (p, mode) => mkdirSync(p, { recursive: true, mode }),
+  chmod: (p, mode) => chmodSync(p, mode),
+  writeFile: (p, data, mode) => writeFileSync(p, data, { mode }),
+  rename: (a, b) => renameSync(a, b),
+  readFile: (p) => readFileSync5(p, "utf8"),
+  unlink: (p) => unlinkSync(p)
+};
+function runtimeConfigDir(home, identityId) {
+  return join6(home, ".securecoms", "runtime-config", identityId);
+}
+function assertManagedName(name) {
+  if (!name || name.includes("/") || name.includes("\\") || name === "." || name === ".." || name !== basename2(name)) {
+    throw new Error(`refusing managed config file name ${JSON.stringify(name)}: not a plain filename`);
+  }
+}
+function atomicWrite(path, body, deps) {
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  deps.writeFile(tmp, body, 384);
+  deps.chmod(tmp, 384);
+  try {
+    deps.rename(tmp, path);
+  } catch (err) {
+    try {
+      deps.unlink(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+function writeManagedFiles(home, identityId, files, deps = REAL_FS) {
+  const entries = Object.entries(files);
+  for (const [name] of entries) assertManagedName(name);
+  const parent2 = join6(home, ".securecoms", "runtime-config");
+  const dir = runtimeConfigDir(home, identityId);
+  for (const d of [join6(home, ".securecoms"), parent2, dir]) {
+    deps.mkdir(d, 448);
+    deps.chmod(d, 448);
+  }
+  for (const [name, body] of entries) atomicWrite(join6(dir, name), body, deps);
+}
+function checkConfiguredPaths(skillsJson, statFn = (p) => {
+  const s = statSync2(p);
+  return { mode: s.mode, size: s.size };
+}) {
+  const paths = [];
+  const endpoints = skillsJson.endpoints ?? {};
+  for (const e of Object.values(endpoints)) if (e?.headersFile) paths.push(e.headersFile);
+  const databases = skillsJson.databases ?? {};
+  for (const d of Object.values(databases)) {
+    if (d?.sqlite) paths.push(d.sqlite);
+    if (d?.postgresUrlFile) paths.push(d.postgresUrlFile);
+  }
+  return paths.map((path) => {
+    let st;
+    try {
+      st = statFn(path);
+    } catch {
+      return { path, ok: false, why: "not found" };
+    }
+    if ((st.mode & 63) !== 0) {
+      return { path, ok: false, why: "readable by other users on this machine \u2014 tighten its permissions to owner-only" };
+    }
+    if (st.size === 0) return { path, ok: false, why: "the file is empty" };
+    return { path, ok: true, why: "" };
+  });
+}
+function lineHash(line) {
+  return createHash("sha256").update(line.trim(), "utf8").digest("hex");
+}
+var LOCAL_REPORT_FILE = "local-config.json";
+function readLocalReport(home, identityId) {
+  const p = join6(runtimeConfigDir(home, identityId), LOCAL_REPORT_FILE);
+  if (!existsSync(p)) return null;
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync5(p, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  const hasSearchKey = doc.has_search_key === true;
+  const raw = doc.persona;
+  const persona = raw && typeof raw === "object" && !Array.isArray(raw) ? Object.fromEntries(
+    Object.entries(raw).filter(([, v]) => typeof v === "string")
+  ) : {};
+  return { persona, has_search_key: hasSearchKey };
+}
+function readManagedMemory(home, identityId) {
+  const p = join6(runtimeConfigDir(home, identityId), MEMORY_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    const body = readFileSync5(p, "utf8").trim();
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+function pruneManagedMemory(home, identityId, hashes, deps = REAL_FS) {
+  const dir = runtimeConfigDir(home, identityId);
+  const path = join6(dir, MEMORY_FILE);
+  if (!existsSync(path)) return 0;
+  const drop = new Set(hashes);
+  const before = deps.readFile(path).split("\n");
+  const kept = before.filter((l) => l.trim() === "" || !drop.has(lineHash(l)));
+  const removed = before.filter((l) => l.trim() !== "" && drop.has(lineHash(l))).length;
+  if (removed === 0) return 0;
+  const body = kept.filter((l, i) => l.trim() !== "" || i < kept.length - 1).join("\n").trimEnd();
+  atomicWrite(path, body ? `${body}
+` : "", deps);
+  return removed;
+}
+
 // src/bridge-agent.ts
+import { homedir as homedir2 } from "node:os";
 var VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 var FAST_PATH_SPOKEN_GUIDANCE = "A one-sentence spoken acknowledgement has already been sent for this turn. Reply only with information it did not contain, in one or two short sentences; if there is nothing to add, send nothing.";
 var ROOM_VOICE_GUIDANCE_MENTION_ONLY = "You are in a group voice room. Reply ONLY when a message @mentions your display name. Keep replies to one short sentence. When you should not reply, send nothing.";
@@ -7363,7 +7494,7 @@ function resolveMessageId(messageId) {
   return messageId;
 }
 function fastReplyId(messageId) {
-  const h = createHash("sha256").update(`fast:${messageId}`).digest();
+  const h = createHash2("sha256").update(`fast:${messageId}`).digest();
   h[6] = h[6] & 15 | 64;
   h[8] = h[8] & 63 | 128;
   const x = h.subarray(0, 16).toString("hex");
@@ -7493,6 +7624,7 @@ var BridgeAgent = class _BridgeAgent {
       onSupersedeUnopenable: (channelId, groupId) => this.healSupersedeUnopenable(channelId, groupId)
     });
     this.fetchImpl = deps.fetchImpl ?? fetch;
+    this.home = deps.home ?? homedir2();
     this.injectedFastLlm = !!deps.fastLlm;
     this.fileVoiceConfig = cfg.voice;
     this.fastLlm = deps.fastLlm ?? (cfg.voice?.fastPath.enabled ? new FastLlmClient(cfg.voice.fastPath, this.fetchImpl) : void 0);
@@ -7525,8 +7657,8 @@ var BridgeAgent = class _BridgeAgent {
       const j = await res.json();
       return String(j.attachment_id);
     };
-    this.attachmentsDirImpl = deps.attachmentsDir ?? join6(dirname(cfg.storePath), "attachments");
-    this.vaultOwnerStoreImpl = deps.vaultOwnerStore ?? new FileOwnerAuthorityStore(join6(dirname(cfg.storePath), "vault-owner-pins.json"));
+    this.attachmentsDirImpl = deps.attachmentsDir ?? join7(dirname(cfg.storePath), "attachments");
+    this.vaultOwnerStoreImpl = deps.vaultOwnerStore ?? new FileOwnerAuthorityStore(join7(dirname(cfg.storePath), "vault-owner-pins.json"));
     this.action = {
       begin: (channelId) => this.actionBegin(channelId),
       start: (opts) => this.actionStart(opts),
@@ -7542,6 +7674,8 @@ var BridgeAgent = class _BridgeAgent {
   // stored for peek-then-join in ingestOnce
   custody;
   fetchImpl;
+  /** Round 5: home for the managed runtime-config directory (test seam). */
+  home;
   joinState = /* @__PURE__ */ new Map();
   /**
    * Phase 2: lazy channel-metadata cache (channel_id → { is_dm, name, at }) used
@@ -7883,6 +8017,84 @@ var BridgeAgent = class _BridgeAgent {
       if (this.voiceSettingsSource === "backend") return;
       process.stderr.write(
         `[bridge] voice settings unavailable (${e.message}); using ${this.voiceSettingsSource}
+`
+      );
+    }
+  }
+  /**
+   * Fetch this agent's runtime config and apply it to the managed directory the
+   * runtime reads (spec §8). Safe to call any time — at start(), or from the
+   * receive pump on a `runtime_config_changed` ping — and never throws: a save
+   * the owner already made must not be undone by a network blip here, and no
+   * shape the backend can send may take the daemon down.
+   *
+   * Order matters. Prunes are applied BEFORE the memory is read back, so the
+   * report the owner sees next is the file as it now stands.
+   *
+   * Every cycle rewrites, even at an unchanged version: directory permissions
+   * are repaired only on a write, so skipping would leave a loosened directory
+   * loose until the next save.
+   */
+  async refetchRuntimeConfig() {
+    const base = `${this.cfg.apiBase}/api/v1/agents/${encodeURIComponent(this.cfg.identityId)}/runtime-config`;
+    try {
+      const res = await this.fetchImpl(`${base}/files`, {
+        headers: { authorization: `Bearer ${this.cfg.apiKey}` }
+      });
+      if (!res.ok) throw new Error(`runtime-config ${res.status}`);
+      const payload = await res.json();
+      if (!payload || !payload.version) {
+        process.stderr.write(
+          `[bridge] runtime config not applied (version ${JSON.stringify(payload?.version ?? null)} \u2014 no saved config)
+`
+        );
+        return;
+      }
+      const skillsJson = payload.skills_json ?? {};
+      writeManagedFiles(this.home, this.cfg.identityId, {
+        ...payload.files ?? {},
+        "skills.json": `${JSON.stringify(skillsJson, null, 2)}
+`
+      });
+      if (payload.memory_prunes?.length) {
+        pruneManagedMemory(this.home, this.cfg.identityId, payload.memory_prunes);
+      }
+      const local = readLocalReport(this.home, this.cfg.identityId);
+      const report = {
+        applied_version: payload.version,
+        paths: checkConfiguredPaths(skillsJson),
+        // Read AFTER the prunes above, so the owner's next view of memory is
+        // the file as it now stands, not the one they just pruned from.
+        memory: readManagedMemory(this.home, this.cfg.identityId),
+        // E13: pass through what the runtime reported. The daemon does not
+        // interpret any of it.
+        local_persona: local?.persona ?? null,
+        // Only the runtime knows whether a search key file is configured — it
+        // is an environment value on that process, invisible to the daemon and
+        // to the backend. The backend needs it to generate a truthful tool
+        // paragraph, so it rides along here.
+        has_search_key: local?.has_search_key ?? false
+      };
+      const posted = await this.fetchImpl(`${base}/report`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.cfg.apiKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(report)
+      });
+      if (!posted.ok) {
+        process.stderr.write(
+          `[bridge] runtime config v${payload.version} written, but reporting it failed (${posted.status}) \u2014 the console will keep showing it as not applied until the next cycle
+`
+        );
+        return;
+      }
+      process.stderr.write(`[bridge] runtime config v${payload.version} applied
+`);
+    } catch (e) {
+      process.stderr.write(
+        `[bridge] runtime config refetch failed: ${e?.message ?? e}
 `
       );
     }
@@ -7914,6 +8126,7 @@ var BridgeAgent = class _BridgeAgent {
     }
     await this.provider.publishKeyPackage();
     await this.refetchVoiceSettings();
+    await this.refetchRuntimeConfig();
     this.startReceivePump();
     if (this.selfHealSweepEnabled) {
       this.bootSweepTimer = setTimeout(
@@ -9398,11 +9611,16 @@ var BridgeAgent = class _BridgeAgent {
           this.pingsReceived++;
           if (ping?.reconnected) {
             process.stderr.write("[bridge] delivery-ping WS (re)connected \u2014 push inbound active\n");
+            await this.refetchRuntimeConfig();
           }
           if (ping?.voiceSettingsChanged) {
             await this.refetchVoiceSettings();
             continue;
           }
+          if (ping?.runtimeConfigChanged) {
+            await this.refetchRuntimeConfig();
+            continue;
+          }
           await this.ingestOnce();
         }
       } catch {
@@ -9840,13 +10058,13 @@ var BridgeAgent = class _BridgeAgent {
 };
 
 // src/config.ts
-import { readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
-import { dirname as dirname2, join as join7 } from "node:path";
+import { readFileSync as readFileSync6, statSync as statSync3 } from "node:fs";
+import { dirname as dirname2, join as join8 } from "node:path";
 var REQUIRED = ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 function loadConfig(opts) {
-  const raw = readFileSync5(opts.credentialPath, "utf8");
+  const raw = readFileSync6(opts.credentialPath, "utf8");
   try {
-    const mode = statSync2(opts.credentialPath).mode & 511;
+    const mode = statSync3(opts.credentialPath).mode & 511;
     if (mode & 63) process.stderr.write(`[bridge] WARNING: credential file ${opts.credentialPath} permission ${mode.toString(8)} is not 0600 \u2014 tighten it (chmod 600).
 `);
   } catch {
@@ -9858,7 +10076,7 @@ function loadConfig(opts) {
     throw new Error("credential file is not valid JSON");
   }
   for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new Error(`credential file missing required field: ${k}`);
-  const storePath = opts.storePath ?? join7(dirname2(opts.credentialPath), "bridge-state.db");
+  const storePath = opts.storePath ?? join8(dirname2(opts.credentialPath), "bridge-state.db");
   const agentName = typeof json2.agent_name === "string" && json2.agent_name ? json2.agent_name : typeof json2.display_name === "string" && json2.display_name ? json2.display_name : void 0;
   const rateLimitCapacity = typeof json2.rate_limit_capacity === "number" ? json2.rate_limit_capacity : 20;
   const rateLimitRefillPerMinute = typeof json2.rate_limit_refill_per_minute === "number" ? json2.rate_limit_refill_per_minute : 20;
@@ -9954,13 +10172,13 @@ import { z as z3 } from "zod";
 
 // src/auth.ts
 import { randomBytes as randomBytes3, timingSafeEqual } from "node:crypto";
-import { existsSync, readFileSync as readFileSync6, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
 function resolveToken(opts) {
   if (opts.token) return opts.token;
   const f = opts.tokenFile;
-  if (f && existsSync(f)) return readFileSync6(f, "utf8").trim();
+  if (f && existsSync2(f)) return readFileSync7(f, "utf8").trim();
   const tok = randomBytes3(32).toString("base64url");
-  if (f) writeFileSync(f, tok, { mode: 384 });
+  if (f) writeFileSync2(f, tok, { mode: 384 });
   return tok;
 }
 function tokenMatches(provided, expected) {

package/dist/service/runtime-config-dir.d.ts

@@ -0,0 +1,44 @@
+export declare const MEMORY_FILE = "MEMORY.md";
+export interface PathCheck {
+    path: string;
+    ok: boolean;
+    why: string;
+}
+export interface FsDeps {
+    mkdir: (p: string, mode: number) => void;
+    chmod: (p: string, mode: number) => void;
+    writeFile: (p: string, data: string, mode: number) => void;
+    rename: (a: string, b: string) => void;
+    readFile: (p: string) => string;
+    unlink: (p: string) => void;
+}
+export declare function runtimeConfigDir(home: string, identityId: string): string;
+export declare function writeManagedFiles(home: string, identityId: string, files: Record<string, string>, deps?: FsDeps): void;
+/** Every path skills.json names, checked on disk. Contents are never read. */
+export declare function checkConfiguredPaths(skillsJson: Record<string, unknown>, statFn?: (p: string) => {
+    mode: number;
+    size: number;
+}): PathCheck[];
+export declare function lineHash(line: string): string;
+export declare const LOCAL_REPORT_FILE = "local-config.json";
+/**
+ * What the runtime says its OWN persona files currently contain (spec E13).
+ *
+ * The runtime writes this; the daemon only reads it. It exists because the
+ * daemon cannot see the runtime's data dir, so without it an owner's
+ * hand-written persona would be invisible in the web app and the first save
+ * would replace it sight unseen. It is inert: nothing here decides behaviour,
+ * and it never affects which file the runtime actually reads.
+ */
+export interface LocalReport {
+    persona: Record<string, string>;
+    has_search_key: boolean;
+}
+export declare function readLocalReport(home: string, identityId: string): LocalReport | null;
+export declare function readManagedMemory(home: string, identityId: string): string | null;
+/**
+ * Remove exactly the named lines. Line-level, never a whole-file replace: the
+ * agent may append a fact between the owner reading and pruning, and that fact
+ * must survive (spec §7).
+ */
+export declare function pruneManagedMemory(home: string, identityId: string, hashes: string[], deps?: FsDeps): number;

package/package.json

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