@securecoms/agent-bridge 0.30.0 → 0.30.1

package/dist/service/instance-lock.d.ts

@@ -0,0 +1,88 @@
+import type { ServiceLog } from "../service-log.js";
+/** An unparseable lock this young may be a holder mid-write. */
+export declare const LOCK_PARTIAL_WRITE_GRACE_MS = 10000;
+/** A takeover guard this old was left by a crashed takeover. */
+export declare const LOCK_TAKEOVER_GUARD_STALE_MS = 30000;
+/** Two boot-epoch reads further apart than this are two different boots. */
+export declare const BOOT_TOLERANCE_SEC = 120;
+/** A holder refreshes its lock's mtime this often (#808 N1). */
+export declare const LOCK_HEARTBEAT_MS = 60000;
+/** A same-kernel, other-hostname lock untouched for this long is abandoned. */
+export declare const LOCK_FOREIGN_STALE_MS: number;
+export type LockRefusal = "held" | "foreign_host" | "unreadable" | "busy" | "failed";
+export type LockResult = "acquired" | LockRefusal;
+/** Everything the lock reads about the machine. Injected in tests. */
+export interface LockEnv {
+    pid: number;
+    hostname(): string;
+    /** Linux boot_id, or undefined where the platform has none. */
+    bootId(): string | undefined;
+    bootEpochSec(): number;
+    /** Linux /proc/<pid>/stat start time, or undefined (not Linux / no such pid). */
+    procStart(pid: number): string | undefined;
+    /** kill(pid, 0): true when running (EPERM counts as running). */
+    pidAlive(pid: number): boolean;
+    /** Test seam: runs after the takeover guard is taken, before the re-read. */
+    beforeTakeoverReread?(): void;
+    /** Test seam: runs after the stale lock is unlinked, before our create. */
+    beforeTakeoverCreate?(): void;
+    /** Test seam: runs after an O_EXCL create found the lock, before it is read. */
+    beforeLockRead?(): void;
+}
+/** Field 22 of /proc/<pid>/stat. The comm field (2) may contain spaces or
+ *  parentheses, so fields are counted from the LAST ')'. */
+export declare function procStartFromStat(stat: string): string | undefined;
+export declare function pidAliveByKill(pid: number): boolean;
+export declare const realLockEnv: LockEnv;
+export declare class InstanceLock {
+    readonly path: string;
+    private readonly env;
+    private readonly log;
+    private readonly heartbeatMs;
+    held: boolean;
+    /** The exact body this process wrote (#808 N1): release and the ownership
+     *  check compare the file against THIS, never against live machine facts
+     *  (a hostname can change under a running process). */
+    private written;
+    private heartbeat;
+    /** The error behind the last `unreadable` / `failed`, for the caller's one
+     *  log line (the lock itself never logs a refusal: it is retried per call). */
+    lastError: unknown;
+    /** PID read from the lock body of the live holder behind the last `held`. */
+    private holderPid;
+    constructor(path: string, env?: LockEnv, log?: ServiceLog, heartbeatMs?: number);
+    private body;
+    /** Try to hold the lock. Never throws (#808 L-e: machine reads included). */
+    acquire(): {
+        result: LockResult;
+        holderPid?: number;
+    };
+    /**
+     * True while the file is still exactly the body this process wrote. Read
+     * before every reserve (one small read), so a holder whose lock was taken
+     * while it was frozen stops before it spends (#808 N1). A lost lock is
+     * dropped: the caller then refuses, and later calls try to re-acquire.
+     */
+    stillHeld(): boolean;
+    private acquireUnguarded;
+    /** Remove the lock only while it is still exactly the body this process
+     *  wrote (#808 N1: not the live hostname, which can change under us). */
+    release(): void;
+    private drop;
+    /** We hold it: remember what we wrote (the file as it is now, ours) and
+     *  start the heartbeat. */
+    private took;
+    /** Refresh the mtime while the file is still ours; stop if it is not. */
+    private beat;
+    private sameBoot;
+    /** O_EXCL create with our body. A write failure removes the half-written
+     *  file (it is ours: we created it) and reports `failed`, never throws. */
+    private create;
+    /**
+     * Replace a stale lock. Only the holder of the O_EXCL takeover guard may
+     * remove a lock, and only after re-reading it UNCHANGED, so two runtimes
+     * that both saw the same stale lock cannot each delete the other's new one.
+     * A fresh guard means a takeover is in progress: busy this time.
+     */
+    private takeOver;
+}

package/dist/service/launchd.d.ts

@@ -1,4 +1,4 @@
 import type { ServiceConfig } from "./config.js";
 /** A deterministic launchd LaunchAgent plist. ProgramArguments re-invoke the
- *  running bin in run mode; KeepAlive restarts on crash, RunAtLoad starts at login. */
+ *  running bin in run mode; KeepAlive{SuccessfulExit:false} restarts only on a non-zero exit (a clean exit stays down), RunAtLoad starts at login. */
 export declare function renderLaunchdPlist(cfg: ServiceConfig): string;

package/dist/service/status.d.ts

@@ -1,11 +1,9 @@
 import type { AgentFleetEntry } from "./fleet.js";
+import { type DaemonHealth } from "./install-prep.js";
 export interface StatusDeps {
     readFleet: () => AgentFleetEntry[];
-    probeConnect: (port: number) => boolean;
-    getHealth: (port: number) => {
-        agent_sessions?: number;
-        evictions?: number;
-    } | null;
+    /** Routed `/healthz` probe (P-2): null unless the daemon answered a 200. */
+    getHealth: (port: number) => DaemonHealth | null;
 }
 export interface AgentStatusRow {
     slug: string;

package/dist/service/systemd.d.ts

@@ -1,4 +1,4 @@
 import type { ServiceConfig } from "./config.js";
 /** A systemd --user unit. ExecStart re-invokes the running bin in run mode;
- *  Restart=always supervises crashes. WantedBy=default.target enables at login. */
+ *  Restart=on-failure supervises crashes only (a clean exit stays down). WantedBy=default.target enables at login. */
 export declare function renderSystemdUnit(cfg: ServiceConfig): string;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.30.0";
+export declare const BRIDGE_VERSION = "0.30.1";

package/dist/ws-server.d.ts

@@ -34,6 +34,9 @@ export declare const INFLIGHT_STALE_AFTER_MS: number;
  * consumer, so it never carried its notes.
  */
 export declare const HELLO_WAIT_MS = 2000;
+/** C9: the close code a superseded bridge sends its local runtime sockets;
+ *  the same code the server sends the bridge (spec §4.1.5, OQ-9). */
+export declare const WS_CLOSE_SESSION_SUPERSEDED = 4409;
 /** Spec §8.5: the hello-reply feature that tells the runtime it may offer memory_note on this socket. */
 export declare const MEMORY_NOTES_FEATURE = "memory_notes";
 /** Semantic memory 7b (spec §7.2 Q4): the hello feature a runtime declares to receive `memory.recall`; the bridge echoes it. */
@@ -52,4 +55,5 @@ export declare const WS_AGENT_MEMBERS: readonly ["ackRuntimeMessages", "action",
 export type WsAgent = Pick<BridgeAgent, (typeof WS_AGENT_MEMBERS)[number]>;
 export declare function attachAgentWebSocket(server: HttpServer, agent: WsAgent, opts: AgentWebSocketOptions): {
     close(): void;
+    enterSessionSuperseded(): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "type": "module",
   "engines": {
     "node": ">=22.5.0"