@staix/agent-hub 0.31.0 → 0.33.0

package/src/adapters/compat.ts

@@ -34,21 +34,21 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "The model-free extension load, RPC session identity and managed tool receipt path were checked on 1.4.0 and 1.5.0. Permissions remain host-owned; account-backed inference and another version's extension contract are unverified.",
     receipt: "docs/verification/2026-11-03-pi-150-compat.md" },
-  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; 2.1.316: docs/verification/2026-10-31-claude-implementer-2.1.316.md; 2.1.318: docs/verification/2026-11-05-claude-implementer-2.1.318.md; host-wrapper receipt below repeats with them.
-  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314", "2.1.316", "2.1.318"], gate: "contract", probe: ["claude", "--version"],
+  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; 2.1.316: docs/verification/2026-10-31-claude-implementer-2.1.316.md; 2.1.318: docs/verification/2026-11-05-claude-implementer-2.1.318.md; 2.1.319: docs/verification/2026-11-06-claude-implementer-2.1.319.md; host-wrapper receipt below repeats with them.
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314", "2.1.316", "2.1.318", "2.1.319"], gate: "contract", probe: ["claude", "--version"],
     parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
     trustNote: "The native prompt-tool transport and host-wrapper rewrite, environment isolation and replay contract have isolated receipts. No dontAsk/bypass fallback exists; another version's permission or rewrite behavior is unverified.",
-    receipt: "docs/verification/2026-11-05-claude-implementer-2.1.318.md" },
-  // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md; 0.166.0: docs/verification/2026-10-31-codex-0166-reviewer-isolation.md
+    receipt: "docs/verification/2026-11-06-claude-implementer-2.1.319.md" },
+  // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md; 0.166.0: docs/verification/2026-10-31-codex-0166-reviewer-isolation.md; 0.167.0 model-free only, not verified until its model-backed run: docs/verification/2026-11-06-codex-0167-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0", "0.166.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),
     trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md).",
-    receipt: "docs/verification/2026-10-31-codex-0166-reviewer-isolation.md" },
-  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md; Kimi 2.3.2: docs/verification/2026-10-26-kimi-232-reviewer-compat.md; Kimi 2.4.1: docs/verification/2026-10-31-kimi-241-reviewer-compat.md
-  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1", "2.3.2", "2.4.1"], gate: "isolation", probe: ["kimi", "--version"],
+    receipt: "docs/verification/2026-11-06-codex-0167-reviewer-isolation.md" },
+  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md; Kimi 2.3.2: docs/verification/2026-10-26-kimi-232-reviewer-compat.md; Kimi 2.4.1: docs/verification/2026-10-31-kimi-241-reviewer-compat.md; Kimi 2.5.1: docs/verification/2026-11-06-kimi-251-reviewer-compat.md
+  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1", "2.3.2", "2.4.1", "2.5.1"], gate: "isolation", probe: ["kimi", "--version"],
     parse: out => plain(out.trim()),
     trustNote: "Every launch still builds the private config, exact two-tool agent file and task-bound MCP; the native tool allowlist behaviour of an untested version is not re-proven.",
-    receipt: "docs/verification/2026-10-31-kimi-241-reviewer-compat.md" },
+    receipt: "docs/verification/2026-11-06-kimi-251-reviewer-compat.md" },
   jcode: { label: "Jcode", verified: ["0.98.1", "0.99.0", "0.99.1"], line: { min: "0.98.0", below: "1.0.0" }, gate: "contract", probe: ["jcode", "--quiet", "version", "--json"], config: "jcode_cmd",
     parse: out => { try { const v = JSON.parse(out).semver; return typeof v === "string" ? plain(v) : undefined; } catch { return undefined; } },
     trustNote: "The ACP, serve and MCP contract was verified on 0.98.1 and 0.99.1 and steering on 0.99.0 and 0.99.1; an untested version may change them.",
@@ -57,10 +57,10 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "Only 1.4.2, 1.4.7 and 1.4.12 are T0-verified; the plugin MCP and hook contract of another version is unverified.",
     receipt: "docs/verification/2026-11-03-agy-1.4.12-launcher-nonce.md" },
-  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
+  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5", "0.26.8"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
     parse: out => plain(out.trim()),
-    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4 and 0.26.5; real model turns remain unverified. Another version may change those contracts.",
-    receipt: "docs/verification/2026-11-03-qwen-0265-acp.md" },
+    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4, 0.26.5 and 0.26.8 (macOS arm64 and Linux x86_64); real model turns remain unverified. Another version may change those contracts.",
+    receipt: "docs/verification/2026-11-06-qwen-0268-acp.md" },
   // Receipt: docs/verification/2026-10-25-qwen-dual-output-t0.md. The dual-output contract (input file, event file, can_use_tool control requests) is its own entry:
   // the ACP receipts of the headless `qwen` entry say nothing about it, so that entry is not widened and this one carries no `line`.
   "qwen-dual": { label: "Qwen Code dual-output TUI", verified: ["0.26.1"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",

package/src/broker/protocol.ts

@@ -8,6 +8,8 @@ import {
   type OwnerPin, type VerifiedPublicRoster,
 } from "../rooms/wire.ts";
 
+/** Optional codec header token; the existing ephemeral opt-in remains byte-for-byte unchanged. */
+export const BROKER_CODEC_FEATURES_OPT_IN = "1";
 export const BROKER_CONTROL_LIMITS = Object.freeze({ control: 1_048_576, challenge: 8192, nonceBytes: 32 });
 export type BrokerProtocolCode = "invalid_wire" | "limit" | "untrusted" | "expired" | "authentication_failed";
 export class BrokerProtocolError extends Error {
@@ -35,6 +37,9 @@ export interface BrokerAuth {
   roster: string | null;
   signature: string;
 }
+/** Broker-to-client transport evidence; never accepted as client control or authority. */
+export interface BrokerCodecPeer { member: string; session: string | null; supported: boolean }
+export interface BrokerCodecPeers { v: 1; type: "codec_peers"; digest: string; peers: BrokerCodecPeer[] }
 export interface BrokerRosterReady { v: 1; type: "roster_ready"; digest: string }
 export interface BrokerReceived { v: 1; type: "received"; digest: string }
 export type BrokerControl = BrokerAuth | BrokerRosterReady | BrokerReceived;

package/src/broker/server.ts

@@ -2,7 +2,7 @@
 import type { ServerWebSocket } from "bun";
 import { assertRoomCryptoReady, decodeBase64url, encodeBase64url, randomBytes } from "../rooms/crypto.ts";
 import { brokerUrl, canonicalBytes, decodeFrame, decodeRoster, publicRosterWire, verifyPublicFrame, verifyPublicRoster, type VerifiedPublicRoster } from "../rooms/wire.ts";
-import { BROKER_CONTROL_LIMITS, decodeBrokerControl, encodeBrokerChallenge, verifyBrokerAuth, type BrokerChallenge } from "./protocol.ts";
+import { BROKER_CODEC_FEATURES_OPT_IN, BROKER_CONTROL_LIMITS, decodeBrokerControl, encodeBrokerChallenge, verifyBrokerAuth, type BrokerChallenge } from "./protocol.ts";
 import { BrokerStore, BrokerStoreError, type BrokerLimits } from "./store.ts";
 
 export const BROKER_SOCKET_LIMITS = Object.freeze({ connections: 128, verifications: 16, authMs: 10_000, rosterAckMs: 30_000, backpressureBytes: 1_048_576, queuedMessages: 8, queuedBytes: 2_097_152, globalQueuedBytes: 33_554_432 });
@@ -26,6 +26,10 @@ interface Client {
   ws?: ServerWebSocket<Client>;
   room: string;
   ephemeral: boolean;
+  codecFeatures: boolean;
+  codecSession: string;
+  pendingCodecMembers: Set<string>;
+  codecFlushQueued: boolean;
   challenge: BrokerChallenge;
   phase: "challenge" | "authenticating" | "roster" | "ready" | "closed";
   busy: boolean;
@@ -108,11 +112,13 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
   function close(client: Client, code: string): void {
     if (client.phase === "closed") return;
     client.phase = "closed";
+    client.pendingCodecMembers.clear(); client.codecFlushQueued = false;
     client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     queuedBytes -= client.inboxBytes; client.inboxBytes = 0; client.inbox.length = 0;
     if (client.member && members.get(memberKey(client)) === client) {
       members.delete(memberKey(client));
       try { store.disconnect(client.room, client.member); } catch { emit("refused", client, "state_unavailable"); }
+      notifyCodecPeers(client.room, client.member);
     }
     if (client.ws) { try { client.ws.close(4403, code); } catch { /* already closed */ } }
     else clients.delete(client);
@@ -137,15 +143,55 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (!roster || !member || identityKey(member) !== client.key) throw new BrokerServerError("untrusted");
     return roster;
   }
+  /** Connection evidence only: the sender must still echo its session in signed presence. */
+  function sendCodecPeers(recipient: Client, memberIds: readonly string[]): void {
+    if (!recipient.codecFeatures || recipient.phase !== "ready") return;
+    try {
+      const roster = active(recipient);
+      const peers = memberIds.filter(member => member !== recipient.member && roster.members.some(row => row.fingerprint === member)).map(member => {
+        const source = members.get(`${recipient.room}|${member}`);
+        const current = source?.phase === "ready" && active(source).digest === roster.digest ? source : undefined;
+        return { member, session: current?.codecSession ?? null, supported: current?.codecFeatures === true };
+      });
+      if (peers.length) control(recipient, { v: 1, type: "codec_peers", digest: roster.digest, peers });
+    } catch { close(recipient, "state_changed"); }
+  }
+  function flushCodecPeers(client: Client): void {
+    const pending = [...client.pendingCodecMembers]; client.pendingCodecMembers.clear();
+    if (pending.length) sendCodecPeers(client, pending);
+  }
+  function notifyCodecPeers(room: string, member: string): void {
+    for (const recipient of clients) if (recipient.room === room && recipient.codecFeatures && recipient.phase === "ready") {
+      try {
+        const current = new Set(active(recipient).members.map(row => row.fingerprint));
+        // At most the signed roster's members can wait; churn replaces evidence
+        // rather than growing a control queue beyond the existing packet ceiling.
+        for (const pending of recipient.pendingCodecMembers) if (!current.has(pending)) recipient.pendingCodecMembers.delete(pending);
+        if (member === recipient.member || !current.has(member)) continue;
+        recipient.pendingCodecMembers.add(member);
+        if (!recipient.codecFlushQueued) {
+          recipient.codecFlushQueued = true;
+          queueMicrotask(() => { recipient.codecFlushQueued = false; flushCodecPeers(recipient); });
+        }
+      } catch { close(recipient, "state_changed"); }
+    }
+  }
+  function codecInventory(client: Client): void {
+    if (!client.codecFeatures || client.phase !== "ready") return;
+    client.pendingCodecMembers.clear();
+    sendCodecPeers(client, active(client).members.map(member => member.fingerprint));
+  }
   function sendRoster(client: Client): void {
     const roster = active(client);
     client.phase = "roster"; client.rosterDigest = roster.digest;
     client.rosterDeadline = now() + BROKER_SOCKET_LIMITS.rosterAckMs;
     // Legacy hubs have a closed ready grammar; advertise only after HTTP opt-in.
-    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}) });
+    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}), ...(client.codecFeatures ? { codecFeatures: true, codecSession: client.codecSession } : {}) });
   }
   function pump(client: Client): void {
     if (stopping || client.phase === "closed" || !client.member) return;
+    flushCodecPeers(client); // Source-session invalidation always precedes ciphertext handoff.
+    if (members.get(memberKey(client)) !== client) return;
     const roster = active(client);
     const next = store.next(client.room, client.member);
     if (client.inFlightEphemeral && client.inFlightEpoch !== roster.epoch) {
@@ -192,6 +238,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (previous && previous !== client) close(previous, "replaced");
     members.set(memberKey(client), client);
     client.phase = "roster";
+    notifyCodecPeers(client.room, client.member);
     sendRoster(client);
     emit("connected", client);
   }
@@ -218,7 +265,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const proof = await (ports.verifyFrame ?? verifyPublicFrame)({ wire: bytes, roster: selected });
       const onlineRecipients = proof.recipients.filter(recipient => {
         const target = members.get(`${client.room}|${recipient}`);
-        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral);
+        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral) && (!proof.codecFeatures || target.codecFeatures);
       });
       try {
         active(client);
@@ -241,6 +288,8 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const latest = active(client);
       if (packet.digest !== client.rosterDigest || packet.digest !== latest.digest) { sendRoster(client); return; }
       client.phase = "ready"; client.rosterDeadline = undefined;
+      codecInventory(client);
+      if (client.member) notifyCodecPeers(client.room, client.member);
       safePump(client); return;
     }
     if (packet.digest !== client.inFlight) { refused(client, "unexpected_ack", false); return; }
@@ -290,7 +339,8 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
           const room = roomId(url.pathname.slice("/v1/rooms/".length));
           if (clients.size >= BROKER_SOCKET_LIMITS.connections) return new Response("busy", { status: 503 });
           const current = store.current(room)?.current;
-          const client: Client = { room, ephemeral: req.headers.get("x-agent-hub-ephemeral") === "1", challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
+          const transportOptIn = req.headers.get("x-agent-hub-ephemeral");
+          const client: Client = { room, ephemeral: transportOptIn === "1", codecFeatures: transportOptIn === "1" && req.headers.get("x-agent-hub-codecs") === BROKER_CODEC_FEATURES_OPT_IN, codecSession: encodeBase64url(randomBytes(32)), pendingCodecMembers: new Set(), codecFlushQueued: false, challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
           clients.add(client);
           if (host.upgrade(req, { data: client })) return;
           clients.delete(client); return new Response("websocket required", { status: 400 });

package/src/broker/store.ts

@@ -408,7 +408,9 @@ export class BrokerStore {
         // ponytail: while A awaits C, A's broadcast reply to B may replace C's request;
         // C waits for A's next state change/reconnect. Task #736 idle refresh or
         // per-(sender,recipient) coalescing closes this latest-per-sender ceiling.
-        this.removeEphemeral(proof.room, proof.sender);
+        // Codec advertisements must not evict a legacy snapshot that a mixed
+        // member has not received yet. Both groups share the existing queue caps.
+        this.removeEphemeral(proof.room, proof.sender, undefined, proof.codecFeatures === true);
         const connected = new Set(onlineRecipients);
         recipients = recipients.filter(recipient => connected.has(recipient));
       }
@@ -438,12 +440,13 @@ export class BrokerStore {
     this.transaction(() => { this.removeEphemeral(room, undefined, recipient); });
   }
 
-  private removeEphemeral(room?: string, sender?: string, recipient?: string): void {
+  private removeEphemeral(room?: string, sender?: string, recipient?: string, codecFeatures?: boolean): void {
     const rows = this.db.query<{ rowid: number; wire: Uint8Array; recipients: string }, [string | null, string | null, string | null, string | null]>(
       "SELECT rowid,wire,recipients FROM queued_frames WHERE (? IS NULL OR room=?) AND (? IS NULL OR sender=?)",
     ).all(room ?? null, room ?? null, sender ?? null, sender ?? null);
     for (const row of rows) {
-      if (!decodeFrame(row.wire).ephemeral) continue;
+      const frame = decodeFrame(row.wire);
+      if (!frame.ephemeral || codecFeatures !== undefined && (frame.codecFeatures === true) !== codecFeatures) continue;
       const remaining = recipient === undefined ? [] : parseRecipients(row.recipients).filter(id => id !== recipient);
       if (remaining.length) this.db.query("UPDATE queued_frames SET recipients=? WHERE rowid=?").run(JSON.stringify(remaining), row.rowid);
       else this.db.query("DELETE FROM queued_frames WHERE rowid=?").run(row.rowid);

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/output.ts

@@ -5,7 +5,7 @@ import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
 import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
 import { taskProgress } from "../ui/task-progress.ts";
-import { backendLabel, memorySyncLine, reviewInputHealthLine } from "./status-lines.ts";
+import { backendLabel, memorySyncLine, reviewInputHealthLine, roomsUnavailableLine } from "./status-lines.ts";
 import { ownerIsolationText } from "./role-holders.ts";
 import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
@@ -14,6 +14,8 @@ import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  roomsUnavailable?: unknown;
+  roomsOpening?: boolean;
   controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
   specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
@@ -263,6 +265,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     const text = ownerIsolationText(isolated, data.ownerIsolationNotes?.[id]);
     if (text) out.push(...detail(`${id} owner isolation`, text, columns, isolated ? undefined : "attention"));
   }
+  if (data.roomsOpening === true) out.push(...lines("rooms: opening; wait for local room storage initialization", columns, "muted"));
+  if (data.roomsUnavailable !== undefined) out.push(...lines(roomsUnavailableLine(data.roomsUnavailable), columns, "failure"));
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const [peer, count] of Object.entries(data.deliveryFailures ?? {})) {
     if (Number.isSafeInteger(count) && count > 0) out.push(...detail(`${peer} failed deliveries`, `${count}; next: ahub queue discard --peer ${peer} --state failed`, columns, "attention"));

package/src/cli/room.ts

@@ -1,8 +1,9 @@
+import { projectRoomUnavailable, projectRoomDiagnostics, type RoomStatusDiagnostics } from "../rooms/status.ts";
 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 +18,10 @@ 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" | "rooms_unavailable", availability?: unknown) {
+    const unavailable = projectRoomUnavailable(availability);
+    const message = { rooms_unavailable: `unavailable (${unavailable?.code ?? "unknown"}); ${unavailable?.nextStep ?? "Run ahub status to inspect room storage before retrying."}`, 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,10 +144,10 @@ 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 RoomRow { name: string; room: string; owner: string; member: string; epoch: string; state: string; deliveries?: (DeliveryRow | DeliverySummary)[]; remotePeers?: RemotePeerRow[] }
+interface RemotePeerRow { id: string; state: "idle" | "busy" | "paused" | "offline"; presence?: "idle" | "busy" | "paused" | "offline" | "unknown"; liveness?: "untracked" }
+interface RoomRow extends RoomStatusDiagnostics { 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}$/;
 const REFUSAL_REASONS: readonly RoomReceiptReason[] = ["admitted", "not_exposed", "boundary_refused", "invalid_message", "rate_limited", "hop", "person_inbox_unsupported", "inbox_admitted", "inbox_full", "inbox_oversize", "inbox_expired", "inbox_age_unavailable"];
@@ -170,10 +173,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 +185,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 +196,10 @@ 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) {
+    if (row.code === "rooms_unavailable") throw new RoomCliError("rooms_unavailable", row.roomsUnavailable);
+    fail(row.code === "epoch_rotated_hold_unavailable" ? "epoch_rotated_hold_unavailable" : "refused");
+  }
   return row;
 }
 function roomRows(value: unknown): RoomRow[] {
@@ -202,7 +211,7 @@ function roomRows(value: unknown): RoomRow[] {
       || typeof row.epoch !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(row.epoch)
       || typeof row.state !== "string" || !/^[a-z][a-z_-]{0,31}$/.test(row.state)) return fail("invalid_reply");
     // Ignore all other fields, even from a newer daemon: read output never grows into room bodies or secrets.
-    return { name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch, state: row.state,
+    return { name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch, state: row.state, ...projectRoomDiagnostics(row),
       ...(row.deliveries !== undefined ? { deliveries: deliveryRows(row.deliveries) } : {}), ...(row.remotePeers !== undefined ? { remotePeers: remotePeerRows(row.remotePeers) } : {}) };
   });
 }
@@ -270,10 +279,17 @@ 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}`);
+      if (command.op === "status") {
+        const health = row.health, age = (value: number | null | undefined) => typeof value === "number" ? `${value}ms` : "unknown";
+        if (row.state === "online" && (row.linkCause === null || row.linkCause === undefined)) console.log("  link online");
+        else console.log(`  link cause ${row.linkCause ?? "unknown"}; next: ${row.linkNextStep ?? "Check broker availability, then read ahub room status again."}`);
+        console.log(`  outbox ${health?.outboxDepth ?? "unknown"}; oldest ${age(health?.oldestOutboxAgeMs)}; last receipt ${age(health?.lastReceiptAgeMs)}`);
+        console.log(`  refused: ${health?.refused ? Object.entries(health.refused).map(([reason, count]) => `${reason} ${count}`).join(", ") : "unknown"}`);
+      }
+      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 +299,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/cli/status-lines.ts

@@ -1,3 +1,4 @@
+import { projectRoomUnavailable } from "../rooms/status.ts";
 import type { ContextView } from "../hub/context-window.ts";
 import { memorySyncNextStep, type MemorySyncCause } from "../hub/memory-sync-state.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
@@ -35,7 +36,7 @@ export function memorySyncLine(sync: MemorySyncRow, time = (at: number) => new D
   const cause = (causes.includes(sync.cause ?? "") ? sync.cause : "unknown") as MemorySyncCause;
   if (cause === "declined" && sync.placementActive === false) {
     const declined = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? String(sync.declinedCount) : "unknown";
-    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store (agent-mem has no activation command yet, agent-mem#281). Inspect with `ahub memory declined`.";
+    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store. Activation is person-only: preview with `amem migrate --sync-placement --dry-run` and declare every writer via --writer-root. The hub does not yet supply the fresh placementAttestation required for active-placement sync (#1173). Inspect with `ahub memory declined`.";
   }
   const count = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? `, ${sync.declinedCount} declined` : "";
   const ids = cause === "declined" && sync.declinedIdsKnown === false ? "; declined ID set unknown" : "";
@@ -55,3 +56,9 @@ export function reviewInputHealthLine(health: ReviewInputHealthRow): string | un
   const state = health.state === "incomplete" || health.state === "corrupt" ? health.state : "unknown";
   return `${state} (${cause}); next: ${next}`;
 }
+
+/** Room failures carry a closed cause and locally generated next step only. */
+export function roomsUnavailableLine(value: unknown): string {
+  const unavailable = projectRoomUnavailable(value);
+  return `rooms: unavailable (${unavailable?.code ?? "unknown"}); next: ${unavailable?.nextStep ?? "Run ahub room status to inspect room storage and broker availability."}`;
+}

package/src/cli/terminal-recovery.ts

@@ -206,17 +206,32 @@ function decoded(result: CommandResult): unknown {
   }
 }
 
+/** Orca's structured error, from the JSON it prints on stdout or stderr. */
+function orcaError(result: CommandResult): Record<string, unknown> {
+  const fromStdout = object(object(decoded(result)).error);
+  if (fromStdout.code !== undefined) return fromStdout;
+  try { return object(object(JSON.parse(bytes(result.stderr))).error); } catch { return {}; }
+}
+
+function errorCode(result: CommandResult): unknown {
+  return orcaError(result).code;
+}
+
+/** #1233: Orca prints its error as JSON on stdout with an empty stderr, so its code comes before the exit-status fallback. */
 function errorText(result: CommandResult): string {
+  const { code, message } = orcaError(result);
+  if (typeof code === "string") return typeof message === "string" && message !== code ? `${code}: ${message.slice(0, 200)}` : code;
   const stderr = bytes(result.stderr).trim();
   return stderr || `exit status ${commandStatus(result)}`;
 }
 
-/** Orca's structured error code, from the JSON it prints on stdout or stderr. */
-function errorCode(result: CommandResult): unknown {
-  const fromStdout = object(object(decoded(result)).error).code;
-  if (fromStdout !== undefined) return fromStdout;
-  try { return object(object(JSON.parse(bytes(result.stderr))).error).code; } catch { return undefined; }
-}
+/**
+ * Orca 1.4.250 answers a terminal it can no longer reach with one of these codes, and its own CLI groups all four as
+ * gone (docs/verification/2026-11-06-orca-1.4.250-cli-contract.md). A wait on a pane whose process ended throws
+ * terminal_exited, so restoration must read it as gone and check the launcher, not stop on a command error (#1233).
+ */
+const GONE_CODES = new Set(["terminal_handle_stale", "terminal_exited", "terminal_gone", "no_connected_pty"]);
+const GONE_STATES: Record<string, string> = { terminal_handle_stale: "no longer exists", terminal_exited: "exited (terminal_exited)" };
 
 function runnerFailure(argv: readonly string[], result: CommandResult): RecoveryBlocker {
   return { code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} failed: ${errorText(result)}` };
@@ -226,9 +241,11 @@ async function run(runner: CommandRunner, argv: readonly string[]): Promise<unkn
   const result = await runner(argv);
   if (commandStatus(result) !== 0) {
     // Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
-    if (errorCode(result) === "terminal_handle_stale") {
+    const code = errorCode(result);
+    if (typeof code === "string" && GONE_CODES.has(code)) {
       const handle = argv.includes("--terminal") ? argv[argv.indexOf("--terminal") + 1] : undefined;
-      throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} no longer exists` });
+      const state = GONE_STATES[code] ?? `is gone (${code})`;
+      throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} ${state}` });
     }
     throw new OrcaCommandError(runnerFailure(argv, result));
   }
@@ -236,7 +253,9 @@ async function run(runner: CommandRunner, argv: readonly string[]): Promise<unkn
   const root = object(value);
   const payload = responseResult(value);
   if (root.ok === false || payload.ok === false) {
-    throw new OrcaCommandError({ code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} returned ok:false${typeof root.error === "string" ? `: ${root.error}` : ""}` });
+    const error = root.error ?? payload.error;
+    const detail = typeof error === "string" ? error : object(error).code;
+    throw new OrcaCommandError({ code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} returned ok:false${typeof detail === "string" && detail ? `: ${detail}` : ""}` });
   }
   return value;
 }
@@ -816,14 +835,17 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
 
 /**
  * One bounded Orca wait. Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
- * that is "not satisfied", not a failure. Any other failure still throws.
+ * that is "not satisfied", not a failure. Any other failure still throws. 1.4.250 also answers ok with `satisfied: false`
+ * and a `blockedReason` (seen: `agent-update-prompt`) when the TUI waits on a prompt; the reason is passed on (#1233).
  */
-async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<boolean> {
+async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<{ satisfied: boolean; blockedReason?: string }> {
   const argv = ["terminal", "wait", "--terminal", handle, "--for", "tui-idle", "--timeout-ms", String(timeoutMs), "--json"];
   const result = await runner(argv);
-  if (commandStatus(result) !== 0 && errorCode(result) === "timeout") return false;
+  if (commandStatus(result) !== 0 && errorCode(result) === "timeout") return { satisfied: false };
   const root = responseResult(await run(async () => result, argv));
-  return root.satisfied === true || object(root.wait).satisfied === true;
+  if (root.satisfied === true || object(root.wait).satisfied === true) return { satisfied: true };
+  const reason = root.blockedReason ?? object(root.wait).blockedReason;
+  return typeof reason === "string" ? { satisfied: false, blockedReason: reason.slice(0, 100) } : { satisfied: false };
 }
 
 /** Wait only on the captured terminal and only for Orca's supported TUI-idle condition. */
@@ -832,8 +854,8 @@ export async function waitForIdle(binding: TerminalBinding, timeoutMs: number, o
   const timeout = Number.isFinite(timeoutMs) && timeoutMs >= 0 ? Math.min(Math.floor(timeoutMs), MAX_WAIT_MS) : 0;
   try {
     await showBinding(binding, config);
-    const satisfied = await waitSatisfied(config.runner, binding.handle, timeout);
-    const blockers = satisfied ? [] : [blocker("terminal-unready", `terminal ${binding.handle} did not become idle before the bounded wait`, binding.peer, binding.handle)];
+    const { satisfied, blockedReason } = await waitSatisfied(config.runner, binding.handle, timeout);
+    const blockers = satisfied ? [] : [blocker("terminal-unready", `terminal ${binding.handle} did not become idle before the bounded wait${blockedReason ? ` (Orca: blocked by ${blockedReason})` : ""}`, binding.peer, binding.handle)];
     return { satisfied, manualRequired: !satisfied, blockers };
   } catch (error) {
     const item = error instanceof OrcaCommandError ? error.blocker : blocker("command-error", String(error), binding.peer, binding.handle);

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>();
@@ -265,6 +266,8 @@ export class Bus {
   private condensing = 0;
   private closed = false;
   storageError?: string;
+  /** Verified durable-write recovery edge; observation never changes settlement. */
+  onStorageRecovered?: () => void;
 
   constructor(opts: Partial<BusOptions> = {}) {
     this.opts = { ...DEFAULT_BUS, ...opts };
@@ -422,6 +425,7 @@ export class Bus {
   private persist(): void {
     if (!this.journal) return;
     const tracking = this.trackingQueuePressure();
+    const wasUnavailable = this.storageError !== undefined;
     try {
       this.journal.transaction(() => {
         for (const outcome of this.pendingOutcomes) this.journal!.createDelivery(outcome);
@@ -429,6 +433,10 @@ export class Bus {
       });
       this.pendingOutcomes.length = 0;
       this.storageError = undefined;
+      if (wasUnavailable) queueMicrotask(() => {
+        if (this.closed || this.storageError) return;
+        try { this.onStorageRecovered?.(); } catch { /* Recovery observers cannot undo the durable write. */ }
+      });
     }
     catch { this.storageError = "delivery journal unavailable"; throw new Error("delivery journal unavailable"); }
   }
@@ -1367,6 +1375,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;