@securecoms/agent-bridge 0.30.1 → 0.30.3

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 readFileSync15, statSync as statSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { readFileSync as readFileSync16, statSync as statSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join24 } from "node:path";
 async function importModelBundle(srcDir, root3, m) {
   const verified = [];
@@ -7574,7 +7574,7 @@ async function importModelBundle(srcDir, root3, m) {
     if (size !== f.size) throw mismatch;
     let bytes;
     try {
-      bytes = readFileSync15(src);
+      bytes = readFileSync16(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}`));
@@ -29848,7 +29882,7 @@ function loadPackageMeta(importMetaUrl) {
 }
 
 // src/bridge-agent.ts
-import { existsSync as existsSync5, promises as fsp, statSync as statSync5 } from "node:fs";
+import { existsSync as existsSync5, promises as fsp, readFileSync as readFileSync11, statSync as statSync5 } from "node:fs";
 import { join as join19, dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -34363,6 +34397,15 @@ import {
   writeFileSync
 } from "node:fs";
 import { basename as basename4, isAbsolute, join as join18 } from "node:path";
+
+// src/grants/search-providers.ts
+var SEARCH_PROVIDERS = /* @__PURE__ */ new Set(["brave", "tavily", "parallel", "exa", "firecrawl"]);
+var OWNER_DM_SEARCH_DAILY_CAP_MAX = 2e3;
+function isSearchProvider(value) {
+  return typeof value === "string" && SEARCH_PROVIDERS.has(value);
+}
+
+// src/service/runtime-config-dir.ts
 var MEMORY_FILE = "MEMORY.md";
 var REAL_FS = {
   mkdir: (p, mode) => mkdirSync5(p, { recursive: true, mode }),
@@ -34545,10 +34588,14 @@ function readLocalReport(home, identityId) {
   const persona = raw && typeof raw === "object" && !Array.isArray(raw) ? Object.fromEntries(
     Object.entries(raw).filter(([, v]) => typeof v === "string")
   ) : {};
+  const capRaw = doc.owner_dm_search_cap_effective;
+  const ownerDmCap = typeof capRaw === "number" && Number.isInteger(capRaw) && capRaw >= 0 && capRaw <= OWNER_DM_SEARCH_DAILY_CAP_MAX ? capRaw : void 0;
   return {
     persona,
     has_search_key: hasSearchKey,
     has_llm_key: hasLlmKey,
+    has_extract_provider: doc.has_extract_provider === true,
+    ...ownerDmCap !== void 0 ? { owner_dm_search_cap_effective: ownerDmCap } : {},
     legacy_memory: localLegacySources(doc).map(({ path: _path, ...source }) => source),
     secret_paths: parseSecretPathsReport(doc.secret_paths)
   };
@@ -34666,7 +34713,8 @@ import { sha256 as sha25611 } from "@noble/hashes/sha256";
 import { ed25519 as ed255195 } from "@noble/curves/ed25519";
 var TOOL_GRANTS_DOMAIN = "SECURECOMS-TOOL-GRANTS-V1:";
 var MANIFEST_KNOWN_TOOLS = Object.freeze({
-  owner_dm: Object.freeze(["web_search", "fetch_url", "http_request", "sql_query"]),
+  owner_dm: Object.freeze(["web_search", "web_extract", "fetch_url", "http_request", "sql_query"]),
+  // web_extract: owner DM only, never team_room (spec §5.4, D5)
   team_room: Object.freeze(["web_search"])
 });
 function manifestSignedBytes(manifest) {
@@ -34741,7 +34789,11 @@ function parseConfig(v) {
   }
   if ("search" in v) {
     const sr = v.search;
-    if (!isPlainObject(sr) || !exactKeys(sr, ["provider"]) || sr.provider !== "brave" && sr.provider !== "tavily") return null;
+    if (!isPlainObject(sr) || !exactKeys(sr, ["provider"], ["owner_dm_daily_cap"]) || !isSearchProvider(sr.provider)) return null;
+    if ("owner_dm_daily_cap" in sr) {
+      const cap = sr.owner_dm_daily_cap;
+      if (typeof cap !== "number" || !Number.isSafeInteger(cap) || cap < 0 || cap > OWNER_DM_SEARCH_DAILY_CAP_MAX) return null;
+    }
   }
   const mem = v.memory;
   if (!isPlainObject(mem) || !exactKeys(mem, ["mode"], ["recall_days"])) return null;
@@ -34751,7 +34803,12 @@ function parseConfig(v) {
   return Object.freeze({
     persona_sha256: v.persona_sha256,
     ...isPlainObject(v.llm) ? { llm: Object.freeze({ provider: v.llm.provider, model: v.llm.model }) } : {},
-    ...isPlainObject(v.search) ? { search: Object.freeze({ provider: v.search.provider }) } : {},
+    ...isPlainObject(v.search) ? {
+      search: Object.freeze({
+        provider: v.search.provider,
+        ..."owner_dm_daily_cap" in v.search ? { owner_dm_daily_cap: v.search.owner_dm_daily_cap } : {}
+      })
+    } : {},
     ...isStringArray(v.tools_allow) ? { tools_allow: Object.freeze([...v.tools_allow]) } : {},
     flags: Object.freeze([...v.flags]),
     memory: Object.freeze({ mode: mem.mode, ..."recall_days" in mem ? { recall_days: mem.recall_days } : {} }),
@@ -34982,7 +35039,20 @@ function bindTargets(raw, signed, equals) {
   }
   return { written, mismatches };
 }
-function bindRuntimeConfig(manifest, payload, prior, switches = { ownerDm: true, room: true }) {
+function signedManifestTools(manifest, audience, searchProvidersCapable) {
+  return MANIFEST_KNOWN_TOOLS[audience].filter((t) => (manifest.grants[audience] ?? []).includes(t) && (t !== "web_extract" || searchProvidersCapable));
+}
+function manifestPolicyFor(manifest, switches, searchProvidersCapable) {
+  return {
+    v: 1,
+    manifest_tools: [.../* @__PURE__ */ new Set([
+      ...switches.ownerDm ? signedManifestTools(manifest, "owner_dm", searchProvidersCapable) : [],
+      ...switches.room ? signedManifestTools(manifest, "team_room", searchProvidersCapable) : []
+    ])].sort(),
+    secret_path_mode: "enforce"
+  };
+}
+function bindRuntimeConfig(manifest, payload, prior, switches = { ownerDm: true, room: true }, searchProvidersCapable = false) {
   const mismatches = /* @__PURE__ */ new Set();
   const cfg = manifest.config;
   const out = {};
@@ -35011,6 +35081,7 @@ function bindRuntimeConfig(manifest, payload, prior, switches = { ownerDm: true,
   for (const name of Object.keys(files)) {
     if (name !== LLM_SOURCE && !PERSONA_FILES.includes(name)) mismatches.add("files");
   }
+  const ownerDmTools = signedManifestTools(manifest, "owner_dm", searchProvidersCapable);
   const sj = isObj2(payload.skills_json) ? payload.skills_json : void 0;
   const eps = bindTargets(sj?.endpoints, manifest.endpoints, endpointEquals);
   const dbs = bindTargets(sj?.databases, manifest.databases, databaseEquals);
@@ -35028,14 +35099,20 @@ function bindRuntimeConfig(manifest, payload, prior, switches = { ownerDm: true,
     appliedSearch = searchBlock;
   } else {
     mismatches.add("search");
-    searchBlock = (prior.search?.provider ?? void 0) === cfg.search?.provider ? prior.search : void 0;
+    const usablePrior = cfg.search !== void 0 && prior.search?.provider === cfg.search.provider ? prior.search : void 0;
+    searchBlock = cfg.search === void 0 ? void 0 : usablePrior ?? Object.freeze({ provider: cfg.search.provider });
   }
   const skillsDoc = {
     endpoints: eps.written,
     databases: dbs.written,
     flags: [...cfg.flags],
     ...deny !== void 0 || cfg.tools_allow !== void 0 ? { tools: { ...deny !== void 0 ? { deny } : {}, ...cfg.tools_allow !== void 0 ? { allow: [...cfg.tools_allow] } : {} } } : {},
-    ...searchBlock ? { search: searchBlock } : {}
+    ...searchBlock ? { search: searchBlock } : {},
+    // D31: the marker the runtime keys D24 (iii) on; written under every manifest, true when config.search is signed.
+    search_signed: cfg.search !== void 0,
+    // D36, D39: the signed owner-DM cap, only when the owner-DM switch is on and the manifest grants an owner-DM tool;
+    // otherwise none, so the runtime clamps a signed raise to the default. Never read from the payload.
+    ...cfg.search?.owner_dm_daily_cap !== void 0 && switches.ownerDm && ownerDmTools.length > 0 ? { owner_dm_search_cap: cfg.search.owner_dm_daily_cap } : {}
   };
   out["skills.json"] = JSON.stringify(skillsDoc, null, 2) + "\n";
   const signedMemory = { mode: cfg.memory.mode, ...cfg.memory.recall_days !== void 0 ? { recall_days: cfg.memory.recall_days } : {} };
@@ -35066,12 +35143,7 @@ function bindRuntimeConfig(manifest, payload, prior, switches = { ownerDm: true,
     mismatches.add("legacy_assign");
     legacyDecisions = decisions.filter((d) => isObj2(d) && d.action === "delete");
   }
-  const signedTools = (a) => MANIFEST_KNOWN_TOOLS[a].filter((t) => (manifest.grants[a] ?? []).includes(t));
-  const policy = {
-    v: 1,
-    manifest_tools: [.../* @__PURE__ */ new Set([...switches.ownerDm ? signedTools("owner_dm") : [], ...switches.room ? signedTools("team_room") : []])].sort(),
-    secret_path_mode: "enforce"
-  };
+  const policy = manifestPolicyFor(manifest, switches, searchProvidersCapable);
   return {
     mismatches: CONFIG_BINDING_FIELDS.filter((f) => mismatches.has(f)).sort(),
     targetMismatches: { endpoint: eps.mismatches, database: dbs.mismatches },
@@ -35210,6 +35282,8 @@ var TOOL_ROOM_CLASSES = Object.freeze({
   current_time: Object.freeze(["room_safe_read"]),
   echo: Object.freeze(["room_safe_read"]),
   web_search: Object.freeze(["owner_credential"]),
+  web_extract: Object.freeze(["owner_credential", "egress"]),
+  // D5: spends the owner's key and sends URLs out
   fetch_url: Object.freeze(["egress"]),
   sql_query: Object.freeze(["owner_credential"]),
   http_request: Object.freeze(["owner_credential", "egress", "side_effect"])
@@ -35631,6 +35705,8 @@ function hexToBytes4(h) {
   return new Uint8Array(Buffer.from(h, "hex"));
 }
 var BOOT_DRAIN_WAIT_MS_DEFAULT = 6e4;
+var SEARCH_CAPABILITY_REFETCH_DEBOUNCE_MS = 1e3;
+var SEARCH_CAPABILITY_REFETCH_MAX_WAIT_MS = 1e4;
 var BootDrainRotationRefusedError = class extends Error {
   constructor() {
     super("key-package rotation refused: the boot drain has not settled");
@@ -35826,6 +35902,8 @@ var BridgeAgent = class _BridgeAgent {
     this.actionClock = deps.actionThrottleNow ?? Date.now;
     this.rng = deps.rng ?? Math.random;
     this.bootDrainWaitMs = deps.bootDrainWaitMs ?? BOOT_DRAIN_WAIT_MS_DEFAULT;
+    this.searchCapabilityRefetchDebounceMs = deps.searchCapabilityRefetchDebounceMs ?? SEARCH_CAPABILITY_REFETCH_DEBOUNCE_MS;
+    this.searchCapabilityRefetchMaxWaitMs = deps.searchCapabilityRefetchMaxWaitMs ?? SEARCH_CAPABILITY_REFETCH_MAX_WAIT_MS;
     this.replySleep = deps.replySleep ?? ((ms) => new Promise((resolve4) => {
       const t = setTimeout(resolve4, ms);
       t.unref?.();
@@ -36264,6 +36342,8 @@ var BridgeAgent = class _BridgeAgent {
   bootSweepTimer;
   rng;
   bootDrainWaitMs;
+  searchCapabilityRefetchDebounceMs;
+  searchCapabilityRefetchMaxWaitMs;
   /** Resolved (and cleared) each time an ingest cycle settles: see start(). */
   ingestSettledWaiters = [];
   /** The boot key-package publish, when start() had to defer it. Test seam. */
@@ -36709,9 +36789,14 @@ var BridgeAgent = class _BridgeAgent {
       }
       const skillsJson = payload.skills_json ?? {};
       if (version && inForce === null) {
+        let asDelivered = skillsJson;
+        if (skillsJson !== null && typeof skillsJson === "object" && !Array.isArray(skillsJson)) {
+          const { owner_dm_search_cap: _cap, search_signed: _signed, ...rest } = skillsJson;
+          asDelivered = rest;
+        }
         this.grantWriters.writeManagedFiles(this.home, this.cfg.identityId, {
           ...payload.files ?? {},
-          "skills.json": `${JSON.stringify(skillsJson, null, 2)}
+          "skills.json": `${JSON.stringify(asDelivered, null, 2)}
 `
         });
       }
@@ -36766,7 +36851,7 @@ var BridgeAgent = class _BridgeAgent {
     }
     let bound;
     try {
-      bound = this.grantWriters.bindRuntimeConfig(manifest, payload, { search: prior }, { ownerDm: this.ownerDmManifestGrants, room: this.roomManifestGrants });
+      bound = this.grantWriters.bindRuntimeConfig(manifest, payload, { search: prior }, { ownerDm: this.ownerDmManifestGrants, room: this.roomManifestGrants }, this.searchProvidersCapable());
     } catch (e) {
       bound = null;
       return this.bindFailed(manifest, payload.memory, e);
@@ -36785,9 +36870,9 @@ var BridgeAgent = class _BridgeAgent {
       return true;
     }
     try {
-      this.grantWriters.writeManifestPolicy(this.home, this.cfg.identityId, bound.policy);
       this.grantWriters.writeManagedFiles(this.home, this.cfg.identityId, bound.files);
       if (manifest.config.llm === void 0) this.grantWriters.removeManagedLlmSource(this.home, this.cfg.identityId);
+      this.grantWriters.writeManifestPolicy(this.home, this.cfg.identityId, manifestPolicyFor(manifest, { ownerDm: this.ownerDmManifestGrants, room: this.roomManifestGrants }, this.searchProvidersCapable()));
     } catch (e) {
       this.manifestBinding = null;
       throw e;
@@ -36840,6 +36925,7 @@ var BridgeAgent = class _BridgeAgent {
   /** The report half of refetchRuntimeConfigOnce (split out for the plan 4 Task 11 bind_failed path). */
   async postRuntimeConfigReport(base, version, skillsJson) {
     const local = readLocalReport(this.home, this.cfg.identityId);
+    const reportedSearchProviders = this.searchProvidersCapable();
     const report = {
       applied_version: version,
       paths: checkConfiguredPaths(skillsJson),
@@ -36854,6 +36940,13 @@ var BridgeAgent = class _BridgeAgent {
       // 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,
+      // L-2 (spec §7.9): only the runtime knows whether an extract-capable provider key is readable; never derived
+      // from has_search_key. An older runtime omits it: false.
+      // Final review I-2 (controller ruling): AND the current search_providers_v2, so the web never shows extract while
+      // the bridge withholds web_extract from the runtime.
+      has_extract_provider: (local?.has_extract_provider ?? false) && reportedSearchProviders,
+      // D39: the owner-DM daily cap the runtime enforces, passed through when it reported a valid one; never the signed value.
+      ...local?.owner_dm_search_cap_effective !== void 0 ? { owner_dm_search_cap_effective: local.owner_dm_search_cap_effective } : {},
       // Same idea, for the BYOK LLM key file: only the runtime can see
       // whether one is configured in its own environment.
       has_llm_key: local?.has_llm_key ?? false,
@@ -36893,7 +36986,11 @@ var BridgeAgent = class _BridgeAgent {
         // Plan 4 Task 15 (OQ-5): sorted, unique enums; capability is the latest hello's class.
         config_binding_mismatches: [...this.configBindingMismatches],
         target_mismatches: ["database", "endpoint"].filter((k) => this.targetMismatches[k] > 0),
-        capability: this.lastConsumerCapability
+        capability: this.lastConsumerCapability,
+        // D28 (§11.1 step 3): a separate key, never a value in the capability enum. False with no runtime attached.
+        search_providers_v2: reportedSearchProviders,
+        // D19 item 4: content-free; the signed provider is one the attached runtime(s) cannot honour.
+        search_provider_unsupported: this.searchProviderUnsupported(reportedSearchProviders)
       }
     };
     const reportedVerifyFailures = this.ownerVerifyFailures;
@@ -36914,6 +37011,7 @@ var BridgeAgent = class _BridgeAgent {
       return;
     }
     this.ownerVerifyFailures = Math.max(0, this.ownerVerifyFailures - reportedVerifyFailures);
+    this.lastReportedSearchProviders = reportedSearchProviders;
     if (version) writeServiceLog("info", "runtime_config.applied", { version });
     else writeServiceLog("info", "runtime_config.legacy_memory_reported");
   }
@@ -36983,6 +37081,7 @@ var BridgeAgent = class _BridgeAgent {
     this.startedAt = Date.now();
     await this.restoreRuntimeInbox();
     await this.loadToolGrantState();
+    this.recomputeManifestPolicy(false);
     try {
       this.store.pruneRoomSearchCap(utcDayOf(Date.now()));
     } catch (e) {
@@ -42774,6 +42873,115 @@ ${channelId}`;
   manifestConsumerAttached() {
     return this.manifestConsumer !== null;
   }
+  /**
+   * D28 (B-4): every socket that said hello, with whether its latest hello declared search_providers_v2 on the
+   * manifest_grants_v1 predicate (ws-server.ts). The agent value is the AND over all of them, absent (false) with
+   * none: unlike manifestConsumer, never newest wins. The per-delivery filter judges each socket by its own hello.
+   */
+  searchProvidersSockets = /* @__PURE__ */ new Map();
+  /**
+   * The D28 value the files were last recomputed for; null until the first socket observation, so that observation
+   * always recomputes (final review I-1), even when it is non-capable.
+   */
+  searchProvidersState = null;
+  searchCapabilityRefetchTimer = null;
+  /** When the current burst's first change happened (valid while the timer is set). */
+  searchCapabilityBurstStart = 0;
+  /** The D28 value in the last report posted (null until one is); a change needs a refetch to reach the web. */
+  lastReportedSearchProviders = null;
+  noteSearchProvidersSocket(token, declared) {
+    this.searchProvidersSockets.set(token, declared);
+    this.onSearchProvidersMaybeChanged();
+  }
+  clearSearchProvidersSocket(token) {
+    if (this.searchProvidersSockets.delete(token)) this.onSearchProvidersMaybeChanged();
+  }
+  /** D28: every attached runtime socket declared search_providers_v2; no socket attached means absent (false). */
+  searchProvidersCapable() {
+    if (this.searchProvidersSockets.size === 0) return false;
+    for (const v of this.searchProvidersSockets.values()) if (!v) return false;
+    return true;
+  }
+  /**
+   * D19 item 3 (B-6): the search provider signed in the stored verified manifest in force (a pin loaded and a good
+   * manifest), never the server payload; undefined with no pin, no manifest, or no signed search block. The
+   * per-delivery filter (consumer-grants.ts withSearchCapability) and the S-28 report reason both read this.
+   */
+  signedSearchProvider() {
+    const pin = this.cfg.ownerGrantPin?.pin ?? null;
+    return pin !== null ? this.toolGrantManifest?.config.search?.provider : void 0;
+  }
+  /** D19 item 4, D34: the in-force signed provider is not brave, and the attached runtime(s) lack the capability. */
+  searchProviderUnsupported(capable) {
+    if (capable) return false;
+    const provider = this.signedSearchProvider();
+    return provider !== void 0 && provider !== "brave";
+  }
+  /**
+   * D35 (P-4): on a capability change, rewrite manifest-policy.json at once from the stored manifest, the kill
+   * switches and the new capability, then a debounced refetch (one per burst) only when needed.
+   */
+  onSearchProvidersMaybeChanged() {
+    const capable = this.searchProvidersCapable();
+    const prev = this.searchProvidersState;
+    if (capable === prev) return;
+    this.searchProvidersState = capable;
+    this.recomputeManifestPolicy(capable);
+    if (this.closingDown) return;
+    if (prev === null && !capable) return;
+    const now = Date.now();
+    if (this.searchCapabilityRefetchTimer !== null) clearTimeout(this.searchCapabilityRefetchTimer);
+    else this.searchCapabilityBurstStart = now;
+    const delay = Math.max(0, Math.min(this.searchCapabilityRefetchDebounceMs, this.searchCapabilityBurstStart + this.searchCapabilityRefetchMaxWaitMs - now));
+    this.searchCapabilityRefetchTimer = setTimeout(() => {
+      this.searchCapabilityRefetchTimer = null;
+      if (this.searchCapabilityRefetchNeeded()) void this.refetchRuntimeConfig();
+    }, delay);
+    this.searchCapabilityRefetchTimer.unref?.();
+  }
+  /**
+   * A refetch re-renders skills.json (owner_dm_search_cap counts web_extract only with the capability, D39) and posts
+   * the report. Needed under a manifest in force, or when the reported value is stale. Never before the boot fetch.
+   */
+  searchCapabilityRefetchNeeded() {
+    if (!this.bootConfigSettled || this.closingDown) return false;
+    const inForce = (this.cfg.ownerGrantPin?.pin ?? null) !== null && this.toolGrantManifest !== null;
+    return inForce || this.lastReportedSearchProviders !== this.searchProvidersCapable();
+  }
+  /**
+   * D35: the local recompute. Widening (web_extract back in) only while the binding for the in-force manifest stands,
+   * so a policy is never written ahead of its skills.json. Narrowing never waits: with no binding in force, a file that
+   * lists web_extract loses it at once, so an older runtime never reads it as unreadable (which drops every grant).
+   * Content-free; a write failure is logged and the debounced refetch tries again.
+   */
+  recomputeManifestPolicy(capable) {
+    const pin = this.cfg.ownerGrantPin?.pin ?? null;
+    const manifest = pin !== null ? this.toolGrantManifest : null;
+    try {
+      if (manifest !== null && this.manifestBinding !== null && this.manifestBinding.counter === manifest.counter) {
+        this.grantWriters.writeManifestPolicy(this.home, this.cfg.identityId, manifestPolicyFor(manifest, { ownerDm: this.ownerDmManifestGrants, room: this.roomManifestGrants }, capable));
+        return;
+      }
+      if (capable) return;
+      const path = join19(runtimeConfigDir(this.home, this.cfg.identityId), MANIFEST_POLICY_FILE);
+      if (!existsSync5(path)) return;
+      let doc;
+      try {
+        doc = JSON.parse(readFileSync11(path, "utf8"));
+      } catch {
+        return;
+      }
+      const tools = doc?.manifest_tools;
+      if (!Array.isArray(tools) || !tools.includes("web_extract")) return;
+      this.grantWriters.writeManifestPolicy(this.home, this.cfg.identityId, {
+        v: 1,
+        manifest_tools: tools.filter((t) => typeof t === "string" && t !== "web_extract"),
+        secret_path_mode: "enforce"
+      });
+    } catch (e) {
+      writeServiceLog("warn", "authz.search_capability", { state: ServiceLogEnum.of("policy_write_failed", ["policy_write_failed"]) }, e);
+    }
+  }
   noteConsumerCapability(state) {
     this.lastConsumerCapability = state;
     if (state !== "ok") {
@@ -42965,6 +43173,8 @@ ${channelId}`;
     this.supersedeRecheckTimers.clear();
     if (this.redeliveryTimer !== null) clearTimeout(this.redeliveryTimer);
     this.redeliveryTimer = null;
+    if (this.searchCapabilityRefetchTimer !== null) clearTimeout(this.searchCapabilityRefetchTimer);
+    this.searchCapabilityRefetchTimer = null;
     this.pingHandle?.close();
     if (this.safetyTimer) clearInterval(this.safetyTimer);
     if (this.runtimeConfigTimer) clearInterval(this.runtimeConfigTimer);
@@ -43075,11 +43285,11 @@ ${channelId}`;
 
 // src/auth.ts
 import { randomBytes as randomBytes11, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
-import { existsSync as existsSync6, readFileSync as readFileSync11, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync12, writeFileSync as writeFileSync2 } from "node:fs";
 function resolveToken(opts) {
   if (opts.token) return opts.token;
   const f = opts.tokenFile;
-  if (f && existsSync6(f)) return readFileSync11(f, "utf8").trim();
+  if (f && existsSync6(f)) return readFileSync12(f, "utf8").trim();
   const tok = randomBytes11(32).toString("base64url");
   if (f) writeFileSync2(f, tok, { mode: 384 });
   return tok;
@@ -43180,6 +43390,7 @@ function withConsumerGrants(m, perToolConsumer) {
   return { ...m, authorization: Object.freeze({ ...rest, ...stripGrants ? { tool_grants: NO_GRANTS } : {} }) };
 }
 var MANIFEST_GRANTS_FEATURE = "manifest_grants_v1";
+var SEARCH_PROVIDERS_FEATURE = "search_providers_v2";
 var CONSTANT_TOOL_NAMES = Object.freeze({
   owner_dm: Object.freeze(["current_time", "web_search"]),
   team_room: Object.freeze(["current_time"])
@@ -43202,6 +43413,15 @@ function withHarnessGrants(m, withheld) {
   if (!a || a.tool_grants.length === 0) return m;
   return { ...m, authorization: Object.freeze({ ...a, tool_grants: NO_GRANTS }) };
 }
+function withSearchCapability(m, consumerHasFeature, signedProvider) {
+  if (consumerHasFeature) return m;
+  const a = m.authorization;
+  if (!a) return m;
+  const stripSearch = signedProvider !== void 0 && signedProvider !== "brave";
+  const kept = a.tool_grants.filter((g) => g.tool !== "web_extract" && !(stripSearch && g.tool === "web_search"));
+  if (kept.length === a.tool_grants.length) return m;
+  return { ...m, authorization: Object.freeze({ ...a, tool_grants: kept.length === 0 ? NO_GRANTS : Object.freeze(kept) }) };
+}
 
 // src/http-server.ts
 function writeSse(res, msgs, onWriteError) {
@@ -43224,7 +43444,8 @@ data: ${JSON.stringify(msgs[i])}
 }
 function deliverSseBatch(res, batch, agent, onWriteError) {
   const withheld = agent.harnessGrantsWithheld();
-  const left3 = writeSse(res, batch.map((m) => withManifestCapability(withHarnessGrants(withConsumerGrants(m, false), withheld), false)), onWriteError);
+  const provider = agent.signedSearchProvider();
+  const left3 = writeSse(res, batch.map((m) => withSearchCapability(withManifestCapability(withHarnessGrants(withConsumerGrants(m, false), withheld), false), false, provider)), onWriteError);
   const leftIds = new Set(left3.map((message) => message.message_id));
   agent.ackRuntimeMessages(batch.filter((message) => !leftIds.has(message.message_id)).map((message) => message.message_id));
   if (left3.length) agent.requeueFront(batch.filter((message) => leftIds.has(message.message_id)));
@@ -43495,7 +43716,10 @@ function createHttpServer(agent, opts) {
       if (method === "GET" && path === "/v1/messages") {
         const channel = url.searchParams.get("channel_id") ?? void 0;
         const wait = Math.max(0, Math.min(50, Number(url.searchParams.get("wait") ?? 0)));
-        return json(res, 200, (await agent.drain(channel, wait)).map((m) => withManifestCapability(withHarnessGrants(withConsumerGrants(m, false), agent.harnessGrantsWithheld()), false)));
+        const drained = await agent.drain(channel, wait);
+        const withheld = agent.harnessGrantsWithheld();
+        const provider = agent.signedSearchProvider();
+        return json(res, 200, drained.map((m) => withSearchCapability(withManifestCapability(withHarnessGrants(withConsumerGrants(m, false), withheld), false), false, provider)));
       }
       if (method === "GET" && path === "/v1/events") {
         const channel = url.searchParams.get("channel_id") ?? void 0;
@@ -43669,6 +43893,7 @@ function attachAgentWebSocket(server, agent, opts) {
       consumer: "unknown",
       perToolGrants: false,
       manifestGrants: false,
+      searchProviders: false,
       // helloWaitMs 0 keeps today's synchronous initial flush exactly (the opt-out the existing tests use).
       deliveryOpen: helloWaitMs <= 0,
       deliveryToken: /* @__PURE__ */ new Map(),
@@ -43722,9 +43947,13 @@ function attachAgentWebSocket(server, agent, opts) {
             continue;
           }
           const out = withConsumerNotes(
-            withManifestCapability(
-              withHarnessGrants(withConsumerGrants(batch[i], session.perToolGrants), !session.perToolGrants && agent.harnessGrantsWithheld()),
-              session.manifestGrants
+            withSearchCapability(
+              withManifestCapability(
+                withHarnessGrants(withConsumerGrants(batch[i], session.perToolGrants), !session.perToolGrants && agent.harnessGrantsWithheld()),
+                session.manifestGrants
+              ),
+              session.searchProviders,
+              agent.signedSearchProvider()
             ),
             batch[i],
             session,
@@ -43760,6 +43989,7 @@ function attachAgentWebSocket(server, agent, opts) {
     const cleanup = () => {
       if (cleaned) return;
       cleaned = true;
+      session.closed = true;
       if (helloTimer) clearTimeout(helloTimer);
       agent.noteSessionClose();
       unsubscribe();
@@ -43780,6 +44010,7 @@ function attachAgentWebSocket(server, agent, opts) {
       if (session.harness) agent.clearHarnessReport(session.harness);
       if (session.perToolGrants) agent.clearPerToolConsumer(session);
       if (session.manifestGrants) agent.clearManifestConsumer(session);
+      agent.clearSearchProvidersSocket(session);
     };
     current = { sock, cleanup, sweepStale };
     sock.on("close", cleanup);
@@ -43855,6 +44086,7 @@ async function handleInbound(sock, agent, data, inflight, flush, session) {
     return;
   }
   if (m.type === "hello") {
+    if (session.closed) return;
     const report = m.harness === void 0 ? null : parseHarnessReport(m.harness);
     if (report) {
       session.harness = report;
@@ -43878,6 +44110,8 @@ async function handleInbound(sock, agent, data, inflight, flush, session) {
       agent.clearManifestConsumer(session);
     }
     agent.noteConsumerCapability(manifest ? "ok" : session.harnessClaimed ? "harness_consumer" : "missing");
+    session.searchProviders = session.consumer === "runtime" && session.harnessClaimed !== true && perTool && Array.isArray(m.features) && m.features.includes(SEARCH_PROVIDERS_FEATURE);
+    agent.noteSearchProvidersSocket(session, session.searchProviders);
     if (session.consumer === "runtime" && session.harnessClaimed !== true && Array.isArray(m.features) && m.features.includes(MEMORY_NOTES_FEATURE)) {
       agent.noteNotesConsumer();
     }
@@ -43885,7 +44119,7 @@ async function handleInbound(sock, agent, data, inflight, flush, session) {
     if (session.recallConsumer) agent.noteRecallConsumer();
     session.unifiedConsumer = agent.unifiedFeatureOn() && session.consumer === "runtime" && session.harnessClaimed !== true && Array.isArray(m.features) && m.features.includes(MEMORY_UNIFIED_FEATURE);
     if (session.unifiedConsumer) agent.noteUnifiedConsumer();
-    sendJson(sock, { type: "hello", features: ["nack", MEMORY_NOTES_FEATURE, MEMORY_RECALL_FEATURE, ...agent.unifiedFeatureOn() ? [MEMORY_UNIFIED_FEATURE] : [], MANIFEST_GRANTS_FEATURE] });
+    sendJson(sock, { type: "hello", features: ["nack", MEMORY_NOTES_FEATURE, MEMORY_RECALL_FEATURE, ...agent.unifiedFeatureOn() ? [MEMORY_UNIFIED_FEATURE] : [], MANIFEST_GRANTS_FEATURE, SEARCH_PROVIDERS_FEATURE] });
     if (!session.deliveryOpen) {
       session.deliveryOpen = true;
       flush();
@@ -44111,7 +44345,7 @@ 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 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 { readFileSync as readFileSync17, 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";
@@ -44197,7 +44431,7 @@ function slugify(s) {
 function deriveServiceConfig(input) {
   if (isVersionEmbeddedNodePath(input.execPath)) {
     throw new Error(
-      `install: refusing to bake a version-embedded Node path into the service definition: ${input.execPath}. Re-run install under a system/Homebrew Node, or pass --exec-path <stable-path>.`
+      `The Node at ${input.execPath} moves when it is upgraded, so the background service can't use it. Install Node ${REQUIRED_NODE_MAJOR} from https://nodejs.org, then run the install command again.`
     );
   }
   const stem = input.label ?? basename5(input.credentialPath, extname(input.credentialPath));
@@ -44278,6 +44512,26 @@ WantedBy=default.target
 // src/service/install.ts
 var ServiceUnsupportedError = class extends Error {
 };
+var PREVIOUS_EXIT_WAIT_MS = 1e4;
+var PREVIOUS_EXIT_POLL_MS = 100;
+function launchdPid(deps, target) {
+  const r = deps.run("launchctl", ["print", target]);
+  if (r.status !== 0) return void 0;
+  const m = /^\s*pid = (\d+)\s*$/m.exec(r.stdout);
+  const pid = m ? Number(m[1]) : NaN;
+  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+}
+function waitForPreviousExit(deps, pid) {
+  const deadline = deps.now() + PREVIOUS_EXIT_WAIT_MS;
+  while (deps.pidAlive(pid)) {
+    if (deps.now() >= deadline) {
+      throw new Error(
+        `the previous bridge (pid ${pid}) did not exit within ${PREVIOUS_EXIT_WAIT_MS / 1e3} s of launchctl bootout, so a new copy would find the instance lock held and stay down. Wait for that process to exit (check with: ps -p ${pid}), then run install again.`
+      );
+    }
+    deps.sleepMs(PREVIOUS_EXIT_POLL_MS);
+  }
+}
 function tokenHint(input) {
   return `${dirname8(input.credentialPath)}/bridge-token`;
 }
@@ -44290,7 +44544,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");
@@ -44301,7 +44558,8 @@ function installService(input, deps) {
     deps.writeFile(cfg.unitPath, renderSystemdUnit(cfg));
     deps.run("systemctl", ["--user", "daemon-reload"]);
     deps.run("loginctl", ["enable-linger", deps.user]);
-    requireOk(deps.run("systemctl", ["--user", "enable", "--now", cfg.unitName]), "systemctl --user enable --now");
+    requireOk(deps.run("systemctl", ["--user", "enable", cfg.unitName]), "systemctl --user enable");
+    requireOk(deps.run("systemctl", ["--user", "restart", cfg.unitName]), "systemctl --user restart");
     return { label: cfg.unitName, filePath: cfg.unitPath, logHint: `journalctl --user -u ${cfg.unitName} -f`, tokenHint: tokenHint(input) };
   }
   throw new ServiceUnsupportedError(`Service install isn't supported on ${deps.platform} yet. Run the agent in a terminal, or use a process manager.`);
@@ -45050,7 +45308,7 @@ function renderStatusTable(rows) {
 import {
   chmodSync as chmodSync5,
   mkdirSync as mkdirSync6,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync as renameSync4,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync3
@@ -45062,7 +45320,7 @@ var REAL_FS2 = {
   chmod: (p, mode) => chmodSync5(p, mode),
   writeFile: (p, data, mode) => writeFileSync3(p, data, { mode }),
   rename: (a, b) => renameSync4(a, b),
-  readFile: (p) => readFileSync12(p, "utf8"),
+  readFile: (p) => readFileSync13(p, "utf8"),
   unlink: (p) => unlinkSync2(p)
 };
 function securecomsDir(home) {
@@ -45111,7 +45369,7 @@ 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 { closeSync as closeSync4, fsyncSync, mkdirSync as mkdirSync7, openSync as openSync4, readFileSync as readFileSync14, 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;
@@ -45125,7 +45383,7 @@ function errno(error) {
 }
 function readTrimmed(path) {
   try {
-    const v = readFileSync13(path, "utf8").trim();
+    const v = readFileSync14(path, "utf8").trim();
     return v === "" ? void 0 : v;
   } catch {
     return void 0;
@@ -45240,7 +45498,7 @@ var InstanceLock = class {
     if (!this.held) return false;
     let current;
     try {
-      current = readFileSync13(this.path, "utf8");
+      current = readFileSync14(this.path, "utf8");
     } catch {
       current = void 0;
     }
@@ -45258,7 +45516,7 @@ var InstanceLock = class {
     let ageMs;
     this.env.beforeLockRead?.();
     try {
-      raw = readFileSync13(this.path, "utf8");
+      raw = readFileSync14(this.path, "utf8");
       ageMs = Date.now() - statSync6(this.path).mtimeMs;
     } catch (error) {
       if (errno(error) === "ENOENT") {
@@ -45299,7 +45557,7 @@ var InstanceLock = class {
     const written = this.written;
     this.drop();
     try {
-      if (written !== void 0 && readFileSync13(this.path, "utf8") === written) unlinkSync3(this.path);
+      if (written !== void 0 && readFileSync14(this.path, "utf8") === written) unlinkSync3(this.path);
     } catch {
     }
   }
@@ -45313,7 +45571,7 @@ var InstanceLock = class {
   took() {
     this.held = true;
     try {
-      this.written = readFileSync13(this.path, "utf8");
+      this.written = readFileSync14(this.path, "utf8");
     } catch {
       this.written = void 0;
     }
@@ -45395,7 +45653,7 @@ var InstanceLock = class {
       this.env.beforeTakeoverReread?.();
       let current;
       try {
-        current = readFileSync13(this.path, "utf8");
+        current = readFileSync14(this.path, "utf8");
       } catch {
         current = void 0;
       }
@@ -45409,7 +45667,7 @@ var InstanceLock = class {
       if (created !== "created") {
         if (created === "failed") return "failed";
         try {
-          this.holderPid = parseBody(readFileSync13(this.path, "utf8"))?.pid;
+          this.holderPid = parseBody(readFileSync14(this.path, "utf8"))?.pid;
         } catch {
         }
         return "held";
@@ -45435,7 +45693,7 @@ import {
   fsyncSync as fsyncSync2,
   lstatSync as lstatSync8,
   openSync as openSync5,
-  readFileSync as readFileSync14,
+  readFileSync as readFileSync15,
   realpathSync as realpathSync2,
   renameSync as renameSync5,
   unlinkSync as unlinkSync4,
@@ -45472,7 +45730,7 @@ function isSymlink(path) {
   }
 }
 function readJson(path) {
-  return JSON.parse(readFileSync14(path, "utf8"));
+  return JSON.parse(readFileSync15(path, "utf8"));
 }
 function publicKeyOf(v) {
   const r = parsePinObject(v);
@@ -45617,6 +45875,20 @@ function runPinCli(argv, io) {
   return 1;
 }
 
+// src/service/credential-arg.ts
+function readCredentialArg(argv, env) {
+  const i = argv.indexOf("--credential");
+  if (i >= 0) {
+    const v = argv[i + 1];
+    return v ? { kind: "path", path: v } : { kind: "empty_flag" };
+  }
+  const fromEnv = env.SECURECOMS_CREDENTIAL;
+  return fromEnv ? { kind: "path", path: fromEnv } : { kind: "absent" };
+}
+function noCredentialLine(verb) {
+  return verb === "run" ? "No key file was given. If you used the copied run command, no key file for this agent was found in your Downloads folder." : "No key file was found in your Downloads folder. Download the key file again from SecureComs, or add --credential <path>.";
+}
+
 // src/bin.ts
 function nodeMajorOk(version) {
   return Number(version.split(".")[0]) >= 24;
@@ -45653,15 +45925,22 @@ function realServiceDeps() {
     removeFile: (p) => rmSync8(p, { force: true }),
     mkdirp: (p) => mkdirSync8(p, { recursive: true }),
     fileExists: (p) => existsSync7(p),
-    user: userInfo().username
+    user: userInfo().username,
+    pidAlive: pidAliveByKill,
+    // installService is synchronous; Atomics.wait is a real blocking sleep.
+    sleepMs: (ms) => {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    },
+    now: () => Date.now()
   };
 }
 function chooseInstallExecPath(runningExecPath, override, deps) {
   if (override) return override;
   const r = resolveStableNodePath(runningExecPath, deps);
   if (!r.stable) {
+    const list = STABLE_LOCATIONS.slice(0, -1).join(", ") + " or " + STABLE_LOCATIONS[STABLE_LOCATIONS.length - 1];
     throw new Error(
-      "install: no reboot-stable Node found. Version-manager Nodes (nvm/asdf/fnm/volta/n) are removed on upgrade and will break the daemon after a reboot. Install a system Node (nodejs.org pkg \u2192 /usr/local/bin/node) or pass --exec-path <stable-path> to override."
+      "The agent's background service needs Node " + REQUIRED_NODE_MAJOR + " or newer at a fixed location (" + list + "), and none was found. Node from nvm, fnm and similar tools moves when it is upgraded, so it is not used. Install Node " + REQUIRED_NODE_MAJOR + " from https://nodejs.org, then run the install command again."
     );
   }
   return r.path;
@@ -45695,7 +45974,7 @@ function realResolveDeps() {
 }
 function realPrepDeps() {
   return {
-    readFile: (p) => readFileSync16(p, "utf8"),
+    readFile: (p) => readFileSync17(p, "utf8"),
     writeFileMode: (p, data, mode) => writeFileSync5(p, data, { mode }),
     mkdirp: (p, mode) => {
       mkdirSync8(p, { recursive: true, mode: mode ?? 493 });
@@ -45748,7 +46027,7 @@ function realReadFleet() {
         return [];
       }
     },
-    readFile: (p) => readFileSync16(p, "utf8")
+    readFile: (p) => readFileSync17(p, "utf8")
   });
 }
 function runStatus() {
@@ -45773,7 +46052,7 @@ function realCopyConnector(srcDir, dstDir, harness) {
     }
     if (name.includes(".test.")) continue;
     if (!allowedExt.some((ext) => name.endsWith(ext))) continue;
-    writeFileSync5(join25(dstDir, name), readFileSync16(srcPath));
+    writeFileSync5(join25(dstDir, name), readFileSync17(srcPath));
   }
 }
 function realWriteBinding(dstDir, identityId) {
@@ -45782,7 +46061,7 @@ function realWriteBinding(dstDir, identityId) {
 }
 function realReadBinding(dstDir) {
   try {
-    const parsed = JSON.parse(readFileSync16(join25(dstDir, "securecoms.binding.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync17(join25(dstDir, "securecoms.binding.json"), "utf8"));
     return parsed.identity_id ?? null;
   } catch {
     return null;
@@ -45800,7 +46079,7 @@ function realStatDir(p) {
 }
 function realReadHermesConfig(p) {
   try {
-    return readFileSync16(p, "utf8");
+    return readFileSync17(p, "utf8");
   } catch {
     return null;
   }
@@ -45841,9 +46120,17 @@ function runWireVerb(verb) {
   process.exit(verb === "wire" ? runWire(realWireDeps()) : runUnwire(realWireDeps()));
 }
 async function runServiceVerb(verb) {
-  const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
+  let credentialPath;
+  if (verb === "install") {
+    const cred = readCredentialArg(process.argv, process.env);
+    credentialPath = cred.kind === "path" ? cred.path : void 0;
+  } else {
+    credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
+  }
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
   if (verb === "install" ? !credentialPath : !credentialPath && !label) {
+    if (verb === "install") process.stderr.write(`${noCredentialLine("install")}
+`);
     const execPathUsage = verb === "install" ? " [--exec-path <path>]" : "";
     process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|universal]${execPathUsage}
 `);
@@ -45966,6 +46253,26 @@ var HELD_POLL_TOTAL_MS = 1e4;
 var HELD_POLL_INTERVAL_MS = 500;
 var HELD_NO_PID_REACQUIRES = 3;
 var SHUTDOWN_HARD_EXIT_MS = 8e3;
+function configErrorLine(reason, o) {
+  const at = o.isTTY ? ` at ${o.path}` : "";
+  switch (reason) {
+    case "credential_not_found":
+      return `Can't find the key file${at}. Check the path after --credential.`;
+    case "credential_unreadable":
+      return `Can't open the key file${at}. Check that it exists and that your user can read it.`;
+    case "credential_not_json":
+    case "identity_id_invalid":
+      return `The key file${at} is damaged. Get a new key file from the agent's page in SecureComs.`;
+    case "credential_missing_field":
+      return `The key file${at} is incomplete (no ${o.field}). Get a new key file from the agent's page in SecureComs.`;
+    case "credential_voice_invalid":
+      return o.source === "env" ? "The voice settings in this computer's environment are not valid." : `The voice settings in the key file${at} are not valid.`;
+    case "bind_refused":
+      return "The Connector only accepts connections from this computer unless TLS is set. Remove --bind, or add --tls-cert and --tls-key.";
+    case "unknown":
+      return void 0;
+  }
+}
 function realRunModeDeps(credentialPath, storePath) {
   return {
     credentialPath,
@@ -45996,22 +46303,56 @@ function realRunModeDeps(credentialPath, storePath) {
       process.stderr.write(`${line}
 `);
     },
+    isTTY: process.stderr.isTTY === true,
     log: writeServiceLog
   };
 }
 async function runMode(deps) {
   const { credentialPath, storePath, log } = deps;
+  const refuse2 = (reason, extra, e) => {
+    const fields = {
+      reason: ServiceLogEnum.of(reason, [
+        "credential_not_found",
+        "credential_unreadable",
+        "credential_not_json",
+        "credential_missing_field",
+        "credential_voice_invalid",
+        "identity_id_invalid",
+        "bind_refused",
+        "unknown"
+      ])
+    };
+    if (extra.field) {
+      fields.field = ServiceLogEnum.of(extra.field, [
+        "api_key",
+        "identity_id",
+        "device_id",
+        "signing_private_key",
+        "enclave_id",
+        "api_base"
+      ]);
+    }
+    log("error", "startup.config_invalid", fields, e);
+    const line = configErrorLine(reason, { path: credentialPath, isTTY: deps.isTTY, ...extra });
+    if (line !== void 0) deps.print(line);
+  };
   let cfg, daemon;
   try {
     cfg = loadConfig({ credentialPath, storePath });
     daemon = parseDaemonArgs(deps.argv, deps.env);
+  } catch (e) {
+    if (e instanceof ConfigError) refuse2(e.reason, { field: e.field, source: e.source }, e);
+    else refuse2("unknown", {}, e);
+    return deps.exit(1);
+  }
+  try {
     validateBind(daemon.bind, daemon.tls);
   } catch (e) {
-    log("error", "startup.config_invalid", {}, e);
+    refuse2("bind_refused", {}, e);
     return deps.exit(1);
   }
   if (!CANONICAL_UUID2.test(cfg.identityId)) {
-    log("error", "startup.config_invalid", { field: ServiceLogEnum.of("identity_id", ["identity_id"]) });
+    refuse2("identity_id_invalid", { field: "identity_id" });
     return deps.exit(1);
   }
   const lockDir = join25(deps.home, ".securecoms", "locks");
@@ -46050,7 +46391,9 @@ async function runMode(deps) {
         lock_path: ServiceLogEnum.of("home_securecoms_locks_identity", ["home_securecoms_locks_identity"]),
         remedy: ServiceLogEnum.of("delete_lock_if_no_other_host", ["delete_lock_if_no_other_host"])
       });
-      deps.print(`This agent's lock file was written under a different computer name: ${lockPath}. If no other computer runs this agent, delete that file and start the agent again.`);
+      deps.print(
+        deps.isTTY ? `This agent's lock file was written under a different computer name: ${lockPath}. If no other computer runs this agent, delete that file and start the agent again.` : "This agent's lock file was written under a different computer name. If no other computer runs this agent, delete that file and start the agent again."
+      );
       return deps.exit(1);
     case "unreadable":
       log("error", "startup.instance_lock_unreadable", {}, lock.lastError);
@@ -46126,7 +46469,7 @@ async function runMode(deps) {
     served = await deps.serve(agent, {
       token,
       allowOrigins: daemon.allowOrigins,
-      readTls: () => daemon.tls ? { cert: readFileSync16(daemon.tlsCert, "utf8"), key: readFileSync16(daemon.tlsKey, "utf8") } : void 0
+      readTls: () => daemon.tls ? { cert: readFileSync17(daemon.tlsCert, "utf8"), key: readFileSync17(daemon.tlsKey, "utf8") } : void 0
     });
   } catch (e) {
     if (!(e instanceof SessionSupersededError)) throw e;
@@ -46171,6 +46514,10 @@ async function runMode(deps) {
     }
   });
 }
+function printNoCredentialRunLine() {
+  process.stderr.write(`${noCredentialLine("run")}
+`);
+}
 async function main() {
   if (!nodeMajorOk(process.versions.node)) {
     writeServiceLog("error", "startup.node_unsupported");
@@ -46197,11 +46544,13 @@ async function main() {
     await runServiceVerb(verb);
     return;
   }
-  const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
-  if (!credentialPath) {
+  const cred = readCredentialArg(process.argv, process.env);
+  if (cred.kind !== "path") {
+    printNoCredentialRunLine();
     writeServiceLog("error", "startup.credential_required.use_--credential");
     process.exit(2);
   }
+  const credentialPath = cred.path;
   const storePath = argOrEnv("--store", "SECURECOMS_STORE");
   await runMode(realRunModeDeps(credentialPath, storePath));
 }
@@ -46219,6 +46568,7 @@ export {
   HELD_POLL_TOTAL_MS,
   SHUTDOWN_HARD_EXIT_MS,
   chooseInstallExecPath,
+  configErrorLine,
   formatServiceError,
   nodeMajorOk,
   parseVerb,