@securecoms/agent-bridge 0.30.0 → 0.30.2

package/README.md

@@ -35,13 +35,9 @@ The server still sees ciphertext only. The trust boundary is the machine running
 - **Node.js 24 LTS or newer.** The daemon requires >= 24 (node:sqlite stable API).
 - A valid SecureComs agent credential (`agent.json`, `chmod 600`)
 
-You don't have to check your Node version yourself. The installer self-checks before anything else runs: on an older Node it prints a clear diagnosis instead of crashing, and on macOS it offers to install Node 24 LTS for you. The install is consent-gated and names its source before asking. If Homebrew is present it runs `brew install node` (user-space, no sudo); otherwise it downloads the official installer from nodejs.org over TLS and verifies the published SHA-256 checksum (an integrity check on the download) before running it.
+You don't have to check your Node version yourself. The installer checks it before anything else runs. On an older Node it says so plainly, and on macOS it offers to install Node 24 from nodejs.org after asking you. That step needs your computer's administrator password. It checks the download's published SHA-256 checksum before running it.
 
-To install Node 24 manually instead:
-
-1. Official installer (recommended): download the Node 24 LTS installer from [nodejs.org](https://nodejs.org) and run it.
-2. Homebrew (macOS): `brew install node`
-3. nvm: `nvm install 24 && nvm use 24`
+To install Node 24 yourself, download the Node 24 LTS installer from [nodejs.org](https://nodejs.org) and run it. Then run the install command again.
 
 Always re-run the install command after upgrading Node — the background service pins the Node path it was installed with.
 
@@ -935,6 +931,81 @@ copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.30.2
+
+<!-- [COPY, approved by Eric 2026-10-15] -->
+
+0.30.2 fixes the guided Node upgrade, makes reinstall safe while the agent is
+running, and prints plain messages when the agent cannot start.
+
+- **The Node upgrade works again on macOS.** When this computer has an older
+  Node, install offers to install Node 24 from nodejs.org. Before 0.30.2 this
+  step could not find the installer and stopped without saying why. It now
+  finds it, checks its published SHA-256 checksum, and asks first:
+  `SecureComs needs Node 24. Install it now from nodejs.org? This needs your
+  computer's administrator password. [y/N]`. If the step fails after you say
+  yes, it prints: `Couldn't install Node 24 from nodejs.org.`
+- **Homebrew is no longer used.** The guided upgrade always uses the
+  nodejs.org installer.
+- **Reinstall while the agent runs.** Install now waits up to 10 seconds for
+  the running Connector to stop before it starts the new one. Before, the new
+  copy could start too early, find the old copy still running, and stay
+  stopped. If the old copy does not stop in time, install starts nothing and
+  tells you to run install again.
+- **Plain messages when the agent cannot start.** A missing, unreadable or
+  invalid key file, or a bad setting in it, now each print one short line
+  that says what to do. File paths are printed only in a terminal, not in the
+  service log.
+- **No key file found.** If the copied install command finds no key file, it
+  prints: `No key file was found in your Downloads folder. Download the key
+  file again from SecureComs, or add --credential <path>.` An empty
+  `--credential` no longer falls back to the `SECURECOMS_CREDENTIAL`
+  environment variable.
+- **Node 24 or newer.** The package now declares `node >= 24`, which the
+  Connector already required to run.
+
+You do not need to change anything after the upgrade. Run the install command
+again only if you want the new install behavior now.
+
+---
+
+## Release notes: 0.30.1
+
+<!-- [COPY, approved by Eric 2026-10-14] -->
+
+0.30.1 makes sure only one copy of an agent runs, and makes install say
+clearly when the agent did not start.
+
+- **Reinstall once after you upgrade.** Run the install command again for
+  each agent. It writes a new service file. The old file restarts the
+  Connector every time it stops, so a refused second copy would keep
+  restarting and print the "already running" message every 10 seconds.
+- **One copy per agent on a computer.** A second copy of the same agent
+  stops before it connects and prints: `This agent is already running on this
+  computer (process <pid>). Stop that copy first, or run: agent-bridge status`
+- **Port already in use.** If another program holds the Connector's port, the
+  agent does not start and prints: `Port <n> is already in use by another
+  program on this computer, so the agent did not start.`
+- **Install checks that the agent really started.** Install now waits up to
+  75 seconds for the Connector to answer its health check. If it does not
+  answer, install fails and names the service log.
+- **Install refuses a second install of the same agent.** If the agent is
+  already installed in another folder or with a different key, install stops
+  before it changes anything and prints: `This agent is already installed in
+  <dir> with a different key. Uninstall it first: agent-bridge uninstall
+  --label <label>`. A downloaded copy such as `margo (1).json` installs as the
+  same agent, not as a new one.
+- **The service restarts only after a failure.** On macOS the new service
+  file restarts the Connector only when it exits with an error. On Linux the
+  unit uses `Restart=on-failure`.
+- **Prepared for one active connection per agent.** When the server reports
+  that the agent connected from another place, this copy stops all network
+  traffic and prints: `This agent connected from another place, so this copy
+  stopped. Stop the other copy, then restart this one.` It stays stopped and
+  does not restart itself. The server side of this check is not turned on yet.
+
+---
+
 ## Release notes: 0.30.0
 
 <!-- [COPY, approved by Eric 2026-10-12] -->

package/dist/bin.d.ts

@@ -1,9 +1,22 @@
 #!/usr/bin/env node
+/**
+ * SecureComs Agent Bridge — HTTP daemon entry point.
+ * Long-running diagnostics go to stderr through the content-free service
+ * logger. The local bearer token is persisted to the `bridge-token` file (see
+ * tokenFile below); startup emits only a fixed token-loaded event, never the
+ * token, its fingerprint, or its path. This prevents the former
+ * `BRIDGE_TOKEN=<value>` leak into journald/launchd logs.
+ */
+import { type BridgeConfig, type ConfigErrorReason } from "./config.js";
 import { BridgeAgent } from "./bridge-agent.js";
 import { createHttpServer } from "./http-server.js";
 import { attachAgentWebSocket } from "./ws-server.js";
+import { createServer as netCreateServer } from "node:net";
+import { type DaemonHealth } from "./service/install-prep.js";
 import { type ResolveNodeDeps } from "./service/resolve-node.js";
 import { type Harness } from "./service/wire.js";
+import { type ServiceLog } from "./service-log.js";
+import { type LockResult } from "./service/instance-lock.js";
 export declare function nodeMajorOk(version: string): boolean;
 /**
  * A redacted bearer-token hint for explicit foreground install output: a short
@@ -14,7 +27,10 @@ export declare function tokenFingerprint(token: string): string;
 export declare function parseVerb(argv: string[]): "install" | "uninstall" | "status" | "wire" | "unwire" | "models" | "pin" | null;
 export declare function slugFromCredentialPath(credentialPath: string): string;
 export declare function chooseInstallExecPath(runningExecPath: string, override: string | undefined, deps: ResolveNodeDeps): string;
+export declare function realGetHealth(port: number): DaemonHealth | null;
 export declare function realCopyConnector(srcDir: string, dstDir: string, harness: Harness): void;
+/** The stderr line (with newline) a failed service verb prints. */
+export declare function formatServiceError(verb: string, e: unknown): string;
 /**
  * Markdown memory 7a, N-L5: start the agent, THEN create the HTTP server and
  * attach /v1/ws. start() applies the runtime config (and any clear issued
@@ -35,3 +51,88 @@ export declare function startThenServe(agent: BridgeAgent, opts: {
     closeAllSseStreams: () => void;
     agentWs: ReturnType<typeof attachAgentWebSocket>;
 }>;
+/** B1 `held` poll (spec §4.1.2, audit r2 M-3): the holder may be this same
+ *  service's previous process, still inside shutdown()'s 8 s drain window. */
+export declare const HELD_POLL_TOTAL_MS = 10000;
+export declare const HELD_POLL_INTERVAL_MS = 500;
+/** Extra acquires after the poll when "held" carries no holder pid (a takeover
+ *  race). M1 names a real pid or is not printed. */
+export declare const HELD_NO_PID_REACQUIRES = 3;
+/** shutdown()'s hard-exit fallback for a hung agent.close() drain (ADR-0008 H1). */
+export declare const SHUTDOWN_HARD_EXIT_MS = 8000;
+/** The lock surface runMode uses (InstanceLock in production). */
+export interface RunModeLock {
+    acquire(): {
+        result: LockResult;
+        holderPid?: number;
+    };
+    release(): void;
+    lastError?: unknown;
+}
+/**
+ * Everything run mode touches outside the process, injected so the start
+ * order, the refusal exits and the release timing are testable
+ * (bin-run-mode.test.ts). `exit` never returns in production; runMode
+ * returns right after calling it so a recording test double also stops.
+ */
+export interface RunModeDeps {
+    credentialPath: string;
+    storePath?: string;
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    home: string;
+    newLock(path: string): RunModeLock;
+    newAgent(cfg: BridgeConfig): BridgeAgent;
+    /** The B2 pre-bind's socket layer (node:net in production). */
+    net: {
+        createServer: typeof netCreateServer;
+    };
+    serve: typeof startThenServe;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /** Arms the shutdown hard-exit fallback; returns its cancel. */
+    setHardExitTimer(cb: () => void, ms: number): () => void;
+    onSignal(signal: "SIGINT" | "SIGTERM", handler: () => void): void;
+    /** Synchronous `process.once("exit")` registration. */
+    onExit(handler: () => void): void;
+    exit(code: number): void;
+    /** One line of approved user-facing copy (spec §8). */
+    print(line: string): void;
+    /**
+     * Whether stderr is a terminal. Under launchd and systemd stderr IS the
+     * service log, so a printed line may carry a path only when this is true
+     * (spec 2026-10-15 §5.3 path rule).
+     */
+    isTTY: boolean;
+    log: ServiceLog;
+}
+export type StartupConfigReason = ConfigErrorReason | "identity_id_invalid" | "bind_refused" | "unknown";
+/**
+ * The one human line for a run-mode config refusal (spec 2026-10-15 §5.3,
+ * E1-E7 approved; E5 with source=env is the BT-5 draft). The path is shown
+ * only on a TTY; `field` is one of the six fixed REQUIRED names. `unknown`
+ * has no line. Never built from an error message.
+ */
+export declare function configErrorLine(reason: StartupConfigReason, o: {
+    path: string;
+    isTTY: boolean;
+    field?: string;
+    source?: "file" | "env";
+}): string | undefined;
+/**
+ * The daemon's run mode (spec §4.1.1). Order, each step gated on the last:
+ *   1. loadConfig (+ daemon args, bind check);
+ *   2. canonical-UUID check of identity_id (it becomes a path);
+ *   3. B1 per-identity lock at ~/.securecoms/locks/<identity_id>.lock;
+ *   4. resolveToken (it can WRITE the token file, so only after the lock);
+ *   5. B2 pre-bind of daemon.port: a bare net server that destroys every
+ *      connection, so a taken port refuses before the store opens or any
+ *      call to SecureComs is made;
+ *   6. new BridgeAgent (opens the SQLite MLS store);
+ *   7. startThenServe, then hand the pre-bound handle to the HTTP server.
+ * The lock is released only after agent.close() settles (audit H-2): in the
+ * close().finally, in the hard-exit fallback, and in a synchronous exit
+ * backstop. Never at shutdown() entry: a second copy must not open the MLS
+ * store while this one is still draining it.
+ */
+export declare function runMode(deps: RunModeDeps): Promise<void>;