@scp-dev/broker 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -10,6 +10,10 @@ interface Hello {
     tty?: boolean;
     /** a hook's connection: it claims like an agent but never counts as connected, and posts only event and status */
     transient?: boolean;
+    /** with `transient`: the session joins the relay on demand, taking `handle` when given */
+    join?: {
+        handle?: string;
+    };
     /** a one-shot command: the broker announces no presence change when it connects or goes */
     brief?: boolean;
     /** no identity: list, status, watch, log and policy only */
@@ -217,11 +221,15 @@ interface Bridge {
     changed(endpoint: string): void;
     /** rules, caps, groups or a title changed, which can touch several endpoints: every mirrored endpoint is sent again */
     resync(): void;
+    /** a local endpoint took another handle: the hub renames its mirror in place, keeping what queued for it */
+    renamed(endpoint: string, was: string): void;
     /** a local endpoint's activity, posted to the hub */
     activity(endpoint: string, row: ActivityRow): void;
     /** the endpoints of other accounts this account's contacts let it reach */
     contacts(): Promise<XListed[]>;
     status(): BridgeStatus;
+    /** reads the credential again and reconnects now, also after the hub revoked or replaced this bridge */
+    relink(): void;
     stop(): Promise<void>;
 }
 /** a WebSocket constructor that takes request headers, as Bun's and Node's do */
@@ -401,6 +409,8 @@ interface BrokerOptions {
     machine?: string | undefined;
     /** the link to the hub; without it the broker never opens a network connection */
     bridge?: BridgeConfig | undefined;
+    /** reads the bridge configuration again for bridge_relink; one that appeared or names another hub or machine restarts the broker */
+    bridgeConfig?: (() => Promise<BridgeConfig | undefined>) | undefined;
     /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
     presenceEveryMs?: number | undefined;
     /** where a judge model's key_env is read (default the broker's environment) */
@@ -419,4 +429,16 @@ interface Broker {
 }
 declare function startBroker(options: BrokerOptions): Promise<Broker>;
 
-export { type Bridge, type BridgeConfig, type BridgeStatus, type Broker, type BrokerInfo, type BrokerOptions, BrokerRunning, BrokerUnavailable, type GrantParams, type GroupParams, type Hello, type HelloResult, MAX_LINE, RelayClient, accountHome, connectBroker, localHostName, policyPath, privateDir, relayDir, relaySocketUrl, shortHostname, socketPath, startBroker, systemHostname, thisHostname };
+/**
+ * What the broker last decided about a harness session, by its session key: whether it joined or left, and the handle it goes by. Hooks and
+ * the MCP shim read it before they claim, so a session that never joined (manual join mode) or left stays off the relay without a broker
+ * round trip, and a renamed session claims its own name. The broker writes it; the endpoint rows stay the source of truth.
+ */
+interface SessionMarker {
+    joined: boolean;
+    handle?: string;
+}
+declare function readSessionMarker(dir: string, session: string): SessionMarker | undefined;
+declare function writeSessionMarker(dir: string, session: string, marker: SessionMarker): void;
+
+export { type Bridge, type BridgeConfig, type BridgeStatus, type Broker, type BrokerInfo, type BrokerOptions, BrokerRunning, BrokerUnavailable, type GrantParams, type GroupParams, type Hello, type HelloResult, MAX_LINE, RelayClient, type SessionMarker, accountHome, connectBroker, localHostName, policyPath, privateDir, readSessionMarker, relayDir, relaySocketUrl, shortHostname, socketPath, startBroker, systemHostname, thisHostname, writeSessionMarker };

package/dist/index.js

@@ -563,6 +563,7 @@ function startBridge(options) {
   let connected = false;
   let ready = false;
   let stopped = false;
+  let shutDown = false;
   let lastError = options.token ? null : options.tokenError ?? "no hub credential; the broker runs local-only";
   let since = (/* @__PURE__ */ new Date()).toISOString();
   let attempt = 0;
@@ -603,7 +604,7 @@ function startBridge(options) {
     });
   }
   function connect() {
-    if (stopped || !token) return;
+    if (stopped || !token || ws) return;
     let socket;
     try {
       socket = new Socket(relaySocketUrl(options.url), { headers: { Authorization: `Bearer ${token}` } });
@@ -680,6 +681,7 @@ function startBridge(options) {
     const hello = await request("hello", { protocol: PROTOCOL2, machine, bridge: true });
     account = hello.account;
     core.setAliases([account]);
+    core.setOthers(account, Array.isArray(hello.others) ? hello.others.filter((name) => typeof name === "string") : []);
     ready = true;
     applyRemote(hello.endpoints, true);
     await Promise.all(fullMirror().map((params) => request("mirror", params)));
@@ -762,7 +764,7 @@ function startBridge(options) {
   function localAddress(address) {
     if (typeof address !== "string" || !account || !address.startsWith(`${account}/`)) return address;
     const rest = address.slice(account.length + 1);
-    return rest.includes("/") ? `${core.user}/${rest}` : `${core.user}/${account}/${rest}`;
+    return rest.includes("/") ? core.remoteAddress(rest) : `${core.user}/${account}/${rest}`;
   }
   function cursor() {
     return inflight.size ? Math.min(...inflight) - 1 : ackedMax;
@@ -795,6 +797,7 @@ function startBridge(options) {
       }
       case "endpoints": {
         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 });
         } catch (error) {
@@ -986,6 +989,17 @@ function startBridge(options) {
     }
     if (mirrored(view)) fireAndForget("mirror", { endpoints: [outward(view)], full: false });
   }
+  function renamed(endpoint, was) {
+    if (!ready) return;
+    let view;
+    try {
+      view = core.whoami(endpoint);
+    } catch {
+      return;
+    }
+    if (mirrored(view)) fireAndForget("mirror", { endpoints: [{ ...outward(view), was }], full: false });
+    else resync();
+  }
   function resync() {
     if (!ready) return;
     let frames;
@@ -1009,8 +1023,19 @@ function startBridge(options) {
   function status() {
     return { enabled: true, machine, url: options.url, connected, last_error: lastError, since };
   }
+  function relink() {
+    if (shutDown) return;
+    stopped = false;
+    attempt = 0;
+    clearTimeout(retryTimer);
+    if (ws) return;
+    void reconnect().then(() => {
+      if (!token && !ws) setState(false, "no hub credential; log in again");
+    });
+  }
   async function stop() {
     stopped = true;
+    shutDown = true;
     clearTimeout(retryTimer);
     for (const fn of waitingForLink.splice(0)) fn();
     const socket = ws;
@@ -1022,15 +1047,15 @@ function startBridge(options) {
     if (socket && socket.readyState <= 1) socket.close(1e3, "the broker stopped");
   }
   connect();
-  return { forward, changed, resync, activity, contacts, status, stop };
+  return { forward, changed, resync, renamed, activity, contacts, status, relink, stop };
 }
 
 // src/server.ts
-import { createHash as createHash2 } from "crypto";
-import { chmodSync as chmodSync2, existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync5, realpathSync, rmdirSync, unlinkSync as unlinkSync2 } from "fs";
+import { createHash as createHash3 } 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";
-import { dirname as dirname2, isAbsolute, join as join3, sep } from "path";
+import { dirname as dirname2, isAbsolute, join as join4, sep } from "path";
 import { setTimeout as sleep2 } from "timers/promises";
 import {
   BROKER_CAPABILITIES,
@@ -1502,6 +1527,34 @@ function heldResult(id, params) {
   return { id, thread: params.thread ?? "", hop: 0, deliveries: [], held: { hold_id: id, side: "local" } };
 }
 
+// src/sessions.ts
+import { createHash as createHash2, 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`);
+}
+function readSessionMarker(dir, session) {
+  try {
+    const value = JSON.parse(readFileSync5(markerPath(dir, session), "utf8"));
+    if (typeof value?.joined !== "boolean") return void 0;
+    return { joined: value.joined, ...typeof value.handle === "string" ? { handle: value.handle } : {} };
+  } catch {
+    return void 0;
+  }
+}
+function writeSessionMarker(dir, session, marker) {
+  const path = markerPath(dir, session);
+  mkdirSync2(join3(dir, "sessions"), { recursive: true, mode: 448 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify(marker), { mode: 384 });
+    renameSync2(temp, path);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+
 // src/sqlite.ts
 import { createRequire } from "module";
 var STATEMENT_CACHE = 512;
@@ -1577,7 +1630,7 @@ function openDatabase(path) {
 // src/server.ts
 var SWEEP_MS = 10 * 6e4;
 var PRESENCE_MS = 6e4;
-var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status"]);
+var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"]);
 var SCOPE_METHODS = /* @__PURE__ */ new Set([
   "rules",
   "rules_set",
@@ -1597,7 +1650,7 @@ var SCOPE_METHODS = /* @__PURE__ */ new Set([
 var CHANGES_SCOPE = /* @__PURE__ */ new Set(["rules_set", "rules_widen", "rules_lift", "group"]);
 var ASK_RECHECK_MS = 1e3;
 var STOP_RECHECK_MS = 1e3;
-var TRANSIENT_METHODS = /* @__PURE__ */ new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted"]);
+var TRANSIENT_METHODS = /* @__PURE__ */ new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted", "title_infer"]);
 var GRANT_UNBOUND = `a spawn-env grant binds only a new harness process: run the harness with it, or name the child (${CLI_NAME} spawn-env --name / --as)`;
 function workerResults(result) {
   return result.messages.length - (result.others_shown ?? 0) + result.more;
@@ -1619,7 +1672,7 @@ function hookOf(s) {
 }
 async function startBroker(options) {
   const dir = privateDir(options.dir);
-  const lock = takeBrokerLock(join3(dir, "broker.lock"));
+  const lock = takeBrokerLock(join4(dir, "broker.lock"));
   const socket = socketPath(dir);
   const connections = /* @__PURE__ */ new Set();
   const waiters = /* @__PURE__ */ new Map();
@@ -1647,16 +1700,16 @@ async function startBroker(options) {
   let listener;
   try {
     privateDir(dirname2(socket));
-    db = openDatabase(join3(dir, "relay.db"));
+    db = openDatabase(join4(dir, "relay.db"));
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA busy_timeout = 5000");
-    chmodSync2(join3(dir, "relay.db"), 384);
+    chmodSync2(join4(dir, "relay.db"), 384);
     const sql = db;
     const machine = options.machine ?? options.bridge?.machine;
     core = new FederatedCore(sql, {
       ...compact({ user: options.user, machine, now: options.now }),
       hostname: shortHostname(),
-      hash: (value) => createHash2("sha256").update(value).digest("hex"),
+      hash: (value) => createHash3("sha256").update(value).digest("hex"),
       transaction: (fn) => db.transaction(fn),
       alive: running
     });
@@ -1712,6 +1765,7 @@ async function startBroker(options) {
   const known = /* @__PURE__ */ new Map();
   for (const view of localViews()) known.set(view.id, view.presence);
   const presenceTimer = setInterval(() => {
+    core.endExited();
     const live = /* @__PURE__ */ new Set();
     for (const view of localViews()) {
       live.add(view.id);
@@ -1734,6 +1788,15 @@ async function startBroker(options) {
       }
     });
   }
+  async function relink() {
+    const config = options.bridgeConfig ? await options.bridgeConfig() : options.bridge;
+    if (!config || bridge && config.url === options.bridge?.url && config.machine === options.bridge?.machine) {
+      bridge?.relink();
+      return bridge?.status() ?? { enabled: false };
+    }
+    setImmediate(() => void stop());
+    return { enabled: false, restarting: true };
+  }
   function activity() {
     if (idleTimer) clearTimeout(idleTimer);
     idleTimer = void 0;
@@ -1742,7 +1805,7 @@ async function startBroker(options) {
   function loadPolicy() {
     let text;
     try {
-      text = readFileSync5(policyFile, "utf8");
+      text = readFileSync6(policyFile, "utf8");
     } catch (error) {
       const code = error.code;
       const dangling = code === "ENOENT" && lstatSync2(policyFile, { throwIfNoEntry: false }) !== void 0;
@@ -1807,6 +1870,20 @@ async function startBroker(options) {
     notifyFleet({ type: "presence", endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels });
     bridge?.changed(view.id);
   }
+  function membership(view, session, joined, was) {
+    const handle = view.address.slice(view.address.lastIndexOf("/") + 1);
+    if (session && !session.startsWith("sub:")) {
+      try {
+        writeSessionMarker(dir, session, { joined, handle });
+      } catch (error) {
+        log(`relay broker: the session marker was not written: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    known.set(view.id, view.presence);
+    notifyFleet({ type: "presence", endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels });
+    if (was !== void 0 && was !== handle) bridge?.renamed(view.id, was);
+    else bridge?.changed(view.id);
+  }
   function notifyFleet(event) {
     const at = new Date((options.now ?? Date.now)()).toISOString();
     let line;
@@ -2060,13 +2137,18 @@ async function startBroker(options) {
         if (params.human === true || params.observe === true || params.resume !== void 0) {
           throw new RelayError4("invalid_params", "a hook connection claims an agent endpoint: transient does not go with human, observe or resume");
         }
-        const before2 = new Map(core.list({ all: true }).map((view) => [view.id, view.presence]));
-        const { endpoint: endpoint2, subagent, created } = core.claim(params.claim ?? {}, { transient: true });
+        const join5 = params.join;
+        if (join5 !== void 0 && (typeof join5 !== "object" || join5 === null || Array.isArray(join5)))
+          throw new RelayError4("invalid_params", "join is {handle?}");
+        const before2 = new Map(core.list({ all: true }).map((view) => [view.id, view]));
+        const { endpoint: endpoint2, subagent, created } = join5 === void 0 ? core.claim(params.claim ?? {}, { transient: true }) : { endpoint: core.joinSession(params.claim ?? {}, join5.handle), subagent: void 0, created: void 0 };
         s.data.endpoint = endpoint2.id;
         s.data.transient = true;
         const key = params.claim?.process;
         if (typeof key === "string") s.data.process = key;
-        if ((before2.get(endpoint2.id) ?? "offline") !== endpoint2.presence) presenceChanged(endpoint2);
+        const was2 = before2.get(endpoint2.id)?.address;
+        if (join5 !== void 0) membership(endpoint2, core.sessionOf(endpoint2.id), true, was2?.slice(was2.lastIndexOf("/") + 1));
+        else if ((before2.get(endpoint2.id)?.presence ?? "offline") !== endpoint2.presence) presenceChanged(endpoint2);
         return {
           endpoint: endpoint2,
           ...subagent ? { subagent, ...created ? { created } : {} } : {},
@@ -2205,6 +2287,22 @@ async function startBroker(options) {
         bridge?.changed(me);
         return view;
       }
+      case "title_infer": {
+        const changed = core.inferTitle(me, params, hookOf(s));
+        if (changed) bridge?.changed(me);
+        return { changed };
+      }
+      case "rename": {
+        const renamed = core.rename(actorOf(s), { ...params.endpoint !== void 0 ? { endpoint: params.endpoint } : {}, handle: params.handle });
+        membership(renamed.endpoint, renamed.session, true, renamed.from);
+        return renamed.endpoint;
+      }
+      case "leave": {
+        const left = core.leaveSession(actorOf(s), params.endpoint !== void 0 ? { endpoint: params.endpoint } : {});
+        for (const c of connections) if (c.data.endpoint === left.endpoint.id && !c.data.transient && !c.data.lineage && c !== s) c.end();
+        membership(left.endpoint, left.session, false);
+        return left.endpoint;
+      }
       case "status": {
         core.status(me, params.state, params.note);
         const view = core.whoami(me);
@@ -2220,14 +2318,25 @@ async function startBroker(options) {
         if ((known.get(me) ?? "offline") !== after.presence) presenceChanged(after);
         return row;
       }
-      case "inject":
-        return core.inject(me, {
+      case "inject": {
+        const waitMs = waitSeconds(params.wait_s);
+        const options2 = {
           stop: params.stop === true,
           count: params.count === true,
           holdUnread: params.hold_unread === true,
           directives: params.directives === true,
+          wake: waitMs > 0 && params.stop !== true && params.count !== true,
           ...hookOf(s)
-        });
+        };
+        const deadline = Date.now() + (options2.wake ? waitMs : 0);
+        let result = core.inject(me, options2);
+        while (!result.offered.length && !s.data.closed && Date.now() < deadline) {
+          await waitFor(me, deadline - Date.now(), s);
+          if (closing) throw new RelayError4("unauthorized", "the relay broker is stopping");
+          result = core.inject(me, options2);
+        }
+        return result;
+      }
       case "stop_wait": {
         const waitMs = waitSeconds(params.wait_s);
         const deadline = Date.now() + waitMs;
@@ -2246,7 +2355,8 @@ async function startBroker(options) {
       case "prompted": {
         const prompted = core.prompted(me, hookOf(s));
         if (prompted) wake(me);
-        return { prompted };
+        const tldr = prompted && typeof params.tldr_every === "number" && core.tldrDue(me, params.tldr_every);
+        return { prompted, ...tldr ? { tldr } : {} };
       }
       case "injected":
         return {
@@ -2335,6 +2445,8 @@ async function startBroker(options) {
       }
       case "cloud_status":
         return bridge?.status() ?? { enabled: false };
+      case "bridge_relink":
+        return relink();
     }
     throw new RelayError4("method_not_found", `no method ${method}`);
   }
@@ -2459,7 +2571,7 @@ async function startBroker(options) {
         unlinkSync2(socket);
       } catch {
       }
-      if (socket !== join3(dir, "relay.sock")) {
+      if (socket !== join4(dir, "relay.sock")) {
         try {
           rmdirSync(dirname2(socket));
         } catch {
@@ -2504,11 +2616,13 @@ export {
   localHostName,
   policyPath,
   privateDir,
+  readSessionMarker,
   relayDir,
   relaySocketUrl,
   shortHostname,
   socketPath,
   startBroker,
   systemHostname,
-  thisHostname
+  thisHostname,
+  writeSessionMarker
 };

package/dist/testing.d.ts

@@ -4,6 +4,8 @@ interface FakeToken {
     tokenId: string;
     /** the account handle the token acts as */
     user: string;
+    /** the org member the token belongs to; none is the personal account's owner */
+    actor?: string;
 }
 interface FakeHubServer {
     /** the http origin, as a bridge's url takes it */

package/dist/testing.js

@@ -50,7 +50,14 @@ function startFakeHubServer(options) {
     if (!token) return null;
     return {
       account: token.user,
-      grant: { tokenId: token.tokenId, userId: `usr_${token.user}`, actorId: null, expiresAt: Date.now() + 36e5, scoped: false, role: null }
+      grant: {
+        tokenId: token.tokenId,
+        userId: `usr_${token.user}`,
+        actorId: token.actor ?? null,
+        expiresAt: Date.now() + 36e5,
+        scoped: false,
+        role: token.actor ? "member" : null
+      }
     };
   }
   const server = Bun.serve({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/broker",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.1",
-    "@scp-dev/hub": "0.1.1"
+    "@scp-dev/core": "0.1.2",
+    "@scp-dev/hub": "0.2.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/bridge.ts

@@ -73,11 +73,15 @@ export interface Bridge {
   changed(endpoint: string): void
   /** rules, caps, groups or a title changed, which can touch several endpoints: every mirrored endpoint is sent again */
   resync(): void
+  /** a local endpoint took another handle: the hub renames its mirror in place, keeping what queued for it */
+  renamed(endpoint: string, was: string): void
   /** a local endpoint's activity, posted to the hub */
   activity(endpoint: string, row: ActivityRow): void
   /** the endpoints of other accounts this account's contacts let it reach */
   contacts(): Promise<XListed[]>
   status(): BridgeStatus
+  /** reads the credential again and reconnects now, also after the hub revoked or replaced this bridge */
+  relink(): void
   stop(): Promise<void>
 }
 
@@ -132,7 +136,9 @@ export function startBridge(options: BridgeOptions): Bridge {
   let connected = false
   /** hello went through on the current socket: deltas may go out */
   let ready = false
+  /** the hub turned this bridge away, or the broker stopped it: no more retries until relink */
   let stopped = false
+  let shutDown = false
   let lastError: string | null = options.token ? null : (options.tokenError ?? "no hub credential; the broker runs local-only")
   let since = new Date().toISOString()
   let attempt = 0
@@ -177,7 +183,7 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   function connect() {
-    if (stopped || !token) return
+    if (stopped || !token || ws) return
     let socket: WebSocket
     try {
       socket = new Socket(relaySocketUrl(options.url), { headers: { Authorization: `Bearer ${token}` } })
@@ -253,9 +259,10 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   async function handshake(socket: WebSocket) {
-    const hello = await request<{ account: string; endpoints: RemoteView[] }>("hello", { protocol: PROTOCOL, machine, bridge: true })
+    const hello = await request<{ account: string; endpoints: RemoteView[]; others?: string[] }>("hello", { protocol: PROTOCOL, machine, bridge: true })
     account = hello.account
     core.setAliases([account])
+    core.setOthers(account, Array.isArray(hello.others) ? hello.others.filter((name): name is string => typeof name === "string") : [])
     ready = true
     applyRemote(hello.endpoints, true)
     await Promise.all(fullMirror().map((params) => request("mirror", params)))
@@ -350,7 +357,7 @@ export function startBridge(options: BridgeOptions): Bridge {
   function localAddress(address: unknown): unknown {
     if (typeof address !== "string" || !account || !address.startsWith(`${account}/`)) return address
     const rest = address.slice(account.length + 1)
-    return rest.includes("/") ? `${core.user}/${rest}` : `${core.user}/${account}/${rest}`
+    return rest.includes("/") ? core.remoteAddress(rest) : `${core.user}/${account}/${rest}`
   }
 
   /** the lowest seq a fresh subscribe must replay from: every delivery at or below it was acked */
@@ -387,6 +394,7 @@ export function startBridge(options: BridgeOptions): Bridge {
       }
       case "endpoints": {
         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 })
         } catch (error) {
@@ -597,6 +605,18 @@ export function startBridge(options: BridgeOptions): Bridge {
     if (mirrored(view)) fireAndForget("mirror", { endpoints: [outward(view)], full: false })
   }
 
+  function renamed(endpoint: string, was: string) {
+    if (!ready) return
+    let view: EndpointView
+    try {
+      view = core.whoami(endpoint)
+    } catch {
+      return
+    }
+    if (mirrored(view)) fireAndForget("mirror", { endpoints: [{ ...outward(view), was }], full: false })
+    else resync()
+  }
+
   function resync() {
     if (!ready) return
     let frames: ReturnType<typeof fullMirror>
@@ -624,8 +644,20 @@ export function startBridge(options: BridgeOptions): Bridge {
     return { enabled: true, machine, url: options.url, connected, last_error: lastError, since }
   }
 
+  function relink() {
+    if (shutDown) return
+    stopped = false
+    attempt = 0
+    clearTimeout(retryTimer)
+    if (ws) return
+    void reconnect().then(() => {
+      if (!token && !ws) setState(false, "no hub credential; log in again")
+    })
+  }
+
   async function stop() {
     stopped = true
+    shutDown = true
     clearTimeout(retryTimer)
     for (const fn of waitingForLink.splice(0)) fn()
     const socket = ws
@@ -638,5 +670,5 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   connect()
-  return { forward, changed, resync, activity, contacts, status, stop }
+  return { forward, changed, resync, renamed, activity, contacts, status, relink, stop }
 }

package/src/client.ts

@@ -31,6 +31,8 @@ export interface Hello {
   tty?: boolean
   /** a hook's connection: it claims like an agent but never counts as connected, and posts only event and status */
   transient?: boolean
+  /** with `transient`: the session joins the relay on demand, taking `handle` when given */
+  join?: { handle?: string }
   /** a one-shot command: the broker announces no presence change when it connects or goes */
   brief?: boolean
   /** no identity: list, status, watch, log and policy only */

package/src/index.ts

@@ -4,3 +4,4 @@ export { BrokerRunning } from "./lock"
 export { MAX_LINE } from "./ndjson"
 export { accountHome, localHostName, policyPath, privateDir, relayDir, shortHostname, socketPath, systemHostname, thisHostname } from "./paths"
 export { startBroker, type Broker, type BrokerOptions } from "./server"
+export { readSessionMarker, type SessionMarker, writeSessionMarker } from "./sessions"

package/src/server.ts

@@ -31,6 +31,7 @@ import { type Deliver, type JudgeClientFactory, JudgeGate } from "./judge-gate"
 import { releaseBrokerLock, takeBrokerLock } from "./lock"
 import { encodeLine, LineReader, LineWriter, MAX_LINE } from "./ndjson"
 import { accountHome, accountHomeVerified, policyPath as defaultPolicyPath, privateDir, shortHostname, socketPath } from "./paths"
+import { writeSessionMarker } from "./sessions"
 import { Conn } from "./socket"
 import { type Database, openDatabase } from "./sqlite"
 
@@ -57,6 +58,8 @@ export interface BrokerOptions {
   machine?: string | undefined
   /** the link to the hub; without it the broker never opens a network connection */
   bridge?: BridgeConfig | undefined
+  /** reads the bridge configuration again for bridge_relink; one that appeared or names another hub or machine restarts the broker */
+  bridgeConfig?: (() => Promise<BridgeConfig | undefined>) | undefined
   /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
   presenceEveryMs?: number | undefined
   /** where a judge model's key_env is read (default the broker's environment) */
@@ -110,7 +113,7 @@ interface Connection {
 
 const SWEEP_MS = 10 * 60_000
 const PRESENCE_MS = 60_000
-const OBSERVER_METHODS = new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status"])
+const OBSERVER_METHODS = new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"])
 const SCOPE_METHODS = new Set([
   "rules",
   "rules_set",
@@ -132,7 +135,7 @@ const CHANGES_SCOPE = new Set(["rules_set", "rules_widen", "rules_lift", "group"
 const ASK_RECHECK_MS = 1000
 /** how often a waiting stop rechecks its workers, since a worker's exit or lapse wakes no one */
 const STOP_RECHECK_MS = 1000
-const TRANSIENT_METHODS = new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted"])
+const TRANSIENT_METHODS = new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted", "title_infer"])
 const GRANT_UNBOUND = `a spawn-env grant binds only a new harness process: run the harness with it, or name the child (${CLI_NAME} spawn-env --name / --as)`
 
 /** the workers' messages and handbacks a stop's push would show, and those of theirs left unread past it */
@@ -258,6 +261,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   const known = new Map<string, Presence>()
   for (const view of localViews()) known.set(view.id, view.presence)
   const presenceTimer = setInterval(() => {
+    core.endExited()
     const live = new Set<string>()
     for (const view of localViews()) {
       live.add(view.id)
@@ -281,6 +285,17 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     })
   }
 
+  /** links the bridge again with the credential on disk; a configuration this broker cannot take without a restart stops it */
+  async function relink(): Promise<object> {
+    const config = options.bridgeConfig ? await options.bridgeConfig() : options.bridge
+    if (!config || (bridge && config.url === options.bridge?.url && config.machine === options.bridge?.machine)) {
+      bridge?.relink()
+      return bridge?.status() ?? { enabled: false }
+    }
+    setImmediate(() => void stop())
+    return { enabled: false, restarting: true }
+  }
+
   function activity() {
     if (idleTimer) clearTimeout(idleTimer)
     idleTimer = undefined
@@ -370,6 +385,22 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     bridge?.changed(view.id)
   }
 
+  /** after a join, rename or leave: the session's marker, the fleet and the hub's mirror learn it; `was` is the handle before */
+  function membership(view: EndpointView, session: string | null, joined: boolean, was?: string) {
+    const handle = view.address.slice(view.address.lastIndexOf("/") + 1)
+    if (session && !session.startsWith("sub:")) {
+      try {
+        writeSessionMarker(dir, session, { joined, handle })
+      } catch (error) {
+        log(`relay broker: the session marker was not written: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+    known.set(view.id, view.presence)
+    notifyFleet({ type: "presence", endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels })
+    if (was !== undefined && was !== handle) bridge?.renamed(view.id, was)
+    else bridge?.changed(view.id)
+  }
+
   function notifyFleet(event: Record<string, unknown>) {
     const at = new Date((options.now ?? Date.now)()).toISOString()
     let line: Uint8Array | undefined
@@ -664,13 +695,21 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         if (params.human === true || params.observe === true || params.resume !== undefined) {
           throw new RelayError("invalid_params", "a hook connection claims an agent endpoint: transient does not go with human, observe or resume")
         }
-        const before = new Map(core.list({ all: true }).map((view) => [view.id, view.presence]))
-        const { endpoint, subagent, created } = core.claim((params.claim ?? {}) as Claim, { transient: true })
+        const join = params.join
+        if (join !== undefined && (typeof join !== "object" || join === null || Array.isArray(join)))
+          throw new RelayError("invalid_params", "join is {handle?}")
+        const before = new Map(core.list({ all: true }).map((view) => [view.id, view]))
+        const { endpoint, subagent, created } =
+          join === undefined
+            ? core.claim((params.claim ?? {}) as Claim, { transient: true })
+            : { endpoint: core.joinSession((params.claim ?? {}) as Claim, (join as { handle?: unknown }).handle), subagent: undefined, created: undefined }
         s.data.endpoint = endpoint.id
         s.data.transient = true
         const key = (params.claim as Claim | undefined)?.process
         if (typeof key === "string") s.data.process = key
-        if ((before.get(endpoint.id) ?? "offline") !== endpoint.presence) presenceChanged(endpoint)
+        const was = before.get(endpoint.id)?.address
+        if (join !== undefined) membership(endpoint, core.sessionOf(endpoint.id), true, was?.slice(was.lastIndexOf("/") + 1))
+        else if ((before.get(endpoint.id)?.presence ?? "offline") !== endpoint.presence) presenceChanged(endpoint)
         return {
           endpoint,
           ...(subagent ? { subagent, ...(created ? { created } : {}) } : {}),
@@ -809,6 +848,22 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         bridge?.changed(me)
         return view
       }
+      case "title_infer": {
+        const changed = core.inferTitle(me, params, hookOf(s))
+        if (changed) bridge?.changed(me)
+        return { changed }
+      }
+      case "rename": {
+        const renamed = core.rename(actorOf(s), { ...(params.endpoint !== undefined ? { endpoint: params.endpoint } : {}), handle: params.handle })
+        membership(renamed.endpoint, renamed.session, true, renamed.from)
+        return renamed.endpoint
+      }
+      case "leave": {
+        const left = core.leaveSession(actorOf(s), params.endpoint !== undefined ? { endpoint: params.endpoint } : {})
+        for (const c of connections) if (c.data.endpoint === left.endpoint.id && !c.data.transient && !c.data.lineage && c !== s) c.end()
+        membership(left.endpoint, left.session, false)
+        return left.endpoint
+      }
       case "status": {
         core.status(me, params.state, params.note)
         const view = core.whoami(me)
@@ -824,14 +879,25 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         if ((known.get(me) ?? "offline") !== after.presence) presenceChanged(after)
         return row
       }
-      case "inject":
-        return core.inject(me, {
+      case "inject": {
+        const waitMs = waitSeconds(params.wait_s)
+        const options = {
           stop: params.stop === true,
           count: params.count === true,
           holdUnread: params.hold_unread === true,
           directives: params.directives === true,
+          wake: waitMs > 0 && params.stop !== true && params.count !== true,
           ...hookOf(s),
-        })
+        }
+        const deadline = Date.now() + (options.wake ? waitMs : 0)
+        let result = core.inject(me, options)
+        while (!result.offered.length && !s.data.closed && Date.now() < deadline) {
+          await waitFor(me, deadline - Date.now(), s)
+          if (closing) throw new RelayError("unauthorized", "the relay broker is stopping")
+          result = core.inject(me, options)
+        }
+        return result
+      }
       case "stop_wait": {
         const waitMs = waitSeconds(params.wait_s)
         const deadline = Date.now() + waitMs
@@ -850,7 +916,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       case "prompted": {
         const prompted = core.prompted(me, hookOf(s))
         if (prompted) wake(me)
-        return { prompted }
+        const tldr = prompted && typeof params.tldr_every === "number" && core.tldrDue(me, params.tldr_every)
+        return { prompted, ...(tldr ? { tldr } : {}) }
       }
       case "injected":
         return {
@@ -948,6 +1015,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       }
       case "cloud_status":
         return bridge?.status() ?? { enabled: false }
+      case "bridge_relink":
+        return relink()
     }
     throw new RelayError("method_not_found", `no method ${method}`)
   }

package/src/sessions.ts

@@ -0,0 +1,39 @@
+import { createHash, randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * What the broker last decided about a harness session, by its session key: whether it joined or left, and the handle it goes by. Hooks and
+ * the MCP shim read it before they claim, so a session that never joined (manual join mode) or left stays off the relay without a broker
+ * round trip, and a renamed session claims its own name. The broker writes it; the endpoint rows stay the source of truth.
+ */
+export interface SessionMarker {
+  joined: boolean
+  handle?: string
+}
+
+function markerPath(dir: string, session: string): string {
+  return join(dir, "sessions", `${createHash("sha256").update(session).digest("hex").slice(0, 32)}.json`)
+}
+
+export function readSessionMarker(dir: string, session: string): SessionMarker | undefined {
+  try {
+    const value = JSON.parse(readFileSync(markerPath(dir, session), "utf8")) as Partial<SessionMarker>
+    if (typeof value?.joined !== "boolean") return undefined
+    return { joined: value.joined, ...(typeof value.handle === "string" ? { handle: value.handle } : {}) }
+  } catch {
+    return undefined
+  }
+}
+
+export function writeSessionMarker(dir: string, session: string, marker: SessionMarker): void {
+  const path = markerPath(dir, session)
+  mkdirSync(join(dir, "sessions"), { recursive: true, mode: 0o700 })
+  const temp = `${path}.${randomUUID()}.tmp`
+  try {
+    writeFileSync(temp, JSON.stringify(marker), { mode: 0o600 })
+    renameSync(temp, path)
+  } finally {
+    rmSync(temp, { force: true })
+  }
+}

package/src/testing.ts

@@ -7,6 +7,8 @@ export interface FakeToken {
   tokenId: string
   /** the account handle the token acts as */
   user: string
+  /** the org member the token belongs to; none is the personal account's owner */
+  actor?: string
 }
 
 export interface FakeHubServer {
@@ -88,7 +90,14 @@ export function startFakeHubServer(options: {
     if (!token) return null
     return {
       account: token.user,
-      grant: { tokenId: token.tokenId, userId: `usr_${token.user}`, actorId: null, expiresAt: Date.now() + 3_600_000, scoped: false, role: null },
+      grant: {
+        tokenId: token.tokenId,
+        userId: `usr_${token.user}`,
+        actorId: token.actor ?? null,
+        expiresAt: Date.now() + 3_600_000,
+        scoped: false,
+        role: token.actor ? "member" : null,
+      },
     }
   }