@staix/agent-hub 0.31.0 → 0.33.0

package/src/rooms/liveness.ts

@@ -0,0 +1,11 @@
+/** Host timing only; signed presence remains the existing v1 ids/state payload. */
+export const ROOM_REFRESH_MS = 30_000;
+export const ROOM_PRESENCE_MISSES = 3;
+export const ROOM_STOP_TIMEOUT_MS = 2_000;
+
+export function roomRefreshPeriod(value = ROOM_REFRESH_MS): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > Math.floor(2_147_483_647 / ROOM_PRESENCE_MISSES)) {
+    throw new Error("room refresh period is invalid; use a positive whole duration within the timer bound");
+  }
+  return value;
+}

package/src/rooms/remote-peer.ts

@@ -3,7 +3,7 @@ import { BasePeer, type DeliveryReceipt } from "../hub/peers.ts";
 import type { Envelope, PeerState } from "../hub/envelope.ts";
 import { encodeRoomMessage, parseRemotePeerId, type RoomChatEnvelope } from "./application.ts";
 import { readRoomOutbound, roomBoundary, type RoomBoundaryContext } from "./boundary.ts";
-import { RoomNotSentError } from "./link.ts";
+import { RoomCodecPendingError, RoomCodecUnsupportedError, RoomNotSentError } from "./link.ts";
 
 export interface RemotePeerPorts {
   member: string;
@@ -32,10 +32,12 @@ export class RemotePeer extends BasePeer {
   private running = false;
   private online = false;
   private blockedNotSent = false;
+  private codecWaiting = false;
   private observed: PeerState = "offline";
   private readonly pending = new Set<string>();
   private readonly waitingForReady = new Set<string>();
   private readonly sending = new Set<string>();
+  private readonly codecRechecks = new Map<string, () => boolean>();
   private readonly deadlines = new Map<string, number>();
   constructor(id: string, readonly remoteRoom: string, readonly remoteQueueTtlMs: number, private readonly ports: RemotePeerPorts) {
     super(id);
@@ -60,6 +62,7 @@ export class RemotePeer extends BasePeer {
     // Active journal rows and their sealed room frames survive a sender restart.
     // Stop only fences in-flight callbacks; it is not evidence of an uncertain send.
     this.pending.clear();
+    this.codecWaiting = false; this.codecRechecks.clear();
     this.waitingForReady.clear();
     this.deadlines.clear(); this.update();
   }
@@ -125,6 +128,7 @@ export class RemotePeer extends BasePeer {
   }
   /** A link becoming ready is an actual wake-up after a typed not-sent refusal. */
   wake(): void { this.blockedNotSent = false; this.update(); }
+  wakeCodec(): void { if (this.codecWaiting) { this.codecWaiting = false; this.wake(); } }
   setRemoteDeadline(envelopeId: string, expiresAt: number): void {
     if (Number.isSafeInteger(expiresAt) && expiresAt > 0 && this.deadlines.size < 200) this.deadlines.set(envelopeId, expiresAt);
   }
@@ -159,7 +163,11 @@ export class RemotePeer extends BasePeer {
     if (this.sending.has(deliveryId)) return;
     this.sending.add(deliveryId);
     try { await this.publishOnce(env, deliveryId, expiresAt, generation, immutable); }
-    finally { this.sending.delete(deliveryId); }
+    finally {
+      this.sending.delete(deliveryId);
+      const changed = this.codecRechecks.get(deliveryId); this.codecRechecks.delete(deliveryId);
+      if (changed?.()) { this.codecWaiting = false; this.wake(); } // Recheck only after this send lane released, closing observation-before-requeue races.
+    }
   }
   private async publishOnce(env: Envelope, deliveryId: string, expiresAt: number, generation: number, immutable?: RoomChatEnvelope): Promise<void> {
     let context: RoomBoundaryContext;
@@ -216,12 +224,19 @@ export class RemotePeer extends BasePeer {
       }
     } catch (error) {
       if (!this.pending.has(deliveryId)) return;
+      if (error instanceof RoomCodecUnsupportedError && !immutable) {
+        let queued: boolean | undefined;
+        try { queued = this.ports.queued?.(deliveryId); } catch { queued = undefined; }
+        if (queued === false) { this.receipt({ id: deliveryId, state: "failed_safe", reason: error.message }); return; }
+      }
+      if (error instanceof RoomCodecPendingError) this.codecWaiting = true;
       if (error instanceof RoomNotSentError) {
         let retained: boolean | undefined;
         try { retained = this.ports.queued?.(deliveryId); } catch { retained = undefined; }
         if (immutable || retained === true) {
-          if (!this.ready()) this.waitForReady(deliveryId);
+          if (!this.ready() || error instanceof RoomCodecPendingError) this.waitForReady(deliveryId);
         } else this.notSent(deliveryId);
+        if (error instanceof RoomCodecPendingError) this.codecRechecks.set(deliveryId, error.changed);
         return;
       }
       if (!trusted()) {

package/src/rooms/service.ts

@@ -1,5 +1,5 @@
 /** Host integration for X4. Remote identities carry chat, never local control authority. */
-import { ROOM_PROOF_UNAVAILABLE_REASON, type Bus } from "../hub/bus.ts";
+import { ROOM_EPOCH_ROTATED_REASON, ROOM_PROOF_UNAVAILABLE_REASON, type Bus } from "../hub/bus.ts";
 import { USER, MAX_HOP, isInvocationKind, type Envelope, type PeerState } from "../hub/envelope.ts";
 import type { RoomInvocationAuthorization } from "./boundary.ts";
 import { roomInvocationHash } from "../hub/room-invocations.ts";
@@ -11,8 +11,9 @@ import { roomMembers, RoomWireError } from "./wire.ts";
 import { RoomStore, RoomStoreError, RoomApplicationLimitError, type RoomOutgoing } from "./store.ts";
 import { RoomPolicy } from "./policy.ts";
 import { RemotePeer } from "./remote-peer.ts";
-import { parseRemotePeerId, roomReceiptReasonText, type RoomMessage, type RoomReceiptReason, type RoomChatEnvelope } from "./application.ts";
+import { parseRemotePeerId, roomReceiptReasonText, type RoomMessage, type RoomReceiptReason, type RoomChatEnvelope, type RoomCodecFeature } from "./application.ts";
 import { RoomApplicationDeferredError, RoomNotSentError, type RoomLink, type RoomLinkApplication, type RoomLinkContext, type RoomLinkState, type RoomPresencePeer } from "./link.ts";
+import { ROOM_PRESENCE_MISSES, ROOM_REFRESH_MS, roomRefreshPeriod } from "./liveness.ts";
 
 export interface RoomInvocationIdentity { room: string; member: string; epoch: string; current: () => boolean }
 export interface RoomInvocationIngress {
@@ -20,7 +21,7 @@ export interface RoomInvocationIngress {
   current: () => boolean; claim: () => boolean;
 }
 export interface RoomChatOptions {
-  bus: Bus; cwd: string; now?: () => number;
+  bus: Bus; cwd: string; now?: () => number; refreshMs?: number;
   routing: () => Routing; piiPaths: () => readonly string[];
   senderPrivate: (peer: string) => boolean | undefined;
   taskPrivate: (id: number) => boolean | undefined;
@@ -31,10 +32,10 @@ export interface RoomChatOptions {
   roster?: (ids: readonly string[]) => void;
   changed?: () => void;
   limits?: () => LimitsConfig;
-  notice?: (value: { code: "application_capacity"; room: string; count: number } | { code: "sequence_gap"; room: string; sender: string; count: string }) => void;
+  notice?: (value: { code: "application_capacity"; room: string; count: number }) => void;
 }
 export interface RoomMetrics { since: number; outbound: number | null; inbound: number | null; withheld: number | null }
-interface Binding { store: RoomStore; name: string; room: string; link: RoomLink; digest: string; online: boolean; states: Map<string, PeerState> }
+interface Binding { store: RoomStore; name: string; room: string; link: RoomLink; digest: string; rosterMembers: string; online: boolean; states: Map<string, PeerState>; observedAt: Map<string, number>; observedMembers: Set<string>; tracked?: boolean }
 interface Target { binding: Binding; member: string; peer: string }
 const ACTIVE = new Set(["dispatching", "accepted", "needs_review"]);
 function completedText(reason?: RoomReceiptReason): string {
@@ -69,6 +70,9 @@ export class RoomChat {
   private readonly outgoing = new Map<string, { binding: Binding; row: RoomOutgoing }>();
   private readonly resuming = new Set<string>();
   private readonly personHeldInvocations = new Map<string, Set<string>>();
+  private readonly refreshMs: number;
+  private presenceClockHighWater?: number;
+  private presenceClockInvalid = false;
   private evidenceCache?: Map<string, { peer: string; roomState: string; disposition?: string; lateReceipt?: string; refusalReason?: string }>;
   private timer?: ReturnType<typeof setTimeout>;
   private stopped = false;
@@ -78,8 +82,9 @@ export class RoomChat {
   readonly application: RoomLinkApplication;
   constructor(private readonly options: RoomChatOptions) {
     this.policy = new RoomPolicy(options.cwd);
+    this.refreshMs = roomRefreshPeriod(options.refreshMs ?? ROOM_REFRESH_MS);
     let since: number | null = null;
-    try { const value = this.now(); if (Number.isSafeInteger(value) && value >= 0) since = value; } catch { /* Observation failure never disables transport construction. */ }
+    try { const value = this.now(); if (Number.isSafeInteger(value) && value >= 0) { since = value; this.presenceClockHighWater = value; } } catch { /* Observation failure never disables transport construction. */ }
     this.metricsSince = since;
     this.application = {
       members: context => { if (context.current()) this.bind(context.store, context.name, context.link); },
@@ -101,14 +106,53 @@ export class RoomChat {
         const binding = this.bindings.get(context.name); if (binding) this.wakeRemotes(binding);
       },
       capacityChanged: context => { if (context.current()) { const binding = this.bindings.get(context.name); if (binding) this.wakeRemotes(binding); this.capacityChanged(); } },
-      gap: (context, input) => {
-        if (context.current()) this.options.notice?.({ code: "sequence_gap", room: context.store.get(context.name)!.current.room, sender: input.sender, count: input.count });
-      },
+      codecsChanged: (context, input) => { if (context.current()) { const binding = this.bindings.get(context.name); if (binding) { this.wakeRemotes(binding, input.member, true); void this.resumeActive(binding, input.member, input.features); } } },
+      // The signed sequence is room-wide, while chat recipients are selective.
+      // A numeric gap is not evidence of loss and must not become an operator notice.
     };
   }
   private now(): number { return this.options.now?.() ?? Date.now(); }
-  private wakeRemotes(binding: Binding): void {
-    for (const [id, remote] of this.remotes) if (this.targets.get(id)?.binding === binding) remote.wake();
+  /** Local receipt time only; remote timestamps never participate in freshness. */
+  private presenceNow(mutate = true): number | undefined {
+    let now: number;
+    try { now = this.now(); } catch { now = NaN; }
+    if (!Number.isSafeInteger(now) || now < 0 || this.presenceClockHighWater !== undefined && now < this.presenceClockHighWater) {
+      if (mutate && !this.presenceClockInvalid) {
+        for (const binding of this.bindings.values()) if (this.livenessTracked(binding) !== false) binding.observedAt.clear();
+      }
+      if (mutate) this.presenceClockInvalid = true;
+      return undefined;
+    }
+    if (mutate) {
+      if (this.presenceClockHighWater === undefined || now > this.presenceClockHighWater) this.presenceClockHighWater = now;
+      this.presenceClockInvalid = false;
+    }
+    return now;
+  }
+  private livenessTracked(binding: Binding): boolean | undefined {
+    return binding.tracked;
+  }
+  private memberFresh(binding: Binding, member: string, now: number | undefined): boolean {
+    if (this.livenessTracked(binding) === false) return true;
+    if (now === undefined || this.presenceClockInvalid) return false;
+    const seen = binding.observedAt.get(member);
+    return seen !== undefined && now >= seen && now - seen < this.refreshMs * ROOM_PRESENCE_MISSES;
+  }
+  private advisoryPresence(id: string, target: Target): PeerState | "unknown" {
+    if (this.livenessTracked(target.binding) !== false && !this.memberFresh(target.binding, target.member, this.presenceNow(false))) return "unknown";
+    return target.peer === USER ? "idle" : target.binding.states.get(id) ?? "offline";
+  }
+  private advisoryLiveness(target: Target): "untracked" | undefined {
+    return this.livenessTracked(target.binding) === false ? "untracked" : undefined;
+  }
+  private targetSendable(id: string): boolean {
+    const target = this.targets.get(id);
+    return !!target && target.binding.online && this.valid(target.binding);
+  }
+  private wakeRemotes(binding: Binding, member?: string, codecOnly = false): void {
+    for (const [id, remote] of this.remotes) if (this.targets.get(id)?.binding === binding && (member === undefined || this.targets.get(id)?.member === member)) {
+      if (codecOnly) remote.wakeCodec(); else remote.wake();
+    }
   }
   metrics(name: string, room?: string): RoomMetrics | null {
     const binding = this.bindings.get(name);
@@ -145,11 +189,18 @@ export class RoomChat {
   bind(store: RoomStore, name: string, link: RoomLink): void {
     if (this.stopped) return;
     const state = store.get(name), digest = state?.current.digest; if (!digest || !state) return;
-    const room = state.current.room, counted = this.counts.get(name);
+    const room = state.current.room, rosterMembers = roomMembers(state.current).map(member => member.fingerprint).sort().join(","), counted = this.counts.get(name);
     if (counted?.room !== room && (counted || this.counts.size < 64)) this.counts.set(name, { room, outbound: 0, inbound: 0, withheld: 0 });
     const saved = this.bindings.get(name);
-    const binding = saved?.store === store && saved.link === link && saved.room === room ? saved : { store, name, room, link, digest, online: false, states: new Map<string, PeerState>() };
-    if (binding.digest !== digest) { binding.states.clear(); binding.online = false; binding.digest = digest; }
+    const binding: Binding = saved?.store === store && saved.link === link && saved.room === room ? saved : {
+      store, name, room, link, digest, rosterMembers, online: false, states: new Map<string, PeerState>(), observedAt: new Map<string, number>(), observedMembers: new Set<string>(),
+    };
+    const tracked = link.livenessTracked;
+    if (binding.digest !== digest || binding.rosterMembers !== rosterMembers
+      || tracked !== undefined && binding.tracked !== undefined && tracked !== binding.tracked) {
+      binding.states.clear(); binding.observedAt.clear(); binding.observedMembers.clear(); binding.online = false; binding.digest = digest; binding.rosterMembers = rosterMembers;
+    }
+    if (tracked !== undefined) binding.tracked = tracked;
     this.bindings.set(name, binding);
     this.reconcileDispositions(binding);
     this.refreshInvocationHolds(binding);
@@ -165,6 +216,14 @@ export class RoomChat {
     } };
   }
   private refreshTargets(): void {
+    const now = this.presenceNow();
+    // Consume an expired observation once. Keeping its timestamp makes every
+    // later queue callback revisit this branch and can re-reserve settled rows.
+    if (now !== undefined) for (const binding of this.bindings.values()) if (this.livenessTracked(binding) !== false) {
+      for (const [member, seenAt] of binding.observedAt) {
+        if (now >= seenAt && now - seenAt >= this.refreshMs * ROOM_PRESENCE_MISSES) binding.observedAt.delete(member);
+      }
+    }
     const candidates = new Map<string, Target[]>();
     for (const binding of this.bindings.values()) {
       const state = binding.store.get(binding.name);
@@ -225,7 +284,7 @@ export class RoomChat {
               this.count(binding, "outbound", withheld === true);
             }
             finally { this.refreshOutgoing(binding); this.queueChanged(); }
-          }, ready: () => this.options.bus.remoteSendAllowed(remote!), waiting: () => this.queueChanged(),
+          }, ready: () => this.options.bus.remoteSendAllowed(remote!) && this.targetSendable(id), waiting: () => this.queueChanged(),
           notSent: deliveryId => this.options.bus.requeueRemoteNotSent(remote!, deliveryId),
           queued: deliveryId => {
             const selected = this.targets.get(id);
@@ -292,7 +351,8 @@ export class RoomChat {
     }
     for (const [id, remote] of this.remotes) {
       const target = this.targets.get(id);
-      remote.presence(target?.peer === USER ? "idle" : target?.binding.states.get(id) ?? "offline", target?.binding.online === true);
+      const state = target?.peer === USER ? "idle" : target?.binding.states.get(id) ?? "offline";
+      remote.presence(state, target?.binding.online === true);
     }
     this.options.roster?.([...this.targets.keys()]);
   }
@@ -302,14 +362,23 @@ export class RoomChat {
       && this.policy.get(binding.name).includes(peer)
       && roomMembers(state.current).some(member => member.fingerprint === binding.store.identity.public.fingerprint && member.exposedPeers.includes(peer));
   }
-  presence(store: RoomStore, name: string, link: RoomLink, value: { member: string; peers: readonly RoomPresencePeer[] }): void {
+  presence(store: RoomStore, name: string, link: RoomLink, value: { member: string; peers: readonly RoomPresencePeer[]; restored?: true; observedAt?: number | null }): void {
     const binding = this.bindings.get(name), state = store.get(name);
     if (!binding || binding.store !== store || binding.link !== link || !state || !this.valid(binding)) return;
     const member = roomMembers(state.current).find(row => row.fingerprint === value.member);
     if (!member) return;
+    if (value.restored && binding.observedMembers.has(value.member)) return;
     for (const peer of member.exposedPeers) binding.states.delete(`${peer}@${member.label}`);
     for (const peer of value.peers) if (member.exposedPeers.includes(peer.id)) binding.states.set(`${peer.id}@${member.label}`, peer.state);
+    const now = this.presenceNow();
+    if (value.restored !== true) {
+      binding.observedMembers.add(member.fingerprint);
+      const receivedAt = Object.hasOwn(value, "observedAt") ? value.observedAt : now;
+      if (typeof receivedAt === "number" && Number.isSafeInteger(receivedAt) && receivedAt >= 0 && now !== undefined && receivedAt <= now) binding.observedAt.set(member.fingerprint, receivedAt);
+      else binding.observedAt.delete(member.fingerprint);
+    }
     this.refreshTargets();
+    this.queueChanged();
   }
   linkState(store: RoomStore, name: string, link: RoomLink, state: RoomLinkState): void {
     // stop() fences callbacks as part of ordinary shutdown; it is not a room
@@ -339,6 +408,9 @@ export class RoomChat {
     return [...new Set([...this.outgoing.values()].filter(({ binding, row }) => binding.store.get(binding.name)?.current.room === room && ACTIVE.has(row.state) && !row.disposition).map(({ row }) => row.application))];
   }
   private outcome(binding: Binding, row: RoomOutgoing): void {
+    // Refresh this snapshot before settlement callbacks synchronously re-enter
+    // queueChanged through Bus.onQueues.
+    this.refreshOutgoing(binding);
     const remote = this.remotes.get(row.remotePeer);
     if (row.state === "needs_review" && !row.disposition) {
       const journalRow = this.options.bus.queueShow(row.deliveryId);
@@ -356,6 +428,7 @@ export class RoomChat {
   }
   private settleStoredOutcome(binding: Binding, remote: RemotePeer | undefined, row: RoomOutgoing): boolean {
     if ((row.state !== "completed" && row.state !== "failed_safe") || row.disposition) return false;
+    this.refreshOutgoing(binding);
     const outcome = row.lateReceipt?.outcome ?? row.state;
     const reason = row.lateReceipt?.reason ?? row.reason ?? (outcome === "completed" ? "admitted" : "boundary_refused");
     const journalRow = this.options.bus.queueShow(row.deliveryId);
@@ -433,6 +506,7 @@ export class RoomChat {
     if (!this.valid(binding)) return;
     let rows: RoomOutgoing[];
     try { rows = binding.store.applicationOutbox(binding.name); } catch { return; }
+    this.refreshOutgoing(binding);
     for (const row of rows) {
       if (row.disposition) continue;
       const remote = this.remotes.get(row.remotePeer);
@@ -443,7 +517,7 @@ export class RoomChat {
         const current = this.currentOutgoingRow(binding, row);
         if (!this.options.bus.holdRemoteMissingIntent(remote, row.deliveryId, current, "proof-unavailable")) continue;
         const quarantined = binding.store.quarantineOutgoingPermanent(binding.name, row.deliveryId, "boundary_refused", current);
-        if (quarantined) remote.settled(row.deliveryId);
+        if (quarantined) { this.refreshOutgoing(binding); remote.settled(row.deliveryId); }
       } else if (row.state === "needs_review") this.holdStoreNeedsReview(binding, row, remote);
     }
     this.refreshOutgoing(binding);
@@ -566,6 +640,16 @@ export class RoomChat {
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined; if (this.stopped || !this.bindings.size) return;
     let next = this.options.bus.nextRemoteExpiry();
+    const presenceNow = this.presenceNow();
+    if (presenceNow !== undefined) {
+      if ([...this.bindings.values()].some(binding => this.livenessTracked(binding) !== false && [...binding.observedAt.values()].some(seenAt =>
+        presenceNow - seenAt >= this.refreshMs * ROOM_PRESENCE_MISSES))) this.refreshTargets();
+      for (const binding of this.bindings.values()) if (this.livenessTracked(binding) !== false) for (const seenAt of binding.observedAt.values()) {
+        const staleAt = seenAt + this.refreshMs * ROOM_PRESENCE_MISSES;
+        if (staleAt <= presenceNow) continue;
+        next = next === undefined ? staleAt : Math.min(next, staleAt);
+      }
+    }
     for (const { binding, row } of this.outgoing.values()) if ((row.state === "dispatching" || row.state === "accepted") && !row.disposition) {
       const due = Math.min(row.expiresAt, binding.online ? row.ackDeadline ?? Infinity : Infinity); next = next === undefined ? due : Math.min(next, due);
     }
@@ -588,6 +672,9 @@ export class RoomChat {
   }
   tick(): void {
     if (this.stopped) return;
+    const presenceNow = this.presenceNow();
+    if (presenceNow === undefined || [...this.bindings.values()].some(binding => this.livenessTracked(binding) !== false && [...binding.observedAt.values()].some(seenAt =>
+      presenceNow - seenAt >= this.refreshMs * ROOM_PRESENCE_MISSES))) this.refreshTargets();
     this.options.bus.expireRemoteQueues(this.now());
     for (const binding of this.bindings.values()) if (this.valid(binding)) {
       try {
@@ -603,11 +690,18 @@ export class RoomChat {
     }
     void this.retryPending(); this.queueChanged();
   }
-  private async resumeActive(binding: Binding): Promise<void> {
+  private async resumeActive(binding: Binding, codecMember?: string, changedFeatures?: readonly RoomCodecFeature[]): Promise<void> {
     if (!binding.online || !this.valid(binding)) return;
     try {
-      const active = binding.store.applicationOutbox(binding.name, true).filter(row => (row.state === "dispatching" || row.state === "accepted")
-        && !this.personHeldInvocations.get(binding.name)?.has(row.deliveryId));
+      const active = binding.store.applicationOutbox(binding.name, true).filter(row => {
+        if (row.state !== "dispatching" && row.state !== "accepted" || this.personHeldInvocations.get(binding.name)?.has(row.deliveryId)) return false;
+        if (codecMember === undefined) return true;
+        if (row.recipient !== codecMember) return false;
+        let required: RoomCodecFeature | undefined;
+        if (row.peer === USER) required = "person_inbox_v1";
+        else if (this.options.bus.queueShow(row.deliveryId)?.originals.some(isInvocationKind)) required = "read_invocation_v1";
+        return required !== undefined && (changedFeatures === undefined || changedFeatures.includes(required));
+      });
       for (const row of active) this.remotes.get(row.remotePeer)?.reservePending(row.deliveryId);
       for (const row of active) this.launchResume(binding, row);
     } catch { /* The next authenticated online edge will retry durable rows. */ }
@@ -664,6 +758,10 @@ export class RoomChat {
     const digest = state?.current.digest;
     const proofCurrent = () => this.storeProofCurrent(binding, row, remote, target, digest);
     if (!target || !state || target.binding !== binding || !proofCurrent()) { remote.deferResume(row.deliveryId); return; }
+    let required: RoomCodecFeature | undefined;
+    if (isInvocationKind(original)) required = "read_invocation_v1";
+    else if (row.peer === USER) required = "person_inbox_v1";
+    if (required && !binding.link.codecSupported(row.recipient, required)) { remote.deferResume(row.deliveryId); return; }
     const ready = () => binding.online && this.options.bus.remoteSendAllowed(remote);
     if (!ready()) { remote.waitForReady(row.deliveryId); return; }
     let readinessLost = false;
@@ -713,16 +811,18 @@ export class RoomChat {
   }
   private reconcileDispositions(binding: Binding): boolean {
     let complete = true;
+    const settled: Array<{ peer: string; deliveryId: string }> = [];
     for (const row of binding.store.applicationOutbox(binding.name)) if (!row.disposition) {
       const action = this.options.bus.remoteDisposition(row.deliveryId);
       if (action) try {
         const disposed = binding.store.disposeApplication(binding.name, row.deliveryId, action, true, () => this.valid(binding)
           && binding.store.get(binding.name)?.current.digest === binding.digest && this.options.bus.remoteDisposition(row.deliveryId) === action);
-        if (disposed?.disposition === action) this.remotes.get(row.remotePeer)?.settled(row.deliveryId);
+        if (disposed?.disposition === action) settled.push({ peer: row.remotePeer, deliveryId: row.deliveryId });
       }
       catch { complete = false; }
     }
     this.refreshOutgoing(binding);
+    for (const row of settled) this.remotes.get(row.peer)?.settled(row.deliveryId);
     return complete;
   }
   disposition(peer: string, deliveryId: string, action: "completed" | "retry" | "discard"): void {
@@ -734,7 +834,10 @@ export class RoomChat {
       const disposed = binding.store.disposeApplication(binding.name, deliveryId, action, true, () => this.valid(binding)
         && binding.store.get(binding.name)?.current.room === room && binding.store.get(binding.name)?.current.digest === digest
         && this.options.bus.remoteDisposition(deliveryId) === action);
-      if (disposed?.disposition === action) this.remotes.get(peer)?.settled(deliveryId);
+      if (disposed?.disposition === action) {
+        this.refreshOutgoing(binding);
+        this.remotes.get(peer)?.settled(deliveryId);
+      }
       this.personHeldInvocations.get(binding.name)?.delete(deliveryId);
       this.refreshOutgoing(binding); break;
     }
@@ -756,20 +859,56 @@ export class RoomChat {
     const row = this.evidenceCache.get(deliveryId); if (!row || row.peer !== peer) return undefined;
     const { peer: _peer, ...view } = row; return view;
   }
+  /** Hold only the sealed intents captured by the person's committed epoch change. */
+  epochRotated(store: RoomStore, name: string, previousDigest: string, expected: readonly RoomOutgoing[]): boolean {
+    const state = store.get(name);
+    if (this.stopped || !state || state.left || state.current.digest === previousDigest) return false;
+    const binding = this.bindings.get(name);
+    if (binding?.store === store && binding.room === state.current.room) {
+      // Releasing an old FIFO head must not drain queued work using old presence.
+      binding.online = false; binding.states.clear(); binding.observedAt.clear();
+      for (const [id, remote] of this.remotes) if (this.targets.get(id)?.binding === binding) remote.presence("offline", false);
+    }
+    let complete = true;
+    for (const before of expected) {
+      const current = () => {
+        const room = store.get(name), row = store.applicationOutbox(name).find(row => row.deliveryId === before.deliveryId);
+        return !this.stopped && !!room && !room.left && room.current.digest === state.current.digest
+          && !!row && row.application === before.application && row.remotePeer === before.remotePeer && row.recipient === before.recipient
+          && row.state === "needs_review" && row.reason === "boundary_refused" && !row.disposition;
+      };
+      if (!current()) { complete = false; continue; }
+      if (!this.options.bus.holdRemoteEpochRotated(before.remotePeer, before.deliveryId, state.current.room, before.recipient, current)) {
+        complete = false; continue;
+      }
+      const remote = this.remotes.get(before.remotePeer);
+      if (remote?.remoteRoom === state.current.room && remote.remoteMember === before.recipient) remote.settled(before.deliveryId);
+    }
+    this.evidenceCache = undefined;
+    return complete;
+  }
   rows(name: string): Record<string, unknown>[] {
     const binding = this.bindings.get(name); if (!binding) return [];
     const incoming = binding.store.applicationStatus(name);
-    return [...binding.store.applicationOutbox(name).sort((a, b) => Number(!ACTIVE.has(a.state) || !!a.disposition) - Number(!ACTIVE.has(b.state) || !!b.disposition) || b.createdAt - a.createdAt).slice(0, 200).map(row => ({ direction: "outbound", id: row.deliveryId, application: row.application, peer: row.remotePeer, state: row.state === "completed" ? completedText(row.reason) : row.state, ...(row.disposition ? { disposition: row.disposition } : {}), ...(row.lateReceipt ? { lateReceipt: lateReceiptText(row.lateReceipt) } : {}), ...(refusalReason(row) ? { refusalReason: refusalReason(row) } : {}) })),
+    const outgoing = binding.store.applicationOutbox(name).sort((a, b) => Number(!ACTIVE.has(a.state) || !!a.disposition) - Number(!ACTIVE.has(b.state) || !!b.disposition) || b.createdAt - a.createdAt).slice(0, 200), epochHolds = new Set<string>();
+    for (const peer of new Set(outgoing.map(row => row.remotePeer))) {
+      for (const row of this.options.bus.queueList(peer, true)) if (row.state === "needs_review" && row.reason === `${ROOM_EPOCH_ROTATED_REASON} ${row.id}`) epochHolds.add(row.id);
+    }
+    return [...outgoing.map(row => ({ direction: "outbound", id: row.deliveryId, application: row.application, peer: row.remotePeer, state: row.state === "completed" ? completedText(row.reason) : row.state, ...(row.disposition ? { disposition: row.disposition } : {}), ...(row.lateReceipt ? { lateReceipt: lateReceiptText(row.lateReceipt) } : {}), ...(epochHolds.has(row.deliveryId) ? { holdReason: "epoch rotated" } : refusalReason(row) ? { refusalReason: refusalReason(row) } : {}) })),
       ...incoming.rows.map(row => ({ direction: "inbound", id: row.digest, application: row.application, state: row.state === "disposed" ? `disposed (${row.disposition}, by person)` : row.state, peer: row.peer, ...(row.disposedAt ? { disposedAt: row.disposedAt } : {}) })),
       { direction: "inbound", pending: incoming.pending, needsReview: incoming.needsReview, truncated: incoming.truncated }];
   }
-  peers(name: string): { id: string; state: PeerState }[] {
-    return [...this.targets].filter(([, target]) => target.binding.name === name && target.peer !== USER).map(([id]) => ({ id, state: this.remotes.get(id)?.state ?? "offline" })).sort((a, b) => a.id.localeCompare(b.id));
+  peers(name: string): { id: string; state: PeerState; presence?: PeerState | "unknown"; liveness?: "untracked" }[] {
+    return [...this.targets].filter(([, target]) => target.binding.name === name && target.peer !== USER)
+      .map(([id, target]) => ({ id, state: this.remotes.get(id)?.state ?? "offline", presence: this.advisoryPresence(id, target), ...(this.advisoryLiveness(target) ? { liveness: "untracked" as const } : {}) })).sort((a, b) => a.id.localeCompare(b.id));
   }
   /** A bounded status list, separate from the explicit detail query above. */
-  peersForStatus(name: string): { id: string; state: PeerState }[] | null {
+  peersForStatus(name: string): { id: string; state: PeerState; presence?: PeerState | "unknown"; liveness?: "untracked" }[] | null {
     const ids = this.statusTargets.get(name);
-    return ids ? ids.map(id => ({ id, state: this.remotes.get(id)?.state ?? "offline" })) : null;
+    return ids ? ids.map(id => {
+      const target = this.targets.get(id)!;
+      return { id, state: this.remotes.get(id)?.state ?? "offline", presence: this.advisoryPresence(id, target), ...(this.advisoryLiveness(target) ? { liveness: "untracked" as const } : {}) };
+    }) : null;
   }
   stop(): void {
     if (this.stopped) return; this.stopped = true;

package/src/rooms/status.ts

@@ -2,6 +2,7 @@ import { types } from "node:util";
 import type { PeerState } from "../hub/envelope.ts";
 import { decodeBase64url, encodeBase64url } from "./crypto.ts";
 import { parseRemotePeerId } from "./application.ts";
+import { ROOM_HEALTH_CAUSES, roomHealthNextStep, type RoomHealthCause } from "./health.ts";
 
 const ROOM_LIMIT = 64;
 const REMOTE_PEER_LIMIT = 4096;
@@ -15,9 +16,18 @@ const EPOCH = /^[1-9][0-9]{0,19}$/;
 const LINK_STATES = new Set(["online", "connecting", "offline", "left"]);
 const PEER_STATES = new Set<PeerState>(["idle", "busy", "paused", "offline"]);
 
+export interface RoomStatusHealth {
+  refused: { invalid_presence: number; wrong_epoch: number; trust_changed: number; stale: number; invalid_frame: number } | null;
+  outboxDepth: number | null;
+  oldestOutboxAgeMs: number | null;
+  lastReceiptAgeMs: number | null;
+}
+
 export interface RoomStatusPeer {
   id: string;
   state: PeerState;
+  presence?: PeerState | "unknown";
+  liveness?: "untracked";
 }
 
 export interface RoomRelayStats {
@@ -27,8 +37,15 @@ export interface RoomRelayStats {
   withheld: number | null;
 }
 
+export interface RoomStatusDiagnostics {
+  health?: RoomStatusHealth | null;
+  linkCause?: RoomHealthCause | null;
+  linkNextStep?: string | null;
+}
+export interface RoomStatusUnavailable { code: RoomHealthCause | null; nextStep: string | null }
+
 /** Allowlisted room metadata. Missing member counts and peer lists stay unknown. */
-export interface RoomStatusView {
+export interface RoomStatusView extends RoomStatusDiagnostics {
   name: string;
   room: string;
   owner: string;
@@ -95,8 +112,13 @@ function remotePeers(value: unknown, remaining: number): RoomStatusPeer[] | null
     if (!plainRecord(item)) return null;
     const id = ownData(item, "id"), state = ownData(item, "state");
     if (typeof id !== "string" || !parseRemotePeerId(id) || typeof state !== "string" || !PEER_STATES.has(state as PeerState) || ids.has(id)) return null;
+    const presenceField = ownField(item, "presence"), livenessField = ownField(item, "liveness");
+    if (presenceField.present && !Object.hasOwn(presenceField, "value") || livenessField.present && !Object.hasOwn(livenessField, "value")) return null;
+    const presence = presenceField.value, liveness = livenessField.value;
+    if (presence !== undefined && presence !== "unknown" && (typeof presence !== "string" || !PEER_STATES.has(presence as PeerState))) return null;
+    if (liveness !== undefined && liveness !== "untracked") return null;
     ids.add(id);
-    result.push({ id, state: state as PeerState });
+    result.push({ id, state: state as PeerState, ...(presence !== undefined ? { presence: presence as RoomStatusPeer["presence"] } : {}), ...(liveness === "untracked" ? { liveness } : {}) });
   }
   return result;
 }
@@ -116,6 +138,46 @@ function relayStats(value: unknown): RoomRelayStats | null {
   return { since, outbound, inbound, withheld };
 }
 
+/** Counts and ages remain unknown when an older daemon cannot report them. */
+export function projectRoomHealth(value: unknown): RoomStatusHealth | null {
+  if (!plainRecord(value)) return null;
+  const rawRefused = ownData(value, "refused");
+  let refused: RoomStatusHealth["refused"] = null;
+  if (plainRecord(rawRefused)) {
+    const invalid_presence = relayCount(ownData(rawRefused, "invalid_presence")), wrong_epoch = relayCount(ownData(rawRefused, "wrong_epoch"));
+    const trust_changed = relayCount(ownData(rawRefused, "trust_changed")), stale = relayCount(ownData(rawRefused, "stale")), invalid_frame = relayCount(ownData(rawRefused, "invalid_frame"));
+    if (invalid_presence !== null && wrong_epoch !== null && trust_changed !== null && stale !== null && invalid_frame !== null)
+      refused = { invalid_presence, wrong_epoch, trust_changed, stale, invalid_frame };
+  }
+  return { refused, outboxDepth: relayCount(ownData(value, "outboxDepth")),
+    oldestOutboxAgeMs: relayCount(ownData(value, "oldestOutboxAgeMs")), lastReceiptAgeMs: relayCount(ownData(value, "lastReceiptAgeMs")) };
+}
+
+function healthCause(value: unknown): RoomHealthCause | null {
+  return typeof value === "string" && ROOM_HEALTH_CAUSES.includes(value as RoomHealthCause) ? value as RoomHealthCause : null;
+}
+
+/** Regenerate guidance from closed causes; arbitrary daemon text is never copied. */
+export function projectRoomDiagnostics(value: unknown): RoomStatusDiagnostics {
+  if (!plainRecord(value)) return {};
+  const cause = healthCause(ownData(value, "linkCause"));
+  const result: RoomStatusDiagnostics = {};
+  if (ownField(value, "health").present) result.health = projectRoomHealth(ownData(value, "health"));
+  if (ownField(value, "linkCause").present) {
+    result.linkCause = cause;
+    result.linkNextStep = null;
+    if (cause !== null) result.linkNextStep = roomHealthNextStep(cause);
+  }
+  return result;
+}
+
+/** Absent or malformed availability metadata stays unknown without evaluating getters. */
+export function projectRoomUnavailable(value: unknown): RoomStatusUnavailable | null {
+  if (!plainRecord(value)) return null;
+  const code = healthCause(ownData(value, "code"));
+  return { code, nextStep: code === null ? null : roomHealthNextStep(code) };
+}
+
 /** Project RoomCommands.rows-compatible data to body-free room status metadata. */
 export function projectRoomStatus(value: unknown): RoomStatusView[] {
   try {
@@ -139,6 +201,7 @@ export function projectRoomStatus(value: unknown): RoomStatusView[] {
         memberCount: memberCount(rawMemberCount),
         remotePeers: peers,
         relays: relayStats(ownData(item, "relays")),
+        ...projectRoomDiagnostics(item),
       });
     }
     return views;

package/src/rooms/store.ts

@@ -2,6 +2,7 @@
 import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
+import type { RoomHealth } from "./health.ts";
 import { realPath } from "../hub/project.ts";
 import { MAX_HOP, USER } from "../hub/envelope.ts";
 import { assertRoomCryptoReady, exportHubIdentityForStorage, generateHubIdentity, importHubIdentity, decodeBase64url, encodeBase64url, sha256, type HubIdentity, type LocalIdentityRecord } from "./crypto.ts";
@@ -673,6 +674,12 @@ export class RoomStore {
       ON CONFLICT(name) DO UPDATE SET epoch=excluded.epoch,digest=excluded.digest,wire=excluded.wire,previous_wire=excluded.previous_wire,previous_digest=excluded.previous_digest,previous_epoch=excluded.previous_epoch,previous_expires=excluded.previous_expires,left=0`)
       .run(name, current.room, broker, decodeRoster(wire).owner, current.epoch, current.digest, wire, prior ? priorWire! : null, prior?.epoch.digest ?? null, prior?.epoch.epoch ?? null, prior?.expiresAt ?? null);
     this.db.query("DELETE FROM pending_joins WHERE name=?").run(name);
+    if (previous && !same) {
+      // Epoch adoption and the old sealed intents' send fence commit together.
+      // The local Bus names the rotation; no new signed receipt reason is introduced.
+      this.db.query("UPDATE application_outbox SET state='needs_review',reason='boundary_refused' WHERE room=? AND state IN ('dispatching','accepted') AND disposition IS NULL").run(current.room);
+      this.db.query("DELETE FROM outbox WHERE room=? AND digest IN (SELECT t.digest FROM application_attempts t JOIN application_outbox a ON a.room=t.room AND a.delivery_id=t.delivery_id WHERE t.room=? AND a.state='needs_review' AND a.reason='boundary_refused')").run(current.room, current.room);
+    }
     return next;
   }
   async install(input: { name: string; broker: string; wire: Uint8Array; expectedDigest: string | null; current?: () => boolean; reactivate?: boolean }): Promise<RoomState> {
@@ -1102,6 +1109,10 @@ export class RoomStore {
     const filter = activeOnly ? " AND state IN ('dispatching','accepted','needs_review') AND disposition IS NULL" : "";
     return this.db.query<OutgoingRow, [string]>(`SELECT * FROM application_outbox WHERE room=?${filter} ORDER BY rowid`).all(state.current.room).map(outgoing);
   }
+  /** Sealed, unresolved intents that a person must see before changing the epoch. */
+  rotationPending(name: string): RoomOutgoing[] {
+    return this.applicationOutbox(name, true).filter(row => row.state === "dispatching" || row.state === "accepted");
+  }
   /** Compatibility no-op for retryable rows; only original TTL expiry creates needs_review. */
   quarantineOutgoing(name: string, deliveryId: string): RoomOutgoing | undefined {
     const state = this.get(name); if (!state) return undefined;
@@ -1548,9 +1559,27 @@ export class RoomStore {
     });
   }
   refused(name: string): RoomRefusal[] {
-    const state = this.get(name); if (!state) return [];
+    this.now(); named(name); const state = this.rooms.get(name); if (!state) return [];
     return this.db.query<RoomRefusal, [string]>("SELECT digest,reason,at FROM refusals WHERE room=? ORDER BY rowid").all(state.current.room);
   }
+  /** Metadata-only diagnostics. No durable clock write, sealed frame or plaintext read. */
+  health(name: string): RoomHealth {
+    const now = this.now(); named(name); const state = this.rooms.get(name);
+    if (!state) fail("untrusted");
+    const refused: RoomHealth["refused"] = { invalid_presence: 0, wrong_epoch: 0, trust_changed: 0, stale: 0, invalid_frame: 0 };
+    for (const row of this.db.query<{ reason: RoomRefusalReason; count: number }, [string]>("SELECT reason,COUNT(*) AS count FROM refusals WHERE room=? GROUP BY reason").all(state.current.room)) refused[row.reason] = row.count;
+    const pending = this.db.query<{ depth: number; dated: number; oldest: number | null }, [string, number]>(`SELECT COUNT(*) AS depth, COUNT(COALESCE(r.created_at,a.created_at)) AS dated, MIN(COALESCE(r.created_at,a.created_at)) AS oldest
+      FROM outbox o LEFT JOIN application_attempts t ON t.room=o.room AND t.digest=o.digest
+      LEFT JOIN application_outbox a ON a.room=t.room AND a.delivery_id=t.delivery_id
+      LEFT JOIN receipt_outbox r ON r.room=o.room AND r.receipt_digest=o.digest
+      WHERE o.room=? AND (t.digest IS NULL OR a.state IN ('dispatching','accepted'))
+      AND (r.receipt_digest IS NULL OR r.state='dispatching' AND r.expires_at>?)`).get(state.current.room, now)!;
+    const receipt = this.db.query<{ at: number | null }, [string]>(`SELECT MAX(i.received_at) AS at FROM inbox i
+      JOIN application_outbox a ON a.room=i.room AND a.receipt_digest=i.digest WHERE i.room=?`).get(state.current.room)?.at;
+    return { refused, outboxDepth: pending.depth,
+      oldestOutboxAgeMs: pending.depth > 0 && pending.dated === pending.depth && pending.oldest !== null ? now - pending.oldest : null,
+      lastReceiptAgeMs: receipt != null ? now - receipt : null };
+  }
   /** Read-only physical-cap hint for a validated host payload; no body is loaded and no replay/clock row is written. */
   ordinaryInboxAvailable(name: string, bytes: number): boolean {
     this.now(); named(name);