@staix/agent-hub 0.31.0 → 0.32.0

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -93,7 +93,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -117,7 +117,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -132,7 +132,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -243,7 +243,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -291,7 +291,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "4ad77748c96383bdef8e55a11ff53808a1359500",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -320,7 +320,7 @@
       ]
     },
     "docs/agent-notes/README.md": {
-      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
+      "verifiedAgainst": "2f4c372a6ce48dc01acb4a002f6a46e9557cbd17",
       "paths": [
         "src/cli/console-state.ts",
         "src/cli/attention.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -10248,7 +10248,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@staix/agent-hub",
-    version: "0.31.0",
+    version: "0.32.0",
     description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
     license: "MIT",
     type: "module",

package/src/cli/console-state.ts

@@ -1031,7 +1031,7 @@ function roomDetail(row: RoomStatusView): Record<string, unknown> {
   return {
     room: row.name, "room id": row.room, "link state": row.link ?? "unknown", owner: row.owner, "local member": row.member,
     "member count": count(row.memberCount),
-    "remote peers": row.remotePeers === null ? "unknown" : row.remotePeers.length ? row.remotePeers.map(peer => `${peer.id} (${peer.state})`) : "0",
+    "remote peers": row.remotePeers === null ? "unknown" : row.remotePeers.length ? row.remotePeers.map(peer => `${peer.id} (${peer.presence ?? peer.state})${peer.liveness === "untracked" ? "; liveness not tracked (broker without ephemeral); upgrade the broker to track liveness" : ""}`) : "0",
     "counter scope": `since daemon start: ${since}`,
     "out handoff": count(relays?.outbound), "in admitted": count(relays?.inbound), withheld: count(relays?.withheld),
   };

package/src/cli/room.ts

@@ -2,7 +2,7 @@ import { decodeBase64url } from "../rooms/crypto.ts";
 import { roomReceiptReasonText, type RoomReceiptReason } from "../rooms/application.ts";
 import { frame, type Envelope } from "../hub/envelope.ts";
 import { terminalText } from "./console-state.ts";
-import type { RoomPersonInboxMeta, RoomPersonInboxItem } from "../rooms/store.ts";
+import { ROOM_STORE_LIMITS, type RoomPersonInboxMeta, type RoomPersonInboxItem } from "../rooms/store.ts";
 /** Membership mutations and inbox forms are person-only; main.ts refuses agent/live-test calls before importing this module. */
 export const ROOM_USAGE = "usage: ahub room create <name> --broker <url> [--label <id>] | invite <name> [--accept <request>] | join <token> [--name <name>] [--label <id>] | join <name> --roster <signed-roster> | leave <name> | revoke <name> <fingerprint> | expose <name> [<peer>...] | resolve <name> --frame <digest> --action accept|discard (membership mutations and resolve require TTY y/N or --confirm <member-fingerprint-prefix>, 16..64 lowercase hex) | list [--json] | status [<name>] [--json] | inbox [<name>] [--json] | inbox show|done|discard <id>";
 
@@ -17,8 +17,9 @@ export type RoomRequest = (message: Record<string, unknown>) => Promise<any>;
 export interface RoomConfirmationIO { isTTY(): boolean; answer(prompt: string): Promise<string> }
 
 export class RoomCliError extends Error {
-  constructor(readonly code: "usage" | "refused" | "invalid_reply" | "inbox_list_limit" | "confirmation_required" | "not_confirmed" | "confirmation_mismatch") {
-    const message = { refused: "operation refused", invalid_reply: "invalid control reply", inbox_list_limit: "inbox list exceeds the limit; choose a room name", confirmation_required: "confirmation required; use a TTY or --confirm with the member fingerprint prefix", not_confirmed: "not confirmed; nothing executed", confirmation_mismatch: "confirmation does not match the member fingerprint; nothing executed" };
+  constructor(readonly code: "usage" | "refused" | "invalid_reply" | "inbox_list_limit" | "confirmation_required" | "not_confirmed" | "confirmation_mismatch" | "epoch_rotated_hold_unavailable") {
+    const message = { refused: "operation refused", invalid_reply: "invalid control reply", inbox_list_limit: "inbox list exceeds the limit; choose a room name", confirmation_required: "confirmation required; use a TTY or --confirm with the member fingerprint prefix", not_confirmed: "not confirmed; nothing executed", confirmation_mismatch: "confirmation does not match the member fingerprint; nothing executed",
+      epoch_rotated_hold_unavailable: "epoch rotated but delivery journal holds are unavailable; inspect ahub room status and ahub queue show before another mutation" };
     super(code === "usage" ? ROOM_USAGE : `room: ${message[code]}`);
     this.name = "RoomCliError";
   }
@@ -141,9 +142,9 @@ async function confirmMember(member: string, explicit: string | undefined, io: R
 }
 
 type DeliveryState = "pending" | "dispatching" | "accepted" | "completed" | "completed (admitted)" | "completed (inbox)" | "failed_safe" | "needs_review" | "disposed" | "disposed (accept, by person)" | "disposed (discard, by person)";
-interface DeliveryRow { direction: "inbound" | "outbound"; id: string; application: string; peer: string; state: DeliveryState; disposition?: "accept" | "completed" | "retry" | "discard"; lateReceipt?: "completed (admitted)" | "completed (inbox)" | "failed_safe"; refusalReason?: RoomReceiptReason }
+interface DeliveryRow { direction: "inbound" | "outbound"; id: string; application: string; peer: string; state: DeliveryState; disposition?: "accept" | "completed" | "retry" | "discard"; lateReceipt?: "completed (admitted)" | "completed (inbox)" | "failed_safe"; refusalReason?: RoomReceiptReason; holdReason?: "epoch rotated" }
 interface DeliverySummary { direction: "inbound"; pending: number; needsReview: number; truncated: boolean }
-interface RemotePeerRow { id: string; state: "idle" | "busy" | "paused" | "offline" }
+interface RemotePeerRow { id: string; state: "idle" | "busy" | "paused" | "offline"; presence?: "idle" | "busy" | "paused" | "offline" | "unknown"; liveness?: "untracked" }
 interface RoomRow { name: string; room: string; owner: string; member: string; epoch: string; state: string; deliveries?: (DeliveryRow | DeliverySummary)[]; remotePeers?: RemotePeerRow[] }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const REMOTE_ID = /^[a-z][a-z0-9-]{0,31}@[a-z][a-z0-9-]{0,31}$/;
@@ -170,10 +171,11 @@ function deliveryRows(value: unknown): (DeliveryRow | DeliverySummary)[] {
     if (row.disposition !== undefined && (typeof row.disposition !== "string" || (row.direction === "inbound" ? !["accept", "discard"].includes(row.disposition) : !["completed", "retry", "discard"].includes(row.disposition)))) return fail("invalid_reply");
     if (row.lateReceipt !== undefined && row.lateReceipt !== "completed (admitted)" && row.lateReceipt !== "completed (inbox)" && row.lateReceipt !== "failed_safe") return fail("invalid_reply");
     if (row.refusalReason !== undefined && (typeof row.refusalReason !== "string" || !REFUSAL_REASONS.includes(row.refusalReason as RoomReceiptReason))) return fail("invalid_reply");
+    if (row.holdReason !== undefined && (row.holdReason !== "epoch rotated" || row.direction !== "outbound" || row.state !== "needs_review")) return fail("invalid_reply");
     if (row.direction === "outbound" && row.state.startsWith("disposed")) return fail("invalid_reply");
     const state = row.state === "completed" ? row.refusalReason === "inbox_admitted" ? "completed (inbox)" : "completed (admitted)" : row.state === "disposed" && row.disposition !== undefined ? `disposed (${row.disposition}, by person)` as DeliveryState : row.state as DeliveryState;
     return { direction: row.direction, id: row.id, application: row.application, peer: row.peer, state,
-      ...(row.disposition !== undefined ? { disposition: row.disposition as DeliveryRow["disposition"] } : {}), ...(row.lateReceipt !== undefined ? { lateReceipt: row.lateReceipt as DeliveryRow["lateReceipt"] } : {}), ...(row.refusalReason !== undefined ? { refusalReason: row.refusalReason as RoomReceiptReason } : {}) };
+      ...(row.disposition !== undefined ? { disposition: row.disposition as DeliveryRow["disposition"] } : {}), ...(row.lateReceipt !== undefined ? { lateReceipt: row.lateReceipt as DeliveryRow["lateReceipt"] } : {}), ...(row.refusalReason !== undefined ? { refusalReason: row.refusalReason as RoomReceiptReason } : {}), ...(row.holdReason === "epoch rotated" ? { holdReason: "epoch rotated" } : {}) };
   });
 }
 function remotePeerRows(value: unknown): RemotePeerRow[] {
@@ -181,7 +183,9 @@ function remotePeerRows(value: unknown): RemotePeerRow[] {
   return value.map<RemotePeerRow>(item => {
     const row = record(item);
     if (typeof row.id !== "string" || !REMOTE_ID.test(row.id) || typeof row.state !== "string" || !["idle", "busy", "paused", "offline"].includes(row.state)) return fail("invalid_reply");
-    return { id: row.id, state: row.state as RemotePeerRow["state"] };
+    if (row.presence !== undefined && (typeof row.presence !== "string" || !["idle", "busy", "paused", "offline", "unknown"].includes(row.presence))) return fail("invalid_reply");
+    if (row.liveness !== undefined && row.liveness !== "untracked") return fail("invalid_reply");
+    return { id: row.id, state: row.state as RemotePeerRow["state"], ...(row.presence !== undefined ? { presence: row.presence as RemotePeerRow["presence"] } : {}), ...(row.liveness === "untracked" ? { liveness: "untracked" as const } : {}) };
   });
 }
 function record(value: unknown): Record<string, unknown> {
@@ -190,7 +194,7 @@ function record(value: unknown): Record<string, unknown> {
 }
 function success(value: unknown): Record<string, unknown> {
   const row = record(value);
-  if (row.ok !== true) fail("refused");
+  if (row.ok !== true) fail(row.code === "epoch_rotated_hold_unavailable" ? "epoch_rotated_hold_unavailable" : "refused");
   return row;
 }
 function roomRows(value: unknown): RoomRow[] {
@@ -270,10 +274,10 @@ export async function runRoomCommand(args: readonly string[], request: RoomReque
     console.log(`Rooms (${rows.length})`);
     for (const row of rows) {
       console.log(`${row.name} ${row.room} epoch ${row.epoch} ${row.state}\n  owner ${row.owner}\n  member ${row.member}`);
-      for (const peer of row.remotePeers ?? []) console.log(`  peer ${peer.id}: ${peer.state}`);
+      for (const peer of row.remotePeers ?? []) console.log(`  peer ${peer.id}: ${peer.presence ?? peer.state}${peer.liveness === "untracked" ? "; liveness not tracked (broker without ephemeral); upgrade the broker to track liveness" : ""}`);
       for (const delivery of row.deliveries ?? []) {
         if (!("id" in delivery)) console.log(`  inbound: pending ${delivery.pending}, needs_review ${delivery.needsReview}${delivery.truncated ? "; truncated" : ""}`);
-        else console.log(`  ${delivery.direction} ${delivery.id}: ${delivery.state}; application ${delivery.application}; peer ${delivery.peer}${delivery.disposition ? `; person disposition ${delivery.disposition}` : ""}${delivery.lateReceipt ? `; late receipt evidence ${delivery.lateReceipt}` : ""}${delivery.refusalReason ? `; refusal ${roomReceiptReasonText(delivery.refusalReason)}` : ""}`);
+        else console.log(`  ${delivery.direction} ${delivery.id}: ${delivery.state}; application ${delivery.application}; peer ${delivery.peer}${delivery.disposition ? `; person disposition ${delivery.disposition}` : ""}${delivery.lateReceipt ? `; late receipt evidence ${delivery.lateReceipt}` : ""}${delivery.refusalReason ? `; refusal ${roomReceiptReasonText(delivery.refusalReason)}` : ""}${delivery.holdReason ? "; reason epoch rotated; inspect ahub queue show before resolving" : ""}`);
       }
     }
     return;
@@ -283,6 +287,12 @@ export async function runRoomCommand(args: readonly string[], request: RoomReque
     || typeof preview.ticket !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(preview.ticket)) fail("invalid_reply");
   console.log(`Owner fingerprint: ${preview.owner}`);
   console.log(`Member fingerprint: ${preview.member}`);
+  if (preview.outstanding !== undefined) {
+    if (!Array.isArray(preview.outstanding) || preview.outstanding.length > ROOM_STORE_LIMITS.outboxPerRoom
+      || preview.outstanding.some(value => typeof value !== "string" || !UUID.test(value)) || new Set(preview.outstanding).size !== preview.outstanding.length) fail("invalid_reply");
+    console.log(`Outstanding deliveries on the old epoch (${preview.outstanding.length}):`);
+    for (const id of preview.outstanding) console.log(`  ${id}`);
+  }
   const confirm = await confirmMember(preview.member, command.confirm, io);
   const result = success(await request({ t: "room", op: "execute", ticket: preview.ticket, confirm }));
   if (result.name !== undefined) {

package/src/hub/bus.ts

@@ -161,6 +161,7 @@ export const NOTES_KEPT = 10;
  * it holds an `important` envelope, or `batchMax` envelopes, or its oldest one has waited `batchMs`.
  */
 export const ROOM_PROOF_UNAVAILABLE_REASON = "room delivery proof unavailable; inspect ahub queue show";
+export const ROOM_EPOCH_ROTATED_REASON = "room epoch rotated; inspect ahub queue show";
 
 export class Bus {
   readonly peers = new Map<PeerId, PeerAdapter>();
@@ -1367,6 +1368,23 @@ export class Bus {
     return this.holdRemoteDeliveryMetadata(peerId, row, `room recipient proof no longer current after restart; inspect ahub queue show ${deliveryId}`);
   }
 
+  /** Person-authorized epoch change: hold metadata only, without cancellation, replay or completion. */
+  holdRemoteEpochRotated(peerId: string, deliveryId: string, expectedRoom: string, expectedMember: string, currentGuard: () => boolean): boolean {
+    if (!parseRemotePeerId(peerId) || typeof expectedRoom !== "string" || !expectedRoom || !remoteFingerprint(expectedMember)
+      || !this.journal || this.storageError || this.closed
+      || this.remoteQueueRooms.get(peerId) !== expectedRoom || this.remoteQueueMembers.get(peerId) !== expectedMember) return false;
+    const row = this.journal.get(deliveryId), reason = `${ROOM_EPOCH_ROTATED_REASON} ${deliveryId}`;
+    if (!row || row.peer !== peerId || row.originals.length !== 1 || row.originals[0]?.to?.includes(peerId) !== true
+      || this.journal.resolution(deliveryId)) return false;
+    const active = this.activeDeliveries.get(deliveryId), transport = this.remoteTransport.get(deliveryId)?.peer;
+    if (active !== undefined && active !== peerId || transport !== undefined && transport !== peerId) return false;
+    if (!["dispatching", "accepted", "needs_review"].includes(row.state)) return false;
+    if (row.state === "needs_review" && row.reason !== reason && row.reason !== `${ROOM_PROOF_UNAVAILABLE_REASON} ${deliveryId}`) return false;
+    try { if (currentGuard() !== true) return false; } catch { return false; }
+    if (row.state === "needs_review" && row.reason === reason) return true;
+    return this.holdRemoteDeliveryMetadata(peerId, row, reason);
+  }
+
   /** Resume the same delivery after the host revalidates its durable outbox proof. */
   resumeRemotePending(source: PeerAdapter, deliveryId: string, state: "dispatching" | "accepted" | "needs_review", currentGuard: () => boolean): boolean {
     const peer = source.id;

package/src/hub/daemon.ts

@@ -4,7 +4,7 @@ import { readSdlcPr } from "./sdlc.ts";
 import type { ActionMeta } from "@staix/agent-console/contract";
 import { isReviewObserverExcluded, reviewCaptureExcluded } from "./memory-policy.ts";
 import { RoomStoreError } from "../rooms/store.ts";
-import { RoomCommands, type RoomPreview } from "../rooms/commands.ts";
+import { RoomCommands, RoomRotationHoldError, type RoomPreview } from "../rooms/commands.ts";
 import { queueBackpressurePolicy, type QueueBackpressurePolicy } from "./queue-backpressure.ts";
 import { RoomChat, type RoomInvocationIngress } from "../rooms/service.ts";
 import { RoomInvocations, roomInvocationHash } from "./room-invocations.ts";
@@ -10788,7 +10788,9 @@ export async function startDaemon(opts: DaemonOptions) {
         const personRoom = c.role === "console";
         const roomCurrent = () => !stopping && !recoveryActive() && !bus.isRecoveryHeld
           && sock.data === client && sock.readyState === WebSocket.OPEN && personRoom;
-        const roomFailure = () => reply({ ok: false, error: "room operation refused; check room state, authority and arguments" });
+        const roomFailure = (error?: unknown) => error instanceof RoomRotationHoldError
+          ? reply({ ok: false, code: "epoch_rotated_hold_unavailable", error: error.message })
+          : reply({ ok: false, error: "room operation refused; check room state, authority and arguments" });
         if (msg.op === "list" || msg.op === "status") {
           if (msg.input !== undefined && (!msg.input || typeof msg.input !== "object" || Array.isArray(msg.input)
             || Object.keys(msg.input).some(key => key !== "name") || (msg.input.name !== undefined && typeof msg.input.name !== "string"))) return roomFailure();
@@ -10831,7 +10833,7 @@ export async function startDaemon(opts: DaemonOptions) {
             if (!roomCurrent()) return roomFailure();
             const ticket = crypto.randomUUID();
             roomTickets.set(sock, { id: ticket, expires: Date.now() + 30_000, preview });
-            reply({ ok: true, owner: preview.owner, member: preview.member, ticket });
+            reply({ ok: true, owner: preview.owner, member: preview.member, ticket, ...(preview.outstanding ? { outstanding: preview.outstanding } : {}) });
           }, roomFailure);
           return;
         }
@@ -11312,7 +11314,7 @@ export async function startDaemon(opts: DaemonOptions) {
   async function stopOnce(): Promise<void> {
     stopping = true;
     controlWriteTelemetry?.stop();
-    roomCommands.stop();
+    const roomsStopped = roomCommands.stop().catch(() => { log("room shutdown failed; inspect ahub room status after restart"); });
     tasks.stopQueuePressureRechecks();
     const studiesStopped = tasks.stopStudies();
     const reviewCommentsStopped = tasks.stopReviewComments();
@@ -11346,7 +11348,7 @@ export async function startDaemon(opts: DaemonOptions) {
         await Promise.race([Promise.all([schedulesPass?.catch(() => undefined), ...manualSchedulePasses, studiesStopped, reviewCommentsStopped]), new Promise<void>(resolve => { timer = setTimeout(resolve, 5_000); timer.unref?.(); })]);
         clearTimeout(timer);
       }
-      await Promise.all([terminalReadsStopped, codeFactsStopped, implementerShellStopped]);
+      await Promise.all([terminalReadsStopped, codeFactsStopped, implementerShellStopped, roomsStopped]);
       await terminalLaunches.settled();
       // A peer can still be inside memory recall or its native handshake when kill arrives.
       // Drain those starts before taking the final owned-process snapshot.

package/src/rooms/commands.ts

@@ -3,14 +3,17 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { assertRoomCryptoReady, decodeBase64url, encodeBase64url, signBytes, verifyBytes } from "./crypto.ts";
 import { acceptRoomEpoch, brokerUrl, canonicalBytes, createInvite, createJoin, createRoomEpoch, decodeInvite, decodeJoin, decodeRoster, roomMembers } from "./wire.ts";
-import { RoomStore, type RoomState, type RoomPersonInboxMeta, type RoomPersonInboxItem } from "./store.ts";
+import { RoomStore, type RoomState, type RoomPersonInboxMeta, type RoomPersonInboxItem, type RoomOutgoing } from "./store.ts";
 import { RoomLink } from "./link.ts";
 import { exposedPeers, roomName, RoomPolicy } from "./policy.ts";
 import type { RoomChat } from "./service.ts";
 import { projectRoomStatus, type RoomStatusView } from "./status.ts";
 
 export interface RoomCommandResult { kind?: string; artifact?: string; name?: string; room?: string; owner?: string; member?: string }
-export interface RoomPreview { owner: string; member: string; commit: () => Promise<RoomCommandResult> }
+export interface RoomPreview { owner: string; member: string; outstanding?: readonly string[]; commit: () => Promise<RoomCommandResult> }
+export class RoomRotationHoldError extends Error {
+  constructor() { super("room epoch rotated but delivery journal holds are unavailable; inspect ahub room status and ahub queue show before another mutation"); this.name = "RoomRotationHoldError"; }
+}
 const FP = /^[0-9a-f]{64}$/;
 function refuse(code: string): never { throw new Error(`room: ${code}`); }
 function fields(input: unknown, keys: string[], optional: string[] = []): Record<string, any> {
@@ -47,9 +50,10 @@ export class RoomCommands {
   private pending?: Promise<RoomStore>;
   private store?: RoomStore;
   private stopped = false;
+  private stopWork?: Promise<void>;
   private readonly links = new Map<string, RoomLink>();
   private readonly policy: RoomPolicy;
-  constructor(private readonly options: { stateDir: string; cwd: string; clock?: () => number; presence?: () => readonly {id: string; state: string}[]; chat?: RoomChat }) { this.policy = new RoomPolicy(options.cwd); }
+  constructor(private readonly options: { stateDir: string; cwd: string; clock?: () => number; refreshMs?: number; presence?: () => readonly {id: string; state: string}[]; chat?: RoomChat }) { this.policy = new RoomPolicy(options.cwd); }
   private async open(): Promise<RoomStore> {
     if (this.stopped) refuse("stopped");
     this.pending ??= RoomStore.open({ stateDir: join(this.options.stateDir, "rooms"), ...(this.options.clock ? { clock: this.options.clock } : {}) }).then(store => {
@@ -63,13 +67,19 @@ export class RoomCommands {
     const store = await this.open();
     if (!this.stopped) for (const state of store.list()) if (!state.left) this.link(state.name);
   }
-  stop(): void { this.stopped = true; clearTimeout(this.presenceTimer); this.options.chat?.stop(); for (const link of this.links.values()) link.stop(); this.links.clear(); this.store?.close(); }
+  stop(): Promise<void> {
+    if (this.stopWork) return this.stopWork;
+    this.stopped = true; clearTimeout(this.presenceTimer); this.options.chat?.stop();
+    const stops = [...this.links.values()].map(link => link.stop()); this.links.clear();
+    this.stopWork = Promise.allSettled([...(this.pending ? [this.pending] : []), ...stops]).then(() => { this.store?.close(); });
+    return this.stopWork;
+  }
   private link(name: string): void {
     if (this.stopped || !this.store || this.store.get(name)?.left) return;
     let link = this.links.get(name);
     if (!link) {
       const store = this.store;
-      const created: RoomLink = new RoomLink({ store, name, application: this.options.chat?.application,
+      const created: RoomLink = new RoomLink({ store, name, application: this.options.chat?.application, refreshMs: this.options.refreshMs, now: this.options.clock,
         onPresence: value => this.options.chat?.presence(store, name, created, value),
         onState: state => this.options.chat?.linkState(store, name, created, state), presence: () => {
         const allowed = new Set(this.policy.get(name));
@@ -78,7 +88,7 @@ export class RoomCommands {
       this.links.set(name, created); link = created;
       this.options.chat?.bind(store, name, created);
       void created.start().catch(() => undefined);
-    } else { this.options.chat?.bind(this.store, name, link); link.refresh(); }
+    } else { this.options.chat?.bind(this.store, name, link); link.refresh(); void link.start().catch(() => undefined); }
   }
   private presenceTimer?: ReturnType<typeof setTimeout>;
   changed(): void {
@@ -91,6 +101,26 @@ export class RoomCommands {
     this.presenceTimer.unref?.();
   }
   private current(check: () => boolean): void { if (this.stopped || !check()) refuse("state_changed"); }
+  private async rotate(store: RoomStore, name: string, digest: string, expected: readonly RoomOutgoing[], check: () => boolean,
+    operation: (current: () => boolean) => Promise<RoomState>, after?: () => void): Promise<RoomState> {
+    const ids = expected.map(row => row.deliveryId).sort(), release = await this.links.get(name)?.quiesceApplications();
+    let next: RoomState | undefined, returned = false;
+    const current = () => !this.stopped && check() && store.get(name)?.current.digest === digest
+      && JSON.stringify(store.rotationPending(name).map(row => row.deliveryId).sort()) === JSON.stringify(ids);
+    try {
+      if (!current()) refuse("state_changed");
+      next = await operation(current);
+      const held = next.current.digest === digest || this.options.chat?.epochRotated(store, name, digest, expected) !== false;
+      this.current(check); after?.();
+      if (!held) throw new RoomRotationHoldError();
+      returned = true; return next;
+    } finally {
+      release?.();
+      // A committed epoch still needs publication if its journal label or local
+      // policy update failed; its old sealed intents were already fenced atomically.
+      if (next && !returned && next.current.digest !== digest) this.link(name);
+    }
+  }
   private active(store: RoomStore, name: string): RoomState {
     const state = store.get(name); if (!state || state.left) refuse("unavailable"); return state;
   }
@@ -196,9 +226,12 @@ export class RoomCommands {
         ? { room: existing.current.room, owner, minEpoch: existing.current.epoch, digest: existing.current.digest }
         : { room: invitation!.room, owner, minEpoch: "0" } });
       this.current(check);
-      return { owner, member: own, commit: async () => {
+      const outstanding = existing ? store.rotationPending(name) : [];
+      return { owner, member: own, ...(existing ? { outstanding: outstanding.map(row => row.deliveryId).sort() } : {}), commit: async () => {
         this.current(check);
-        const state = await store.install({ name, broker, wire, expectedDigest: existing?.current.digest ?? null, current: check, reactivate: true });
+        const state = existing ? await this.rotate(store, name, existing.current.digest, outstanding, check, current =>
+          store.install({ name, broker, wire, expectedDigest: existing.current.digest, current, reactivate: true }))
+          : await store.install({ name, broker, wire, expectedDigest: null, current: check, reactivate: true });
         return completed(state);
       } };
     }
@@ -235,7 +268,11 @@ export class RoomCommands {
     const state = this.active(store, name), owner = this.owner(state), digest = state.current.digest;
     if (action === "leave") return { owner, member: own, commit: async () => {
       this.current(check); if (store.get(name)?.current.digest !== digest) refuse("state_changed");
-      store.leave(name); this.links.get(name)?.stop(); this.links.delete(name); return { name, room: state.current.room, owner, member: own };
+      await this.links.get(name)?.stop();
+      try {
+        this.current(check); if (store.get(name)?.current.digest !== digest) refuse("state_changed");
+        store.leave(name); this.links.delete(name); return { name, room: state.current.room, owner, member: own };
+      } catch (error) { this.link(name); throw error; }
     } };
     if (action === "invite") {
       if (owner !== own) refuse("owner_only");
@@ -254,9 +291,12 @@ export class RoomCommands {
         if (!sender || exposure.room !== state.current.room || exposure.owner !== owner || exposure.digest !== digest || !await verifyBytes({ fingerprint: sender.fingerprint, signingKey: sender.signingKey, agreementKey: sender.agreementKey }, exposureBytes(body), decodeBase64url(signature, 64))) refuse("untrusted");
       }
       this.current(check);
-      return { owner, member, commit: async () => {
+      const outstanding = store.rotationPending(name);
+      return { owner, member, outstanding: outstanding.map(row => row.deliveryId).sort(), commit: async () => {
         this.current(check);
-        const next = exposure ? await store.rotate(name, roomMembers(state.current).map(m => m.fingerprint === member ? { ...m, exposedPeers: exposedPeers(exposure.peers) } : m), digest, check) : await store.enroll(name, request, check);
+        const next = await this.rotate(store, name, digest, outstanding, check, current => exposure
+          ? store.rotate(name, roomMembers(state.current).map(m => m.fingerprint === member ? { ...m, exposedPeers: exposedPeers(exposure.peers) } : m), digest, current)
+          : store.enroll(name, request, current));
         this.current(check); completed(next);
         return { name, owner, member, kind: "roster", artifact: encodeBase64url(next.wire) };
       } };
@@ -264,19 +304,24 @@ export class RoomCommands {
     if (action === "revoke") {
       if (owner !== own) refuse("owner_only");
       if (typeof row.member !== "string" || !FP.test(row.member) || row.member === own || !roomMembers(state.current).some(m => m.fingerprint === row.member)) refuse("invalid_member");
-      return { owner, member: row.member, commit: async () => {
-        this.current(check); const next = await store.rotate(name, roomMembers(state.current).filter(m => m.fingerprint !== row.member), digest, check); return completed(next);
+      const outstanding = store.rotationPending(name);
+      return { owner, member: row.member, outstanding: outstanding.map(row => row.deliveryId).sort(), commit: async () => {
+        this.current(check); const next = await this.rotate(store, name, digest, outstanding, check, current =>
+          store.rotate(name, roomMembers(state.current).filter(m => m.fingerprint !== row.member), digest, current)); return completed(next);
       } };
     }
     if (action === "expose") {
       const peers = exposedPeers(row.peers ?? []);
       this.policy.assertWritable(name, peers, check);
-      return { owner, member: own, commit: async () => {
+      const outstanding = owner === own ? store.rotationPending(name) : [];
+      return { owner, member: own, ...(owner === own ? { outstanding: outstanding.map(row => row.deliveryId).sort() } : {}), commit: async () => {
         this.current(check); this.policy.assertWritable(name, peers, check);
         if (store.get(name)?.current.digest !== digest) refuse("state_changed");
         if (owner === own) {
-          const next = await store.rotate(name, roomMembers(state.current).map(m => m.fingerprint === own ? { ...m, exposedPeers: peers } : m), digest, check);
-          this.current(check); this.policy.set(name, peers, check); return completed(next);
+          const next = await this.rotate(store, name, digest, outstanding, check, current =>
+            store.rotate(name, roomMembers(state.current).map(m => m.fingerprint === own ? { ...m, exposedPeers: peers } : m), digest, current),
+          () => this.policy.set(name, peers, check));
+          return completed(next);
         }
         const body: Omit<ExposureRequest, "signature"> = { v: 1, type: "exposure", room: state.current.room, owner, member: own, digest, peers };
         const request = canonicalBytes({ ...body, signature: encodeBase64url(await signBytes(store.identity, exposureBytes(body))) });