@scp-dev/broker 0.1.6 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ScopePreset, Claim, EndpointView, ScopeView, ScopeChange, Envelope, StopWaitResult, PeerView, WhyResult, SendParams, SendResult, ActivityRow, XListed, Selector } from '@scp-dev/core';
-import { JudgeGate as JudgeGate$1, JudgeGateOptions, FederatedCore, Deliver, JudgeClientFactory } from '@scp-dev/hub';
+import { LOCAL_EVENT_KINDS, JudgeGate as JudgeGate$1, JudgeGateOptions, FederatedCore, Deliver, JudgeClientFactory } from '@scp-dev/hub';
 export { Deliver } from '@scp-dev/hub';
 
 interface Hello {
@@ -203,6 +203,10 @@ interface BridgeConfig {
     redact?: boolean | undefined;
     /** let messages marked private leave this machine */
     privateOk?: boolean | undefined;
+    /** report metadata of deliveries made on this machine to the hub, never bodies (default true) */
+    mirrorLocal?: boolean | undefined;
+    /** how often reported local deliveries are sent, batched (default 1 s) */
+    localFlushMs?: number | undefined;
     /** a WebSocket constructor (tests) */
     webSocket?: WebSocketWithHeaders | undefined;
     /** reconnect backoff bounds (default 1 s to 60 s) */
@@ -236,6 +240,8 @@ interface Bridge {
     renamed(endpoint: string, was: string): void;
     /** a local endpoint's activity, posted to the hub */
     activity(endpoint: string, row: ActivityRow): void;
+    /** a delivery between endpoints of this machine: its metadata is reported to the hub in the next batch */
+    local?(event: LocalDelivery): void;
     /** the endpoints of other accounts this account's contacts let it reach */
     contacts(): Promise<XListed[]>;
     status(): BridgeStatus;
@@ -243,6 +249,15 @@ interface Bridge {
     relink(): void;
     stop(): Promise<void>;
 }
+/** a delivery the broker made on its own machine, by local endpoint ids */
+interface LocalDelivery {
+    id: string;
+    thread: string;
+    kind: (typeof LOCAL_EVENT_KINDS)[number];
+    from: string;
+    to: string[];
+    at: number;
+}
 /** a WebSocket constructor that takes request headers, as Bun's and Node's do */
 type WebSocketWithHeaders = new (url: string, options: {
     headers: Record<string, string>;
@@ -319,6 +334,8 @@ interface BrokerOptions {
     link?: LinkFactory | undefined;
     /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
     presenceEveryMs?: number | undefined;
+    /** how often the broker checks it still owns its socket and lock, stopping once another broker or a wiped state directory took them (default 2 s) */
+    ownershipEveryMs?: number | undefined;
     /** where a judge model's key_env is read (default the broker's environment) */
     env?: Record<string, string | undefined> | undefined;
     /** the judge model client for a policy's `judge.model` (default the provider's HTTP API) */

package/dist/index.js

@@ -524,6 +524,7 @@ async function connectBroker(dir, start, timeoutMs = 5e3) {
 }
 
 // src/bridge.ts
+import { createHash as createHash2 } from "crypto";
 import {
   findSecret,
   matches,
@@ -532,7 +533,9 @@ import {
   RelayError as RelayError2,
   XLIMITS
 } from "@scp-dev/core";
-import { HUB_LIMITS } from "@scp-dev/hub";
+import { HUB_LIMITS, LOCAL_EVENTS } from "@scp-dev/hub";
+var LOCAL_BUFFER = 1e3;
+var idHash = (id) => createHash2("sha256").update(id).digest("hex").slice(0, 32);
 var CONNECT_TIMEOUT_MS = 15e3;
 var MIRROR_FRAME_BYTES = HUB_LIMITS.frameBytes - 1024;
 var DEAD_LETTER_ATTEMPTS = 3;
@@ -578,6 +581,10 @@ function startBridge(options) {
   const inflight = /* @__PURE__ */ new Set();
   const injectFailures = /* @__PURE__ */ new Map();
   const fromHub = /* @__PURE__ */ new WeakSet();
+  const mirrorLocal = options.mirrorLocal !== false;
+  const localFlushMs = options.localFlushMs ?? 1e3;
+  let localQueue = [];
+  let localTimer;
   const setState = (up, error) => {
     if (up !== connected || error !== lastError) since = (/* @__PURE__ */ new Date()).toISOString();
     connected = up;
@@ -699,7 +706,8 @@ function startBridge(options) {
       byMachine.set(view.machine, [...byMachine.get(view.machine) ?? [], view]);
     }
     if (full) {
-      for (const view of core.remoteViews()) if (view.machine !== account && !byMachine.has(view.machine)) byMachine.set(view.machine, []);
+      core.dropMachine(machine);
+      for (const view of core.remoteViews()) if (view.machine !== account && !byMachine.has(view.machine)) core.dropMachine(view.machine);
     }
     for (const [name, list] of byMachine) {
       try {
@@ -800,7 +808,8 @@ function startBridge(options) {
         if (typeof params.machine !== "string" || params.machine === machine) return;
         if (typeof params.own === "boolean") core.setOther(params.machine, !params.own);
         try {
-          core.mirror(params.machine, params.endpoints, { full: params.full === true });
+          if (params.released === true) core.dropMachine(params.machine);
+          else core.mirror(params.machine, params.endpoints, { full: params.full === true });
         } catch (error) {
           log(`relay bridge: the endpoints of ${params.machine} were not applied: ${error instanceof Error ? error.message : String(error)}`);
         }
@@ -887,21 +896,21 @@ function startBridge(options) {
     if (event.machine === machine) return;
     if (event.type === "message" && Array.isArray(event.to) && account && event.to.some((to) => typeof to === "string" && to.startsWith(`${account}/${machine}/`)))
       return;
-    const local = {
+    const local2 = {
       ...event,
       ...event.from !== void 0 ? { from: localAddress(event.from) } : {},
       ...event.endpoint !== void 0 ? { endpoint: localAddress(event.endpoint) } : {}
     };
-    if (Array.isArray(event.to)) local.to = event.to.map(localAddress);
+    if (Array.isArray(event.to)) local2.to = event.to.map(localAddress);
     if (event.type === "activity" && typeof event.machine === "string" && typeof event.endpoint === "string") {
       try {
         const proxy = core.remoteEndpoint(event.machine, event.endpoint.slice(event.endpoint.lastIndexOf("/") + 1));
         const row = core.event(proxy, { kind: event.kind, tool: event.tool, summary: event.summary });
-        local.id = row.id;
+        local2.id = row.id;
       } catch {
       }
     }
-    hooks.fleet(local);
+    hooks.fleet(local2);
   }
   function linkUp(ms) {
     if (connected) return Promise.resolve(true);
@@ -1017,6 +1026,30 @@ function startBridge(options) {
     if (handle === null) return;
     fireAndForget("event", { from: handle, kind: row.kind, tool: row.tool ?? void 0, summary: options.redact ? void 0 : row.summary ?? void 0 });
   }
+  function local(event) {
+    if (!mirrorLocal || !ready || localQueue.length >= LOCAL_BUFFER) return;
+    let from;
+    let to;
+    try {
+      from = handleOf(event.from);
+      to = event.to.flatMap((endpoint) => {
+        const handle = handleOf(endpoint);
+        return handle === null ? [] : [handle];
+      });
+    } catch {
+      return;
+    }
+    if (from === null || !to.length) return;
+    localQueue.push({ from, to: to.slice(0, LOCAL_EVENTS.recipients), kind: event.kind, at: event.at, id: idHash(event.id), thread: idHash(event.thread) });
+    localTimer ??= setTimeout(flushLocal, localFlushMs);
+  }
+  function flushLocal() {
+    localTimer = void 0;
+    const batch = localQueue;
+    localQueue = [];
+    if (!ready) return;
+    for (let i = 0; i < batch.length; i += LOCAL_EVENTS.perFrame) fireAndForget("local_events", { events: batch.slice(i, i + LOCAL_EVENTS.perFrame) });
+  }
   async function contacts() {
     if (!connected) throw unavailable();
     return (await request("list", { contacts: true })).contacts;
@@ -1038,6 +1071,8 @@ function startBridge(options) {
     stopped = true;
     shutDown = true;
     clearTimeout(retryTimer);
+    clearTimeout(localTimer);
+    localQueue = [];
     for (const fn of waitingForLink.splice(0)) fn();
     const socket = ws;
     ws = null;
@@ -1048,11 +1083,11 @@ function startBridge(options) {
     if (socket && socket.readyState <= 1) socket.close(1e3, "the broker stopped");
   }
   connect();
-  return { forward, changed, resync, renamed, activity, contacts, status, relink, stop };
+  return { forward, changed, resync, renamed, activity, local, contacts, status, relink, stop };
 }
 
 // src/server.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { chmodSync as chmodSync2, existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync6, realpathSync, rmdirSync, unlinkSync as unlinkSync2 } from "fs";
 import { createServer } from "net";
 import { homedir as homedir2 } from "os";
@@ -1089,11 +1124,11 @@ var JudgeGate = class extends HubJudgeGate {
 };
 
 // src/sessions.ts
-import { createHash as createHash2, randomUUID } from "crypto";
+import { createHash as createHash3, randomUUID } from "crypto";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync as renameSync2, rmSync, writeFileSync } from "fs";
 import { join as join3 } from "path";
 function markerPath(dir, session) {
-  return join3(dir, "sessions", `${createHash2("sha256").update(session).digest("hex").slice(0, 32)}.json`);
+  return join3(dir, "sessions", `${createHash3("sha256").update(session).digest("hex").slice(0, 32)}.json`);
 }
 function readSessionMarker(dir, session) {
   try {
@@ -1191,6 +1226,7 @@ function openDatabase(path) {
 // src/server.ts
 var SWEEP_MS = 10 * 6e4;
 var PRESENCE_MS = 6e4;
+var OWNERSHIP_MS = 2e3;
 var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"]);
 var SCOPE_METHODS = /* @__PURE__ */ new Set([
   "rules",
@@ -1271,6 +1307,7 @@ async function startBroker(options) {
   let judge;
   let bridge = null;
   let listener;
+  let socketIno;
   try {
     privateDir(dirname2(socket));
     db = openDatabase(join4(dir, "relay.db"));
@@ -1282,11 +1319,12 @@ async function startBroker(options) {
     core = new FederatedCore(sql, {
       ...compact({ user: options.user, machine, now: options.now }),
       hostname: shortHostname(),
-      hash: (value) => createHash3("sha256").update(value).digest("hex"),
+      hash: (value) => createHash4("sha256").update(value).digest("hex"),
       transaction: (fn) => db.transaction(fn),
       alive: running
     });
     core.migrate();
+    core.relabelMachine();
     core.resetConnections();
     core.sweep();
     judge = new JudgeGate({ sql, core, now: options.now ?? Date.now, env: options.env ?? process.env, client: options.judgeClient, log, wake });
@@ -1323,6 +1361,7 @@ async function startBroker(options) {
     });
     listener.on("error", (error) => log(`relay broker: the socket listener failed: ${error.message}`));
     chmodSync2(socket, 384);
+    socketIno = lstatSync2(socket).ino;
   } catch (error) {
     listener?.close();
     db?.close();
@@ -1346,6 +1385,22 @@ async function startBroker(options) {
     }
     for (const id of known.keys()) if (!live.has(id)) known.delete(id);
   }, options.presenceEveryMs ?? PRESENCE_MS);
+  const ownership = setInterval(() => {
+    if (closing || ownsState()) return;
+    log(`relay broker: ${socket} or its lock was removed or taken over; stopping`);
+    void stop();
+  }, options.ownershipEveryMs ?? OWNERSHIP_MS);
+  ownership.unref?.();
+  function ownsSocket() {
+    return lstatSync2(socket, { throwIfNoEntry: false })?.ino === socketIno;
+  }
+  function ownsState() {
+    try {
+      return ownsSocket() && readFileSync6(lock.path, "utf8") === lock.content;
+    } catch {
+      return false;
+    }
+  }
   const remoteHooks = {
     wake,
     fleet: notifyFleet,
@@ -1434,6 +1489,20 @@ async function startBroker(options) {
   function localViews() {
     return core.list({ all: true }).filter((view) => core.machineOf(view.id) === null);
   }
+  function setWaker(s, endpoint) {
+    const was = s.data.waker;
+    if (was === endpoint) return;
+    s.data.waker = endpoint;
+    if (was) core.waker(was, false, { grace: s.data.transient === true });
+    if (endpoint) core.waker(endpoint, true);
+    for (const id of [was, endpoint]) if (id) presenceMoved(id);
+  }
+  function presenceMoved(id) {
+    const view = core.whoami(id);
+    if ((known.get(id) ?? "offline") === view.presence) return false;
+    presenceChanged(view);
+    return true;
+  }
   function presenceChanged(view) {
     known.set(view.id, view.presence);
     notifyFleet({ type: "presence", endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels });
@@ -1585,6 +1654,7 @@ async function startBroker(options) {
     s.data.closed = true;
     clearTimeout(s.data.lineTimer);
     connections.delete(s);
+    if (!closing) setWaker(s, void 0);
     if (s.data.endpoint && !closing && !s.data.transient && !s.data.lineage) {
       const before = core.whoami(s.data.endpoint).presence;
       const settled = core.disconnect(s.data.endpoint, { settle: !s.data.brief });
@@ -1878,7 +1948,8 @@ async function startBroker(options) {
       case "wake": {
         if (s.data.lineage && !s.data.own) throw new RelayError3("unauthorized", "only the endpoint's own session says how it wakes");
         const changed = core.setWake(me, params.via, hookOf(s));
-        if (changed) bridge?.changed(me);
+        setWaker(s, params.via !== "none" && core.whoami(me).wake === params.via ? me : void 0);
+        if (!presenceMoved(me) && changed) bridge?.changed(me);
         return { changed };
       }
       case "rename": {
@@ -1981,13 +2052,23 @@ async function startBroker(options) {
   }
   const deliver = async (from, send, origin) => {
     let result;
-    if (remoteSend(core, send.to)) {
+    const remote = remoteSend(core, send.to);
+    if (remote) {
       if (!bridge)
         throw new RelayError3("not_found", `no endpoint ${[send.to].flat().join(", ")}: this broker is not linked to a hub (${CLI_NAME} cloud enable)`);
       result = await bridge.forward(from, send, origin);
     } else {
       result = core.send(from, send, origin);
     }
+    if (!result.duplicate && !remote)
+      bridge?.local?.({
+        id: result.id,
+        thread: result.thread,
+        kind: send.kind ?? "message",
+        from,
+        to: result.deliveries.map((d) => d.endpoint),
+        at: (options.now ?? Date.now)()
+      });
     if (!result.duplicate) {
       for (const delivery of result.deliveries) wake(delivery.endpoint);
       notifyFleet({
@@ -2113,6 +2194,14 @@ async function startBroker(options) {
         if (result.handback) {
           const message = core.delivered(spawner, result.handback);
           wake(spawner);
+          bridge?.local?.({
+            id: message.id,
+            thread: message.thread,
+            kind: "handback",
+            from: message.from.endpoint,
+            to: [spawner],
+            at: (options.now ?? Date.now)()
+          });
           notifyFleet({
             type: "message",
             id: message.id,
@@ -2163,6 +2252,7 @@ async function startBroker(options) {
       closing = true;
       clearInterval(sweeper);
       clearInterval(presenceTimer);
+      clearInterval(ownership);
       await bridge?.stop();
       if (idleTimer) clearTimeout(idleTimer);
       for (const set of [...waiters.values()]) for (const fn of [...set]) fn();
@@ -2170,11 +2260,13 @@ async function startBroker(options) {
       while (pending > 0 && Date.now() < deadline) await sleep2(5);
       await Promise.race([judge.settled(), sleep2(Math.max(0, deadline - Date.now()))]);
       for (const s of connections) s.end();
-      listener.close();
-      try {
-        unlinkSync2(socket);
-      } catch {
-      }
+      if (ownsSocket()) {
+        listener.close();
+        try {
+          unlinkSync2(socket);
+        } catch {
+        }
+      } else listener.unref();
       if (socket !== join4(dir, "relay.sock")) {
         try {
           rmdirSync(dirname2(socket));

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { RelayHub, HubSocket } from '@scp-dev/hub';
+import { RelayHub, HubSocket, DashboardEvent } from '@scp-dev/hub';
 
 interface FakeToken {
     tokenId: string;
@@ -27,6 +27,8 @@ declare function startFakeHubServer(options: {
     tokens: Record<string, FakeToken>;
     now?: (() => number) | undefined;
     contacts?: [string, string][] | undefined;
+    /** receives every account's dashboard events */
+    dashboard?: ((account: string, event: DashboardEvent) => void) | undefined;
 }): FakeHubServer;
 
 export { type FakeHubServer, type FakeToken, startFakeHubServer };

package/dist/testing.js

@@ -37,7 +37,8 @@ function startFakeHubServer(options) {
       sockets: () => [...sockets.values()],
       save: () => {
       },
-      ...options.contacts ? { crossAccount: linkOf(name) } : {}
+      ...options.contacts ? { crossAccount: linkOf(name) } : {},
+      ...options.dashboard ? { dashboard: (event) => options.dashboard(name, event) } : {}
     });
     hub.init({ user: name });
     found = { hub, sockets, traps: /* @__PURE__ */ new Map() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/broker",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Swarm Communication Protocol local broker: a unix socket JSON-RPC daemon over the relay core, its client and the bridge to an account hub.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -37,8 +37,8 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/core": "0.1.4",
-    "@scp-dev/hub": "0.4.0"
+    "@scp-dev/core": "0.1.6",
+    "@scp-dev/hub": "0.5.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/bridge.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto"
 import {
   type ActivityRow,
   type EndpointView,
@@ -13,7 +14,7 @@ import {
   XLIMITS,
   type XListed,
 } from "@scp-dev/core"
-import { type FederatedCore, HUB_LIMITS, type RemoteView } from "@scp-dev/hub"
+import { type FederatedCore, HUB_LIMITS, type LOCAL_EVENT_KINDS, LOCAL_EVENTS, type RemoteView } from "@scp-dev/hub"
 
 /** what the broker gives the bridge: waking local waiters, telling local watchers, the local policy's state */
 export interface BridgeHooks {
@@ -42,6 +43,10 @@ export interface BridgeConfig {
   redact?: boolean | undefined
   /** let messages marked private leave this machine */
   privateOk?: boolean | undefined
+  /** report metadata of deliveries made on this machine to the hub, never bodies (default true) */
+  mirrorLocal?: boolean | undefined
+  /** how often reported local deliveries are sent, batched (default 1 s) */
+  localFlushMs?: number | undefined
   /** a WebSocket constructor (tests) */
   webSocket?: WebSocketWithHeaders | undefined
   /** reconnect backoff bounds (default 1 s to 60 s) */
@@ -77,6 +82,8 @@ export interface Bridge {
   renamed(endpoint: string, was: string): void
   /** a local endpoint's activity, posted to the hub */
   activity(endpoint: string, row: ActivityRow): void
+  /** a delivery between endpoints of this machine: its metadata is reported to the hub in the next batch */
+  local?(event: LocalDelivery): void
   /** the endpoints of other accounts this account's contacts let it reach */
   contacts(): Promise<XListed[]>
   status(): BridgeStatus
@@ -85,6 +92,21 @@ export interface Bridge {
   stop(): Promise<void>
 }
 
+/** a delivery the broker made on its own machine, by local endpoint ids */
+export interface LocalDelivery {
+  id: string
+  thread: string
+  kind: (typeof LOCAL_EVENT_KINDS)[number]
+  from: string
+  to: string[]
+  at: number
+}
+
+/** local deliveries waiting for the next batch; past this, new ones are dropped until it is sent */
+const LOCAL_BUFFER = 1000
+
+const idHash = (id: string): string => createHash("sha256").update(id).digest("hex").slice(0, 32)
+
 /** a WebSocket constructor that takes request headers, as Bun's and Node's do */
 export type WebSocketWithHeaders = new (url: string, options: { headers: Record<string, string> }) => WebSocket
 
@@ -153,6 +175,10 @@ export function startBridge(options: BridgeOptions): Bridge {
   const inflight = new Set<number>()
   const injectFailures = new Map<number, number>()
   const fromHub = new WeakSet<Error>()
+  const mirrorLocal = options.mirrorLocal !== false
+  const localFlushMs = options.localFlushMs ?? 1000
+  let localQueue: object[] = []
+  let localTimer: ReturnType<typeof setTimeout> | undefined
 
   const setState = (up: boolean, error: string | null) => {
     if (up !== connected || error !== lastError) since = new Date().toISOString()
@@ -274,14 +300,20 @@ export function startBridge(options: BridgeOptions): Bridge {
     for (const fn of waitingForLink.splice(0)) fn()
   }
 
-  /** the other machines' endpoints, grouped by machine; with `full`, a known machine missing from the list goes offline */
+  /**
+   * the other machines' endpoints, grouped by machine; with `full`, a known machine the hub no longer lists was released and its rows go,
+   * as do rows mirrored under this machine's own name from before it was renamed back to it
+   */
   function applyRemote(views: RemoteView[], full: boolean) {
     const byMachine = new Map<string, RemoteView[]>()
     for (const view of views) {
       if (view.machine === machine) continue
       byMachine.set(view.machine, [...(byMachine.get(view.machine) ?? []), view])
     }
-    if (full) for (const view of core.remoteViews()) if (view.machine !== account && !byMachine.has(view.machine)) byMachine.set(view.machine, [])
+    if (full) {
+      core.dropMachine(machine)
+      for (const view of core.remoteViews()) if (view.machine !== account && !byMachine.has(view.machine)) core.dropMachine(view.machine)
+    }
     for (const [name, list] of byMachine) {
       try {
         core.mirror(name, list, { full })
@@ -397,7 +429,8 @@ export function startBridge(options: BridgeOptions): Bridge {
         if (typeof params.machine !== "string" || params.machine === machine) return
         if (typeof params.own === "boolean") core.setOther(params.machine, !params.own)
         try {
-          core.mirror(params.machine, params.endpoints, { full: params.full === true })
+          if (params.released === true) core.dropMachine(params.machine)
+          else core.mirror(params.machine, params.endpoints, { full: params.full === true })
         } catch (error) {
           log(`relay bridge: the endpoints of ${params.machine} were not applied: ${error instanceof Error ? error.message : String(error)}`)
         }
@@ -636,6 +669,32 @@ export function startBridge(options: BridgeOptions): Bridge {
     fireAndForget("event", { from: handle, kind: row.kind, tool: row.tool ?? undefined, summary: options.redact ? undefined : (row.summary ?? undefined) })
   }
 
+  function local(event: LocalDelivery) {
+    if (!mirrorLocal || !ready || localQueue.length >= LOCAL_BUFFER) return
+    let from: string | null
+    let to: string[]
+    try {
+      from = handleOf(event.from)
+      to = event.to.flatMap((endpoint) => {
+        const handle = handleOf(endpoint)
+        return handle === null ? [] : [handle]
+      })
+    } catch {
+      return
+    }
+    if (from === null || !to.length) return
+    localQueue.push({ from, to: to.slice(0, LOCAL_EVENTS.recipients), kind: event.kind, at: event.at, id: idHash(event.id), thread: idHash(event.thread) })
+    localTimer ??= setTimeout(flushLocal, localFlushMs)
+  }
+
+  function flushLocal() {
+    localTimer = undefined
+    const batch = localQueue
+    localQueue = []
+    if (!ready) return
+    for (let i = 0; i < batch.length; i += LOCAL_EVENTS.perFrame) fireAndForget("local_events", { events: batch.slice(i, i + LOCAL_EVENTS.perFrame) })
+  }
+
   async function contacts(): Promise<XListed[]> {
     if (!connected) throw unavailable()
     return (await request<{ contacts: XListed[] }>("list", { contacts: true })).contacts
@@ -660,6 +719,8 @@ export function startBridge(options: BridgeOptions): Bridge {
     stopped = true
     shutDown = true
     clearTimeout(retryTimer)
+    clearTimeout(localTimer)
+    localQueue = []
     for (const fn of waitingForLink.splice(0)) fn()
     const socket = ws
     ws = null
@@ -671,5 +732,5 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   connect()
-  return { forward, changed, resync, renamed, activity, contacts, status, relink, stop }
+  return { forward, changed, resync, renamed, activity, local, contacts, status, relink, stop }
 }

package/src/server.ts

@@ -64,6 +64,8 @@ export interface BrokerOptions {
   link?: LinkFactory | undefined
   /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
   presenceEveryMs?: number | undefined
+  /** how often the broker checks it still owns its socket and lock, stopping once another broker or a wiped state directory took them (default 2 s) */
+  ownershipEveryMs?: number | undefined
   /** where a judge model's key_env is read (default the broker's environment) */
   env?: Record<string, string | undefined> | undefined
   /** the judge model client for a policy's `judge.model` (default the provider's HTTP API) */
@@ -114,6 +116,8 @@ interface Connection {
   process?: string
   /** a one-shot CLI command's connection: its comings and goings are not fleet presence events */
   brief?: boolean
+  /** the endpoint whose wake this connection set: it counts as its waker until it closes or sets none */
+  waker?: string | undefined
   cwd?: string | undefined
   watching: boolean
   closed: boolean
@@ -126,6 +130,7 @@ interface Connection {
 
 const SWEEP_MS = 10 * 60_000
 const PRESENCE_MS = 60_000
+const OWNERSHIP_MS = 2_000
 const OBSERVER_METHODS = new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"])
 const SCOPE_METHODS = new Set([
   "rules",
@@ -219,6 +224,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   let judge!: JudgeGate
   let bridge: Bridge | null = null
   let listener!: Server
+  let socketIno: number | bigint | undefined
   try {
     privateDir(dirname(socket))
     db = openDatabase(join(dir, "relay.db"))
@@ -235,6 +241,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       alive: running,
     })
     core.migrate()
+    core.relabelMachine()
     core.resetConnections()
     core.sweep()
     judge = new JudgeGate({ sql, core, now: options.now ?? Date.now, env: options.env ?? process.env, client: options.judgeClient, log, wake })
@@ -271,6 +278,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     })
     listener.on("error", (error) => log(`relay broker: the socket listener failed: ${error.message}`))
     chmodSync(socket, 0o600)
+    socketIno = lstatSync(socket).ino
   } catch (error) {
     listener?.close()
     db?.close()
@@ -294,6 +302,26 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     }
     for (const id of known.keys()) if (!live.has(id)) known.delete(id)
   }, options.presenceEveryMs ?? PRESENCE_MS)
+  const ownership = setInterval(() => {
+    if (closing || ownsState()) return
+    log(`relay broker: ${socket} or its lock was removed or taken over; stopping`)
+    void stop()
+  }, options.ownershipEveryMs ?? OWNERSHIP_MS)
+  ownership.unref?.()
+
+  /** whether the socket path is still this broker's listener */
+  function ownsSocket(): boolean {
+    return lstatSync(socket, { throwIfNoEntry: false })?.ino === socketIno
+  }
+
+  /** whether the socket path and the lock are still this broker's */
+  function ownsState(): boolean {
+    try {
+      return ownsSocket() && readFileSync(lock.path, "utf8") === lock.content
+    } catch {
+      return false
+    }
+  }
   const remoteHooks: BridgeHooks = {
     wake,
     fleet: notifyFleet,
@@ -399,6 +427,24 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     return core.list({ all: true }).filter((view) => core.machineOf(view.id) === null)
   }
 
+  /** counts `s` as the waker of `endpoint`, or of none, and reports the presence that moves */
+  function setWaker(s: Conn<Connection>, endpoint: string | undefined) {
+    const was = s.data.waker
+    if (was === endpoint) return
+    s.data.waker = endpoint
+    if (was) core.waker(was, false, { grace: s.data.transient === true })
+    if (endpoint) core.waker(endpoint, true)
+    for (const id of [was, endpoint]) if (id) presenceMoved(id)
+  }
+
+  /** reports an endpoint's presence when it is not the one last reported; whether it was not */
+  function presenceMoved(id: string): boolean {
+    const view = core.whoami(id)
+    if ((known.get(id) ?? "offline") === view.presence) return false
+    presenceChanged(view)
+    return true
+  }
+
   /** an endpoint's presence changed outside a connection's own hello or close: watchers and the other machines hear it */
   function presenceChanged(view: EndpointView) {
     known.set(view.id, view.presence)
@@ -583,6 +629,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     s.data.closed = true
     clearTimeout(s.data.lineTimer)
     connections.delete(s)
+    if (!closing) setWaker(s, undefined)
     if (s.data.endpoint && !closing && !s.data.transient && !s.data.lineage) {
       const before = core.whoami(s.data.endpoint).presence
       const settled = core.disconnect(s.data.endpoint, { settle: !s.data.brief })
@@ -891,7 +938,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       case "wake": {
         if (s.data.lineage && !s.data.own) throw new RelayError("unauthorized", "only the endpoint's own session says how it wakes")
         const changed = core.setWake(me, params.via, hookOf(s))
-        if (changed) bridge?.changed(me)
+        setWaker(s, params.via !== "none" && core.whoami(me).wake === params.via ? me : undefined)
+        if (!presenceMoved(me) && changed) bridge?.changed(me)
         return { changed }
       }
       case "rename": {
@@ -996,13 +1044,23 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   /** a send as `from` to local endpoints or, through the bridge, other machines; wakes the recipients and tells the watchers */
   const deliver: Deliver = async (from, send, origin) => {
     let result: SendResult
-    if (remoteSend(core, send.to)) {
+    const remote = remoteSend(core, send.to)
+    if (remote) {
       if (!bridge)
         throw new RelayError("not_found", `no endpoint ${[send.to].flat().join(", ")}: this broker is not linked to a hub (${CLI_NAME} cloud enable)`)
       result = await bridge.forward(from, send, origin)
     } else {
       result = core.send(from, send, origin)
     }
+    if (!result.duplicate && !remote)
+      bridge?.local?.({
+        id: result.id,
+        thread: result.thread,
+        kind: send.kind ?? "message",
+        from,
+        to: result.deliveries.map((d) => d.endpoint),
+        at: (options.now ?? Date.now)(),
+      })
     if (!result.duplicate) {
       for (const delivery of result.deliveries) wake(delivery.endpoint)
       notifyFleet({
@@ -1138,6 +1196,14 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         if (result.handback) {
           const message = core.delivered(spawner, result.handback)!
           wake(spawner)
+          bridge?.local?.({
+            id: message.id,
+            thread: message.thread,
+            kind: "handback",
+            from: message.from.endpoint,
+            to: [spawner],
+            at: (options.now ?? Date.now)(),
+          })
           notifyFleet({
             type: "message",
             id: message.id,
@@ -1192,6 +1258,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       closing = true
       clearInterval(sweeper)
       clearInterval(presenceTimer)
+      clearInterval(ownership)
       await bridge?.stop()
       if (idleTimer) clearTimeout(idleTimer)
       for (const set of [...waiters.values()]) for (const fn of [...set]) fn()
@@ -1199,10 +1266,13 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       while (pending > 0 && Date.now() < deadline) await sleep(5)
       await Promise.race([judge.settled(), sleep(Math.max(0, deadline - Date.now()))])
       for (const s of connections) s.end()
-      listener.close()
-      try {
-        unlinkSync(socket)
-      } catch {}
+      // closing a listener unlinks its path, which another broker may own by now
+      if (ownsSocket()) {
+        listener.close()
+        try {
+          unlinkSync(socket)
+        } catch {}
+      } else listener.unref()
       if (socket !== join(dir, "relay.sock")) {
         try {
           rmdirSync(dirname(socket))

package/src/testing.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite"
 import type { Server, ServerWebSocket } from "bun"
 import { type CrossAccountLink, PASS_GATE, sha256Hex, type Sql, type SqlValue, type XContact } from "@scp-dev/core"
-import { type HubGrant, type HubSocket, RelayHub } from "@scp-dev/hub"
+import { type DashboardEvent, type HubGrant, type HubSocket, RelayHub } from "@scp-dev/hub"
 
 export interface FakeToken {
   tokenId: string
@@ -40,6 +40,8 @@ export function startFakeHubServer(options: {
   tokens: Record<string, FakeToken>
   now?: (() => number) | undefined
   contacts?: [string, string][] | undefined
+  /** receives every account's dashboard events */
+  dashboard?: ((account: string, event: DashboardEvent) => void) | undefined
 }): FakeHubServer {
   const accounts = new Map<string, Account>()
 
@@ -77,6 +79,7 @@ export function startFakeHubServer(options: {
       sockets: () => [...sockets.values()],
       save: () => {},
       ...(options.contacts ? { crossAccount: linkOf(name) } : {}),
+      ...(options.dashboard ? { dashboard: (event: DashboardEvent) => options.dashboard!(name, event) } : {}),
     })
     hub.init({ user: name })
     found = { hub, sockets, traps: new Map() }