@securecoms/agent-bridge 0.30.0 → 0.30.1

package/README.md

@@ -935,6 +935,43 @@ copied after the owner's next typed message.
 
 ---
 
+## 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 } 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,69 @@ 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;
+    log: ServiceLog;
+}
+/**
+ * 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>;