@securecoms/agent-runtime 0.13.0 → 0.13.1

package/README.md

@@ -527,6 +527,27 @@ The paragraph is therefore an advisory configuration summary, not an authority
 claim. Channel authorization and the local gate are both enforced at call
 time, so a configured but ungranted or denied tool is still refused.
 
+## Release notes: 0.13.1
+
+<!-- [COPY, approved by Eric 2026-10-15] -->
+
+0.13.1 prints a plain line when the runtime cannot reach the SecureComs Agent
+Connector, and says so once instead of on every retry.
+
+- **Plain connection lines.** While it waits or fails, the runtime prints one
+  line for the cause, for example `Waiting for the SecureComs Agent Connector
+  to start on this computer...` or `Another agent's Connector is using this
+  agent's port. Restart this agent's Connector.` When it connects it prints
+  `Connected to the SecureComs Agent Connector.`
+- **Quieter log.** The service log records each cause once until it changes,
+  not on every retry. The log names the cause but never a token, a path or an
+  identity id.
+- **Plainer install refusals.** When install cannot use this computer's Node,
+  it names the Node version it needs and the fixed places where Node must be
+  installed.
+
+No setting changes. Use it with `@securecoms/agent-bridge` 0.30.2.
+
 ## Release notes: 0.13.0
 
 <!-- [COPY, approved by Eric 2026-10-12] -->

package/dist/bin.js

@@ -77,6 +77,25 @@ function failureEpisodeReporter(warn) {
     }
   };
 }
+function reasonEpisodeReporter(onNew) {
+  let last = null;
+  return {
+    failed(reason) {
+      if (reason === last) return;
+      last = reason;
+      try {
+        onNew(reason);
+      } catch {
+      }
+    },
+    attached() {
+      last = null;
+    }
+  };
+}
+function writeHumanLine(line2) {
+  console.error(line2);
+}
 function writeServiceLog(level, event, fields, error) {
   const line2 = formatServiceLog(level, event, fields, error);
   if (level === "error") console.error(line2);
@@ -1547,7 +1566,10 @@ var STABLE_LOCATIONS = [
   // system (linux)
 ];
 function candidates(home) {
-  return home ? [...STABLE_LOCATIONS, `${home}/.local/bin/node`] : STABLE_LOCATIONS;
+  return home ? [...STABLE_LOCATIONS, `${home}/.local/bin/node`] : [...STABLE_LOCATIONS];
+}
+function orList(items) {
+  return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
 }
 function usable(path, deps) {
   if (!deps.fileExists(path)) return false;
@@ -1586,7 +1608,7 @@ function chooseInstallExecPath(runningExecPath, override, deps, home) {
   const r = resolveStableNodePath(runningExecPath, deps, home);
   if (!r.stable) {
     throw new Error(
-      `install: no reboot-stable Node found (need major >= ${REQUIRED_NODE_MAJOR} at a path whose location does not encode a version). Version-manager Nodes (nvm/asdf/fnm/volta/n) and Homebrew kegs are relocated on upgrade and would break the service 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 (${orList(candidates(home))}), 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;
@@ -1602,7 +1624,7 @@ function abs(p) {
 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 head = input.identityId.slice(0, 8).toLowerCase();
@@ -4384,6 +4406,26 @@ function parseVoiceGuidance(frame) {
   const g = frame.guidance.trim().slice(0, VOICE_GUIDANCE_MAX_CHARS);
   return g || void 0;
 }
+var TransportStepError = class extends Error {
+  constructor(reason, options) {
+    super(reason, options);
+    this.reason = reason;
+    this.name = "TransportStepError";
+  }
+};
+var TRANSPORT_LINES = {
+  no_connection_file: "Waiting for the SecureComs Agent Connector to start on this computer...",
+  bridge_unreachable: "The SecureComs Agent Connector is not answering. Check that it is running on this computer.",
+  wrong_agent: "Another agent's Connector is using this agent's port. Restart this agent's Connector.",
+  attach_refused: "The Connector refused this runtime. Restart the Connector, then restart this runtime.",
+  connection_file_unreadable: "Can't read the Connector's connection details. Restart the Connector.",
+  token_unreadable: "Can't read the Connector's connection details. Restart the Connector.",
+  unknown: "Can't connect to the SecureComs Agent Connector yet. Retrying.",
+  attached: "Connected to the SecureComs Agent Connector."
+};
+function isEnoent(e) {
+  return typeof e === "object" && e !== null && e.code === "ENOENT";
+}
 var SEEN_MAX = 5e3;
 var PENDING_REPLY_MAX = 1e3;
 var TERMINAL_REPLY_ERRORS = /* @__PURE__ */ new Set(["agent_paused", "send_forbidden"]);
@@ -4394,6 +4436,11 @@ var SecureComsDataPlane = class {
   initialDelayMs;
   maxDelayMs;
   log;
+  print;
+  /** Tier A item 6: one report per reason episode; the settle timer ends it. */
+  episodes;
+  /** The cause behind the failure currently being reported (its class is logged). */
+  failureCause = void 0;
   sleep;
   random;
   healthTimeoutMs;
@@ -4466,6 +4513,11 @@ var SecureComsDataPlane = class {
     this.initialDelayMs = cfg.initialDelayMs ?? 250;
     this.maxDelayMs = cfg.maxDelayMs ?? 3e4;
     this.log = cfg.log ?? writeServiceLog;
+    this.print = cfg.print ?? writeHumanLine;
+    this.episodes = reasonEpisodeReporter((reason) => {
+      this.log("error", "transport.connection_attempt_failed", { reason: logLabel(reason) }, this.failureCause);
+      this.print(TRANSPORT_LINES[reason] ?? TRANSPORT_LINES.unknown);
+    });
     this.sleep = cfg.sleep ?? ((ms2) => new Promise((resolve4) => {
       this.sleepTimer = setTimeout(() => {
         this.sleepTimer = null;
@@ -4552,6 +4604,13 @@ var SecureComsDataPlane = class {
       void this.sleep(ms2).then(finish, finish);
     });
   }
+  /** A human line from a timer callback: a throwing sink must never escape it. */
+  say(line2) {
+    try {
+      this.print(line2);
+    } catch {
+    }
+  }
   clearSettle() {
     if (this.settle) {
       clearTimeout(this.settle);
@@ -4573,7 +4632,9 @@ var SecureComsDataPlane = class {
         await this.attemptOnce();
         delay = this.initialDelayMs;
       } catch (e) {
-        this.log("error", "transport.connection_attempt_failed", {}, e);
+        const step = e instanceof TransportStepError ? e : null;
+        this.failureCause = step && step.cause !== void 0 ? step.cause : e;
+        this.episodes.failed(step ? step.reason : "unknown");
       }
       if (!live()) break;
       await this.wait(this.random() * delay);
@@ -4582,9 +4643,26 @@ var SecureComsDataPlane = class {
     if (this.generation === generation) this.running = false;
   }
   async attemptOnce() {
-    const conn = JSON.parse(readFileSync10(this.connectionPath, "utf8"));
-    const httpBase = conn.bridge_url.replace(/^ws/, "http").replace(/\/v1\/ws$/, "");
-    const token = readFileSync10(conn.token_file, "utf8").trim();
+    let raw;
+    try {
+      raw = readFileSync10(this.connectionPath, "utf8");
+    } catch (e) {
+      throw new TransportStepError(isEnoent(e) ? "no_connection_file" : "connection_file_unreadable", { cause: e });
+    }
+    let conn;
+    let httpBase;
+    try {
+      conn = JSON.parse(raw);
+      httpBase = conn.bridge_url.replace(/^ws/, "http").replace(/\/v1\/ws$/, "");
+    } catch (e) {
+      throw new TransportStepError("connection_file_unreadable", { cause: e });
+    }
+    let token;
+    try {
+      token = readFileSync10(conn.token_file, "utf8").trim();
+    } catch (e) {
+      throw new TransportStepError("token_unreadable", { cause: e });
+    }
     const healthController = new AbortController();
     this.healthController = healthController;
     const healthTimer = setTimeout(
@@ -4594,14 +4672,14 @@ var SecureComsDataPlane = class {
     let health;
     try {
       health = await (await fetch(`${httpBase}/healthz`, { signal: healthController.signal })).json();
+    } catch (e) {
+      throw new TransportStepError("bridge_unreachable", { cause: e });
     } finally {
       clearTimeout(healthTimer);
       if (this.healthController === healthController) this.healthController = null;
     }
     if (conn.identity_id !== health.identity_id || this.identityId !== health.identity_id) {
-      throw new Error(
-        `gate refused: expected ${this.identityId}, connection file says ${conn.identity_id}, daemon on this port is ${health.identity_id}`
-      );
+      throw new TransportStepError("wrong_agent");
     }
     if (this.stopped) return;
     const ws = new WebSocket(`${conn.bridge_url}?token=${encodeURIComponent(token)}`);
@@ -4611,15 +4689,18 @@ var SecureComsDataPlane = class {
     try {
       await new Promise((resolve4, reject) => {
         ws.addEventListener("error", (e) => {
-          reject(Object.assign(new Error("socket_error"), { cause: e }));
+          const err = Object.assign(new Error("socket_error"), { cause: e });
+          reject(established ? err : new TransportStepError("attach_refused", { cause: err }));
         });
         ws.addEventListener("close", (e) => {
           if (established) resolve4();
           else {
             reject(
-              new Error(
-                `closed with code ${e.code} before the connection settled \u2014 bad token, or another connector took this port`
-              )
+              new TransportStepError("attach_refused", {
+                cause: new Error(
+                  `closed with code ${e.code} before the connection settled \u2014 bad token, or another connector took this port`
+                )
+              })
             );
           }
         });
@@ -4632,6 +4713,8 @@ var SecureComsDataPlane = class {
           settle = setTimeout(() => {
             established = true;
             this.log("info", "transport.attached");
+            this.episodes.attached();
+            this.say(TRANSPORT_LINES.attached);
           }, this.establishedMs);
           this.settle = settle;
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-runtime",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "type": "module",
   "bin": {
     "securecoms-agent": "dist/bin.js"