@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/bus.ts

@@ -1,8 +1,11 @@
 import { appendNote, DIGEST, frame, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
+import type { DoingKind } from "./peer-doing.ts";
+import type { QueuePressure } from "./queue-backpressure.ts";
 import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
 import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
 import { MAX_DEFERRED_HUB, RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
+import { parseRemotePeerId } from "../rooms/application.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
@@ -22,6 +25,10 @@ export type BusEvent =
   | { t: "state"; peer: PeerId; state: PeerState };
 
 export interface BusOptions {
+  /** Durable application outbox ids; the bus combines them with its own pending ids without recursion. */
+  remotePending?: (room: string) => readonly string[];
+  /** Host provenance at enqueue, never a body screen; unknown/throw marks the original private. */
+  remotePrivate?: (env: Readonly<Envelope>) => boolean | undefined;
   /** Live project membership; absent preserves the existing audience and delivery behaviour. */
   rostered?: (peer: PeerId) => boolean;
   /** Transient owner lifecycle fence: retain new work without changing console/budget pauses. */
@@ -34,9 +41,16 @@ export interface BusOptions {
   /** How long a status envelope may wait for company before it is delivered on its own. */
   batchMs: number;
   queueCap: number;
+  /** Accepted live operational settings; read only at the next matching delivery/note operation. */
+  maxAttempts?: () => number;
+  digestMax?: () => number;
+  pullBudgetBytes?: () => number;
+  notesKept?: () => number;
   /** Optional: rewrite a delivery before it goes out (M6 digest condensation). Must return its input on any failure. */
   condense?: (envs: Envelope[]) => Promise<Envelope[]>;
   journal?: DeliveryJournal;
+  /** Host-owned opt-in; no delivery body or timestamp is a routing-policy authority. */
+  trackQueuePressure?: () => boolean;
   /**
    * Optional: may an agent send this envelope now (issue #38)? `parent` is the id of what it answers. A reason refuses
    * it, and the sender hears it on its next delivery.
@@ -59,6 +73,8 @@ export interface BusOptions {
    * dequeued, steered or journaled for it, and the queue still waits for `Bus.pull`; a throw is swallowed.
    */
   onImportantQueued?: (peer: PeerId, counts: { queued: number; important: number }) => void;
+  /** Optional (#878): an attached adapter observed its session title or current plan item. Never published, journaled or tapped. */
+  doing?: (peer: PeerId, kind: DoingKind, text?: unknown) => void;
 }
 
 /** Serializable delivery state used by the controlled restart coordinator. Bodies stay in the private daemon file. */
@@ -70,8 +86,16 @@ export interface BusSnapshot {
   attempts: Record<string, number>;
   withdrawn: string[];
   manualPaused?: string[];
+  /** Host enqueue provenance only. null means an age lost to a legacy/restored writer. */
+  queuedAt?: Record<string, Record<string, number | null>>;
   /** Hub notices accepted during recovery, durable but outside the carried delivery queues. */
   deferredHub?: Envelope[];
+  /** Local enqueue deadlines; absent old metadata is unknown, never a fresh TTL. */
+  remoteQueueExpires?: Record<string, Record<string, number>>;
+  /** Host room binding for retained queues, never reconstructed from a remote label. */
+  remoteQueueRooms?: Record<string, string>;
+  /** Original verified target identity; a reused room label cannot inherit queued text. */
+  remoteQueueMembers?: Record<string, string>;
   journal?: ReturnType<DeliveryJournal["snapshot"]>;
 }
 
@@ -99,14 +123,20 @@ function resolveTo(to: PeerId[], originals: Envelope[] | undefined): PeerId[] {
 }
 
 const SEEN_CAP = 2048;
-const MAX_ATTEMPTS = 3;
+export const MAX_ATTEMPTS = 3;
+// ponytail: provenance is capped at 2048 ids/peer, 4096 peers, 100000 ids total and 256 KiB per snapshot.
+// Omitted metadata means unknown age only; use a measured per-envelope store if larger queues need provenance.
+const QUEUE_TIME_CAP = 2048, QUEUE_TIME_PEERS_CAP = 4096, QUEUE_TIME_TOTAL_CAP = 100_000, QUEUE_TIME_SNAPSHOT_BYTES = 256 * 1024;
+const REMOTE_ROOM_CAP = 200, REMOTE_QUEUE_TTL_MS = 24 * 60 * 60 * 1000;
+const remoteId = (id: string): boolean => id.includes("@");
+const remoteFingerprint = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
 // ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
 // Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
-const DIGEST_MAX = 10;
+export const DIGEST_MAX = 10;
 // #713: a pull-only peer reads between steps, often minutes apart, so one pull drains its queue up to this many bytes of rendered text instead of ten items.
 // Bounded, not unbounded: a queue larger than the budget takes more than one pull, and the reply says how many are still waiting. Push peers keep DIGEST_MAX.
-const PULL_BUDGET_BYTES = 64 * 1024;
-const NOTES_KEPT = 10;
+export const PULL_BUDGET_BYTES = 64 * 1024;
+export const NOTES_KEPT = 10;
 
 /**
  * N-peer fan-out. Never delivers back to `from`, caps hops, dedupes by id. Each peer has one queue,
@@ -118,7 +148,15 @@ export class Bus {
   private readonly opts: BusOptions;
   private readonly journal?: DeliveryJournal;
   private readonly queues = new Map<PeerId, Envelope[]>();
+  private readonly queueTimes = new Map<PeerId, Map<string, number | null>>();
+  private queueTimeEntries = 0;
+  private queuePressureWasTracked = false;
   private readonly prefaces = new Map<PeerId, Envelope>();
+  private readonly remoteQueueMembers = new Map<PeerId, string>();
+  private readonly remoteQueueRooms = new Map<PeerId, string>();
+  private readonly remoteQueueExpires = new Map<PeerId, Map<string, number>>();
+  private readonly remoteReservations = new Map<string, Set<string>>();
+  private readonly remoteTransport = new Map<string, { peer: string; originals: Envelope[] }>();
   private readonly paused = new Set<PeerId>();
   private readonly manualPaused = new Set<PeerId>();
   private readonly timers = new Map<PeerId, ReturnType<typeof setTimeout>>();
@@ -168,6 +206,7 @@ export class Bus {
     this.opts = { ...DEFAULT_BUS, ...opts };
     this.onDeliver = opts.onDeliver;
     this.journal = opts.journal;
+    this.trackingQueuePressure();
     if (this.journal) {
       const state = this.journal.snapshot();
       const bus = state.bus as BusSnapshot;
@@ -191,9 +230,22 @@ export class Bus {
   }
 
   add(peer: PeerAdapter): void {
+    if (peer.remoteRoom !== undefined && (!parseRemotePeerId(peer.id) || typeof peer.remoteRoom !== "string" || !peer.remoteRoom || peer.remoteRoom.length > 256 || !remoteFingerprint(peer.remoteMember))) throw new Error("invalid remote peer binding");
+    const pendingRemote = peer.remoteRoom !== undefined && this.hasRemoteWork(peer.id);
+    if (peer.remoteRoom !== undefined && pendingRemote) {
+      const room = this.remoteQueueRooms.get(peer.id), member = this.remoteQueueMembers.get(peer.id);
+      if (room === undefined || member === undefined) {
+        this.expireRemoteQueues();
+        if (this.hasRemoteWork(peer.id)) throw new Error("remote queued identity binding unavailable");
+      } else if (room !== peer.remoteRoom) throw new Error("remote queued room binding changed");
+      else if (member !== peer.remoteMember) throw new Error("remote queued member binding changed");
+    }
+    if (peer.remoteRoom !== undefined && !pendingRemote) { this.remoteQueueRooms.delete(peer.id); this.remoteQueueMembers.delete(peer.id); }
     this.peers.set(peer.id, peer);
     if (!this.queues.has(peer.id)) this.queues.set(peer.id, []);
     peer.onDelivery = (receipt) => this.deliveryReceipt(peer.id, receipt);
+    peer.onDoing = (kind, text) => { if (!this.closed && this.peers.get(peer.id) === peer) this.opts.doing?.(peer.id, kind, text); };
+    this.opts.doing?.(peer.id, "reset"); // a new adapter never shows what the one it replaces was doing
     peer.onMessage = (text, opts) => {
       if (!this.isRostered(peer.id)) return `off roster: ${peer.id}`;
       const { priority, body } = parseMarker(text);
@@ -208,6 +260,12 @@ export class Bus {
       const audienceOriginals = originals ?? (opts?.to?.includes(DIGEST) && condensed ? last?.originals : undefined);
       const to = opts?.to?.length ? resolveTo(opts.to, audienceOriginals) : undefined;
       let env = newEnvelope(peer.id, body, { ...opts, ...(to ? { to } : {}), priority: opts?.priority ?? capPriority(peer, priority, opts?.inReplyTo, originals) });
+      try { this.checkRemotePublication(env); }
+      catch (error) {
+        if (!(error instanceof PreEffectToolRefusal)) throw error;
+        this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered: ${error.message}`));
+        return error.message;
+      }
       const offRoster = this.offRosterRecipients(env);
       if (offRoster.length && offRoster.length === new Set(env.to?.filter(id => id !== env.from)).size) {
         const reason = `off roster: ${offRoster.join(", ")}`;
@@ -233,7 +291,13 @@ export class Bus {
         this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered: ${refused}`));
         return refused;
       }
-      const published = this.publishResult(env);
+      let published: PublishResult;
+      try { published = this.publishResult(env); }
+      catch (error) {
+        if (!(error instanceof PreEffectToolRefusal)) throw error;
+        this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered: ${error.message}`));
+        return error.message;
+      }
       if (offRoster.length && published.dropped !== "hop") this.note(peer.id, noteLine(HUB, "decision", `your message is retained off roster for ${offRoster.join(", ")}; delivered to the other recipients`));
       // The sender's result (issue #107): a turn answer has no caller, so it hears it on its next delivery. It counts as
       // not sent only when nobody got it.
@@ -267,10 +331,11 @@ export class Bus {
 
   private persist(): void {
     if (!this.journal) return;
+    const tracking = this.trackingQueuePressure();
     try {
       this.journal.transaction(() => {
         for (const outcome of this.pendingOutcomes) this.journal!.createDelivery(outcome);
-        this.journal!.persistBus(this.snapshotWithoutJournal(), [...this.manualPaused]);
+        this.journal!.persistBus(this.snapshotWithoutJournal(), [...this.manualPaused], tracking);
       });
       this.pendingOutcomes.length = 0;
       this.storageError = undefined;
@@ -281,7 +346,7 @@ export class Bus {
   private durableHandoff(peer: PeerId, deliveryId: string, originals: Envelope[], out: Envelope[], observe = true): void {
     if (!this.journal) return;
     const delivery = { id: deliveryId, peer, state: "dispatching" as const, createdAt: Date.now(), originals, out };
-    this.journal.checkpointDelivery(this.snapshotWithoutJournal(), delivery);
+    this.journal.checkpointDelivery(this.snapshotWithoutJournal(), delivery, this.trackingQueuePressure());
     if (observe) this.memoryDelivery(peer, deliveryId, out, "rendered", originals);
   }
 
@@ -375,16 +440,39 @@ export class Bus {
 
   /** A bounded, JSON-safe representation of queued work and retry/dedupe state. */
   snapshot(includeJournal = true): BusSnapshot {
+    const rooms = this.remoteRoomSnapshot(), members = this.remoteMemberSnapshot();
+    const queues = Object.fromEntries([...this.queues].map(([id, queue]) => [id, queue.map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) }))]));
+    for (const peer of new Set([...Object.keys(rooms), ...Object.keys(members)])) queues[peer] ??= [];
     const out: BusSnapshot = {
       schemaVersion: 1,
-      queues: Object.fromEntries([...this.queues].map(([id, queue]) => [id, queue.map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) }))])),
+      queues,
       prefaces: Object.fromEntries([...this.prefaces].map(([id, e]) => [id, { ...e, ...(e.to ? { to: [...e.to] } : {}) }])),
       seen: [...this.seen.values()].map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) })),
       attempts: Object.fromEntries(this.attempts),
       withdrawn: [...this.withdrawn],
       manualPaused: [...this.manualPaused],
       ...(this.deferredHub.size ? { deferredHub: structuredClone([...this.deferredHub.values()]) } : {}),
+      ...(this.remoteQueueExpires.size ? { remoteQueueExpires: this.remoteExpirySnapshot() } : {}),
+      ...(Object.keys(rooms).length ? { remoteQueueRooms: rooms } : {}),
+      ...(Object.keys(members).length ? { remoteQueueMembers: members } : {}),
     };
+    if (this.trackingQueuePressure()) {
+      // Metadata is advisory: omit capped or unknown entries rather than enlarge a delivery without bound.
+      const queuedAt = Object.create(null) as NonNullable<BusSnapshot["queuedAt"]>;
+      let bytes = 32;
+      for (const [peer, queue] of this.queues) {
+        const times = Object.create(null) as Record<string, number>;
+        const peerBytes = Buffer.byteLength(JSON.stringify(peer)) + 4;
+        for (const env of queue) {
+          const at = this.queueTimes.get(peer)?.get(env.id);
+          const entryBytes = Buffer.byteLength(JSON.stringify(env.id)) + 20;
+          if (typeof at !== "number" || bytes + peerBytes + entryBytes > QUEUE_TIME_SNAPSHOT_BYTES) continue;
+          times[env.id] = at; bytes += entryBytes;
+        }
+        if (Object.keys(times).length) { queuedAt[peer] = times; bytes += peerBytes; }
+      }
+      if (Object.keys(queuedAt).length) out.queuedAt = queuedAt;
+    }
     if (includeJournal && this.journal) out.journal = this.journal.snapshot();
     return out;
   }
@@ -395,7 +483,7 @@ export class Bus {
     if (_operationId && this.journal) {
       const current = this.journal.snapshot();
       if (current.revision === 0) {
-        this.journal.importSnapshot(snapshot.journal ?? { schemaVersion: 1, revision: 1, instanceId: this.journal.instanceId, bus: snapshot, deliveries: [], manualPaused: snapshot.manualPaused ?? [] }, _operationId);
+        this.journal.importSnapshot(snapshot.journal ?? { schemaVersion: 1, revision: 1, instanceId: this.journal.instanceId, bus: snapshot, deliveries: [], manualPaused: snapshot.manualPaused ?? [] }, _operationId, this.trackingQueuePressure());
       }
       const committedQueues = snapshot.queues;
       snapshot = this.journal.snapshot().bus;
@@ -417,6 +505,24 @@ export class Bus {
     for (const env of deferred) this.deferredHub.set(env.id, structuredClone(env));
     this.queues.clear();
     for (const [id, queue] of Object.entries(snapshot.queues ?? {})) this.queues.set(id, queue.map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) })));
+    this.queueTimes.clear(); this.queueTimeEntries = 0;
+    if (this.trackingQueuePressure()) for (const [peer, queue] of this.queues) {
+      const provenance = snapshot.queuedAt;
+      const times = provenance && typeof provenance === "object" && !Array.isArray(provenance) && Object.hasOwn(provenance, peer) ? provenance[peer] : undefined;
+      for (const env of queue) {
+        const at = times && typeof times === "object" && !Array.isArray(times) && Object.hasOwn(times, env.id) ? times[env.id] : null;
+        this.recordQueueTime(peer, env.id, typeof at === "number" && Number.isSafeInteger(at) && at > 0 ? at : null);
+      }
+    }
+    this.remoteQueueMembers.clear();
+    for (const [peer, member] of Object.entries(snapshot.remoteQueueMembers ?? {})) if (parseRemotePeerId(peer) && remoteFingerprint(member)) this.remoteQueueMembers.set(peer, member);
+    this.remoteQueueRooms.clear();
+    for (const [peer, room] of Object.entries(snapshot.remoteQueueRooms ?? {})) if (parseRemotePeerId(peer) && typeof room === "string" && room.length > 0 && room.length <= 256) this.remoteQueueRooms.set(peer, room);
+    this.remoteQueueExpires.clear();
+    for (const [peer, values] of Object.entries(snapshot.remoteQueueExpires ?? {})) {
+      if (!remoteId(peer)) continue;
+      this.remoteQueueExpires.set(peer, new Map(Object.entries(values).filter(([, expiry]) => Number.isSafeInteger(expiry) && expiry >= 0)));
+    }
     this.prefaces.clear();
     for (const [id, e] of Object.entries(snapshot.prefaces ?? {})) this.prefaces.set(id, { ...e, body: uniqueMemoryLines(e.body), ...(e.to ? { to: [...e.to] } : {}) });
     this.seen.clear();
@@ -460,6 +566,7 @@ export class Bus {
   }
 
   private retryOut(peer: string, originals: Envelope[], out: Envelope[]): Envelope[] {
+    if (remoteId(peer)) return out;
     if (!out.length || !this.journal || !this.journal.retryWarning(peer, originals)) return out;
     return out.map((env, index) => {
       if (index !== 0) return env;
@@ -474,6 +581,7 @@ export class Bus {
 
   resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string, actor: string = "user"): void {
     if (!this.journal || this.storageError) throw new Error("delivery journal unavailable");
+    this.trackingQueuePressure();
     const record = this.queueShow(id);
     if (!record) throw new Error("unknown delivery");
     const previous = this.journal.resolution(id);
@@ -481,6 +589,13 @@ export class Bus {
       this.journal.resolve(id, revision, action, reason, revision, actor); // verifies identical request; no second enqueue
       return;
     }
+    if (action === "retry" && remoteId(record.peer)) {
+      const peer = this.peers.get(record.peer), room = this.remoteQueueRooms.get(record.peer), member = this.remoteQueueMembers.get(record.peer);
+      if (record.state !== "needs_review" || record.originals.length !== 1 || !room || !remoteFingerprint(member) || peer?.remoteRoom !== room || peer.remoteMember !== member) throw new Error("remote original identity unavailable or changed; discard it or send a new message explicitly");
+      const deadline = this.remoteQueueExpires.get(record.peer)?.get(record.originals[0]!.id);
+      if (!Number.isSafeInteger(deadline) || deadline! <= Date.now()) throw new PreEffectToolRefusal("remote original deadline unavailable or expired; discard it or send a new message explicitly");
+      this.checkRemotePublication(record.originals[0]!);
+    }
     const recipientConsent = actor === `peer:${record.peer}` && action === "retry" && record.state === "needs_review";
     // #713: a `queued` delivery was never handed to the peer, so nothing is in flight and a busy peer (a pull-only TUI is busy most of the time) does not block
     // discarding it. `dispatching` and `accepted` stay refused, and every other resolution keeps the busy fence.
@@ -489,7 +604,7 @@ export class Bus {
     if (this.peers.get(record.peer)?.state === "busy" && !recipientConsent && !queuedDiscard) throw new Error("peer busy: its delivery cannot be resolved while it works");
     if (record.revision !== revision) throw new Error("stale delivery revision");
     if (record.state === "queued" && action === "retry") throw new Error("queued delivery is already scheduled");
-    if (action === "retry" && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
+    if (action === "retry" && !remoteId(record.peer) && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
     const queue = this.queues.get(record.peer) ?? [];
     const hadQueue = this.queues.has(record.peer);
     const before = [...queue];
@@ -549,8 +664,22 @@ export class Bus {
     if (this.closed) return;
     const owner = this.activeDeliveries.get(receipt.id);
     if (!owner || owner !== peer || !this.journal) return;
+    this.trackingQueuePressure();
     const id = receipt.id;
     const before = this.journal.get(id);
+    if (this.peers.get(peer)?.remoteRoom !== undefined && receipt.state === "failed_safe") {
+      // A signed recipient NACK is a terminal known refusal, not a failed native
+      // turn eligible for poison retries. It records no recipient read evidence.
+      this.journal.transition(id, "failed", receipt.reason ?? "remote recipient refused safely");
+      this.activeDeliveries.delete(id); this.remoteTransport.delete(id);
+      for (const env of before?.originals ?? []) { this.attempts.delete(`${peer}:${env.id}`); this.remoteQueueExpires.get(peer)?.delete(env.id); }
+      const last = this.lastDelivery.get(peer);
+      if (before && last && last.out.length === before.out.length && last.out.every((env, index) => env.id === before.out[index]!.id)) this.lastDelivery.delete(peer);
+      this.refreshRecoveryHold(peer);
+      this.onQueues?.();
+      void this.drain(peer);
+      return;
+    }
     const state: JournalDeliveryState = receipt.state === "accepted" ? "accepted" : receipt.state === "completed" ? "completed" : receipt.state === "failed_safe" ? "failed" : "needs_review";
     if (state === "failed" || state === "needs_review") this.deliveryFailed(peer);
     if (state === "completed") this.journal.completeDelivered(id, peer, "adapter", receipt.reason);
@@ -578,6 +707,7 @@ export class Bus {
 
   completeReply(peer: PeerId, envelopeId: string): void {
     if (!this.journal) return;
+    this.trackingQueuePressure();
     for (const [id, owner] of this.activeDeliveries) {
       if (owner !== peer) continue;
       const row = this.journal.get(id);
@@ -654,6 +784,7 @@ export class Bus {
 
   /** Context the hub wants the peer to see once: it rides in front of the next delivery instead of costing a turn of its own. */
   preface(id: PeerId, text: string): void {
+    if (remoteId(id)) return;
     const body = uniqueMemoryLines(quoteNotes(text));
     const existing = this.prefaces.get(id);
     if (existing) {
@@ -669,15 +800,17 @@ export class Bus {
 
   /** Another peer's shared note: rides in the preface like recall. The newest NOTES_KEPT stay; older ones remain in amem. */
   note(id: PeerId, line: string): void {
+    if (remoteId(id)) return;
     const existing = this.prefaces.get(id);
-    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
+    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), this.opts.notesKept?.() ?? NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
     this.persist();
   }
 
   /** A preface that went out with a failed delivery comes back ahead of whatever was prefaced meanwhile, instead of replacing it. */
   private restorePreface(id: PeerId, env: Envelope): void {
+    if (remoteId(id)) return;
     const now = this.prefaces.get(id);
-    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), NOTES_KEPT) });
+    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), this.opts.notesKept?.() ?? NOTES_KEPT) });
   }
 
   /**
@@ -687,6 +820,7 @@ export class Bus {
    */
   discardDeferredHub(reason: string): string[] {
     if (this.peers.size || this.flushingHub || this.replayingHub || !this.journal || this.storageError) throw new Error("deferred reset requires a stopped, readable delivery journal");
+    this.trackingQueuePressure();
     const pending = [...this.deferredHub];
     const settled: string[] = [];
     try {
@@ -713,6 +847,137 @@ export class Bus {
     return [...(this.queues.get(peer) ?? []), ...[...this.deferredHub.values()].filter(e => e.to?.includes(peer))];
   }
 
+  /** Own accepted queue/preparation/active ids, without consulting the host callback. */
+  remotePendingIds(room: string): string[] {
+    const ids = new Set<string>();
+    for (const [peer, queue] of this.queues) if ((this.remoteQueueRooms.get(peer) ?? this.peers.get(peer)?.remoteRoom) === room) for (const env of queue) ids.add(env.id);
+    for (const [peer, batch] of this.preparing) if ((this.remoteQueueRooms.get(peer) ?? this.peers.get(peer)?.remoteRoom) === room) for (const env of batch) ids.add(env.id);
+    for (const { peer, originals } of this.remoteTransport.values()) if ((this.remoteQueueRooms.get(peer) ?? this.peers.get(peer)?.remoteRoom) === room) for (const env of originals) ids.add(env.id);
+    for (const [id, peer] of this.activeDeliveries) if ((this.remoteQueueRooms.get(peer) ?? this.peers.get(peer)?.remoteRoom) === room) for (const env of this.journal?.get(id)?.originals ?? []) ids.add(env.id);
+    return [...ids];
+  }
+  /** Remote preflight precedes limiter admission; publication rechecks before effects. */
+  checkRemotePublication(env: Envelope): string[] {
+    if (env.to?.some(remoteId) && this.opts.remotePrivate) {
+      try { if (this.opts.remotePrivate(env) !== false) env.private = true; }
+      catch { env.private = true; }
+    }
+    const rooms = new Set<string>(), targets = [...new Set((env.to ?? []).filter(remoteId))];
+    if (remoteId(env.from) && !parseRemotePeerId(env.from)) throw new PreEffectToolRefusal("invalid remote sender");
+    for (const target of targets) {
+      const peer = this.peers.get(target);
+      if (!parseRemotePeerId(target) || !peer?.remoteRoom || !remoteFingerprint(peer.remoteMember)) throw new PreEffectToolRefusal("remote recipient unavailable");
+      const bound = this.remoteQueueRooms.get(target), member = this.remoteQueueMembers.get(target);
+      if (this.hasRemoteWork(target) && (!bound || !member || bound !== peer.remoteRoom || member !== peer.remoteMember)) throw new PreEffectToolRefusal("remote queued identity binding changed");
+      const ttl = peer.remoteQueueTtlMs ?? REMOTE_QUEUE_TTL_MS;
+      if (!Number.isSafeInteger(ttl) || ttl <= 0 || !Number.isSafeInteger(Date.now() + ttl)) throw new PreEffectToolRefusal("remote queue TTL unavailable");
+      rooms.add(peer.remoteRoom);
+    }
+    // ponytail: one original has one stable wire identity. A follow-up may derive
+    // stable per-target wire ids and account each delivery separately before fan-out.
+    if (targets.length > 1) throw new PreEffectToolRefusal(`remote targets ${targets.slice(0, 64).join(", ")}${targets.length > 64 ? ` and ${targets.length - 64} more` : ""}: send to each remote peer separately`);
+    for (const room of rooms) {
+      const pending = new Set([...this.remotePendingIds(room), ...(this.remoteReservations.get(room) ?? [])]);
+      let external: readonly string[];
+      try { external = this.opts.remotePending?.(room) ?? []; } catch { throw new PreEffectToolRefusal("remote queue unavailable"); }
+      if (!Array.isArray(external) || external.length > REMOTE_ROOM_CAP || external.some(id => typeof id !== "string" || id.length < 1 || id.length > 256)) throw new PreEffectToolRefusal("remote queue unavailable");
+      for (const id of external) pending.add(id);
+      pending.add(env.id);
+      if (pending.size > REMOTE_ROOM_CAP) throw new PreEffectToolRefusal("remote room queue is full");
+    }
+    return [...rooms];
+  }
+  private hasRemoteWork(peer: string, pending?: ReadonlySet<string>): boolean {
+    return (this.queues.get(peer)?.length ?? 0) > 0 || this.preparing.has(peer) || [...this.activeDeliveries.values()].includes(peer) || [...this.remoteTransport.values()].some(value => value.peer === peer) || (pending ?? new Set(this.journal?.pendingPeers() ?? [])).has(peer);
+  }
+  private remoteBindingSnapshot(values: ReadonlyMap<string, string>): Record<string, string> {
+    if (!values.size) return {};
+    const pending = new Set(this.journal?.pendingPeers() ?? []);
+    return Object.fromEntries([...values].filter(([peer]) => this.hasRemoteWork(peer, pending)));
+  }
+  private remoteMemberSnapshot(): Record<string, string> { return this.remoteBindingSnapshot(this.remoteQueueMembers); }
+  private remoteRoomSnapshot(): Record<string, string> { return this.remoteBindingSnapshot(this.remoteQueueRooms); }
+  private remoteExpirySnapshot(): Record<string, Record<string, number>> {
+    const snapshot: Record<string, Record<string, number>> = {};
+    for (const [peer, expiries] of this.remoteQueueExpires) {
+      const pending = new Set([...(this.queues.get(peer) ?? []), ...(this.preparing.get(peer) ?? [])].map(env => env.id));
+      for (const { peer: target, originals } of this.remoteTransport.values()) if (target === peer) for (const env of originals) pending.add(env.id);
+      for (const [id, target] of this.activeDeliveries) if (target === peer) for (const env of this.journal?.get(id)?.originals ?? []) pending.add(env.id);
+      // Uncertainty is still pending work. Keep its known TTL through checkpoints,
+      // using unresolved rows only, never completed delivery history.
+      for (const row of this.journal?.unresolved(peer) ?? []) for (const env of row.originals) pending.add(env.id);
+      for (const id of expiries.keys()) if (!pending.has(id)) expiries.delete(id);
+      if (expiries.size) snapshot[peer] = Object.fromEntries(expiries);
+      else this.remoteQueueExpires.delete(peer);
+    }
+    return snapshot;
+  }
+  /** Metadata-only timer hint; an unknown retained deadline/binding is due immediately. */
+  nextRemoteExpiry(): number | undefined {
+    let next: number | undefined;
+    for (const [peer, queue] of this.queues) {
+      if (!remoteId(peer) || !queue.length) continue;
+      if (!this.remoteQueueRooms.has(peer) || !this.remoteQueueMembers.has(peer)) return Date.now();
+      const expiries = this.remoteQueueExpires.get(peer);
+      for (const env of queue) {
+        const expiry = expiries?.get(env.id);
+        if (expiry === undefined) return Date.now();
+        next = next === undefined ? expiry : Math.min(next, expiry);
+      }
+    }
+    return next;
+  }
+  /** Expiry is a durable uncertain outcome, never a silent retry/drop or a fresh timestamp. */
+  expireRemoteQueues(now = Date.now()): number {
+    if (!Number.isSafeInteger(now) || now < 0) throw new Error("invalid remote queue clock");
+    if (!this.journal || this.closed) return 0; // Without a journal there is no durable sink for uncertain work.
+    const expired = [...this.queues].filter(([peer]) => remoteId(peer)).flatMap(([peer, queue]) => queue.filter(env => {
+      const expiry = this.remoteQueueExpires.get(peer)?.get(env.id);
+      return this.remoteQueueRooms.get(peer) === undefined || this.remoteQueueMembers.get(peer) === undefined || expiry === undefined || expiry <= now;
+    }).map(env => ({ peer, env })));
+    if (!expired.length) return 0;
+    const queues = new Map([...this.queues].map(([peer, queue]) => [peer, [...queue]]));
+    const expiries = new Map([...this.remoteQueueExpires].map(([peer, values]) => [peer, new Map(values)]));
+    const held = [...this.recoveryHeldPeers], outcomes = this.pendingOutcomes.length;
+    try {
+      for (const { peer, env } of expired) {
+        const queue = this.queues.get(peer)!;
+        const index = queue.findIndex(item => item.id === env.id);
+        if (index >= 0) queue.splice(index, 1);
+        const known = this.remoteQueueExpires.get(peer)?.has(env.id);
+        this.remoteQueueExpires.get(peer)?.delete(env.id);
+        this.pendingOutcomes.push({ id: crypto.randomUUID(), peer, state: "needs_review", createdAt: now, originals: [env], out: [env], reason: !known ? "remote queue expiry unavailable after restore" : !this.remoteQueueRooms.has(peer) ? "remote queue room binding unavailable after restore" : !this.remoteQueueMembers.has(peer) ? "remote queue member binding unavailable after restore" : "remote queue expired before recipient admission" });
+        this.recoveryHeldPeers.add(peer);
+      }
+      this.persist();
+    } catch (error) {
+      for (const [peer, before] of queues) this.queues.get(peer)!.splice(0, this.queues.get(peer)!.length, ...before);
+      this.remoteQueueExpires.clear(); for (const [peer, values] of expiries) this.remoteQueueExpires.set(peer, values);
+      this.recoveryHeldPeers.clear(); for (const peer of held) this.recoveryHeldPeers.add(peer);
+      this.pendingOutcomes.length = outcomes;
+      throw error;
+    }
+    this.onQueues?.();
+    return expired.length;
+  }
+  /** A room may acknowledge local admission only with a live, known-available journal. */
+  deliveryJournalAvailable(): boolean { return this.journal !== undefined && !this.storageError && !this.closed; }
+  /** Explicit person disposition metadata only, never inferred from transport completion. */
+  remoteDisposition(deliveryId: string): "completed" | "retry" | "discard" | undefined {
+    const resolution = this.journal?.resolution(deliveryId);
+    return resolution?.actor === "user" ? resolution.action : undefined;
+  }
+  /** A late signed queue receipt is evidence for the person; it never auto-settles uncertainty. */
+  noteLateRemoteReceipt(peer: string, deliveryId: string, outcome: "completed" | "failed_safe"): boolean {
+    if ((outcome !== "completed" && outcome !== "failed_safe") || !parseRemotePeerId(peer) || !this.peers.get(peer)?.remoteRoom || !this.journal || this.storageError || this.closed) return false;
+    const row = this.journal.get(deliveryId), adapter = this.peers.get(peer)!;
+    if (!row || row.peer !== peer || row.state !== "needs_review" || this.remoteQueueRooms.get(peer) !== adapter.remoteRoom || this.remoteQueueMembers.get(peer) !== adapter.remoteMember) return false;
+    const reason = outcome === "completed" ? "late signed completed receipt: remote queue admitted; remains needs_review" : "late signed failed_safe receipt; remains needs_review";
+    if (row.reason !== reason) this.journal.transition(row.id, "needs_review", reason, row.revision);
+    this.onQueues?.();
+    return true;
+  }
+
   /** Returns the peers the envelope was accepted for, including durable deferred notices. */
   publish(env: Envelope): PeerId[] {
     return this.publishResult(env).targets;
@@ -722,6 +987,7 @@ export class Bus {
   publishResult(env: Envelope): PublishResult {
     if (this.storageError) throw new Error("delivery journal unavailable");
     if (this.seen.has(env.id) || this.deferredHub.has(env.id)) return { targets: [] };
+    this.checkRemotePublication(env);
     if (this.recoveryHeld && (this.deferHub || this.replayingHub) && env.from === HUB && env.priority !== "fyi" && env.hop <= MAX_HOP) {
       if (this.deferredHub.size >= MAX_DEFERRED_HUB) throw new RecoveryDeferredHubError();
       const targets = this.audience(env);
@@ -737,48 +1003,52 @@ export class Bus {
   private publishNow(env: Envelope): PublishResult {
     if (this.storageError) throw new Error("delivery journal unavailable");
     if (this.seen.has(env.id)) return { targets: [] };
-    this.seen.set(env.id, env);
-    if (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
-
-    // fyi is for the record (console now, task board from M4), never worth an agent's turn.
-    const dropped = env.hop > MAX_HOP ? "hop" : env.priority === "fyi" ? "fyi" : undefined;
-    this.emit({ t: "envelope", env, ...(dropped ? { dropped } : {}) });
-    if (dropped) { this.persist(); return { targets: [], dropped }; }
-
-    const hushed = this.hushed(env);
-    if (hushed.length) this.emit({ t: "quiet", env, peers: hushed.map((h) => h.peer), reason: hushed[0]!.reason });
-    const targets = this.audience(env).filter((id) => !hushed.some((h) => h.peer === id) || !this.isRostered(id));
-    this.suppressDrain = !!this.journal;
-    try { for (const id of targets) {
-      const peer = this.peers.get(id);
-      if (!peer) { this.enqueue(id, env); continue; }
-      if (!this.journal && !this.held(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
-        // Not queued while the steer is in flight, or an idle transition would deliver it a second time.
-        this.steering++;
-        const deliveryId = crypto.randomUUID();
-        this.activeDeliveries.set(deliveryId, id);
-        if (this.journal) this.durableHandoff(id, deliveryId, [env], [env]);
-        const steerResult = this.journal ? peer.steer([env], deliveryId) : peer.steer([env]);
-        steerResult.then(() => { this.delivered(id, [env]); }).catch(() => {
-          this.deliveryFailed(id);
-          if (this.journal) this.journal.transition(deliveryId, "needs_review", "adapter steering outcome is uncertain");
-          this.activeDeliveries.delete(deliveryId);
-          if (!this.journal) this.enqueue(id, env, true);
-        }).finally(() => { this.steering--; });
-      } else this.enqueue(id, env);
-    } } finally { this.suppressDrain = false; }
-    if (this.journal) {
-      this.persist();
-      if (!this.flushingHub) this.onQueues?.();
-      for (const id of targets) {
+    const rooms = this.checkRemotePublication(env);
+    for (const room of rooms) { const reserved = this.remoteReservations.get(room) ?? new Set<string>(); reserved.add(env.id); this.remoteReservations.set(room, reserved); }
+    try {
+      this.seen.set(env.id, env);
+      if (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
+
+      // fyi is for the record (console now, task board from M4), never worth an agent's turn.
+      const dropped = env.hop > MAX_HOP ? "hop" : env.priority === "fyi" ? "fyi" : undefined;
+      this.emit({ t: "envelope", env, ...(dropped ? { dropped } : {}) });
+      if (dropped) { this.persist(); return { targets: [], dropped }; }
+
+      const hushed = this.hushed(env);
+      if (hushed.length) this.emit({ t: "quiet", env, peers: hushed.map((h) => h.peer), reason: hushed[0]!.reason });
+      const targets = this.audience(env).filter((id) => !hushed.some((h) => h.peer === id) || !this.isRostered(id));
+      this.suppressDrain = !!this.journal;
+      try { for (const id of targets) {
         const peer = this.peers.get(id);
-        if (!this.held(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
-        else void this.drain(id);
+        if (!peer) { this.enqueue(id, env); continue; }
+        if (!this.journal && !this.held(id) && env.priority === "important" && !remoteId(id) && peer.steer && this.stateOf(id) === "busy") {
+          // Not queued while the steer is in flight, or an idle transition would deliver it a second time.
+          this.steering++;
+          const deliveryId = crypto.randomUUID();
+          this.activeDeliveries.set(deliveryId, id);
+          if (this.journal) this.durableHandoff(id, deliveryId, [env], [env]);
+          const steerResult = this.journal ? peer.steer([env], deliveryId) : peer.steer([env]);
+          steerResult.then(() => { this.delivered(id, [env]); }).catch(() => {
+            this.deliveryFailed(id);
+            if (this.journal) this.journal.transition(deliveryId, "needs_review", "adapter steering outcome is uncertain");
+            this.activeDeliveries.delete(deliveryId);
+            if (!this.journal) this.enqueue(id, env, true);
+          }).finally(() => { this.steering--; });
+        } else this.enqueue(id, env);
+      } } finally { this.suppressDrain = false; }
+      if (this.journal) {
+        this.persist();
+        if (!this.flushingHub) this.onQueues?.();
+        for (const id of targets) {
+          const peer = this.peers.get(id);
+          if (!this.held(id) && env.priority === "important" && !remoteId(id) && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
+          else void this.drain(id);
+        }
       }
-    }
-    const offRoster = targets.filter(id => !this.isRostered(id));
-    if (offRoster.length) this.emit({ t: "off_roster", env, peers: offRoster });
-    return { targets };
+      const offRoster = targets.filter(id => !this.isRostered(id));
+      if (offRoster.length) this.emit({ t: "off_roster", env, peers: offRoster });
+      return { targets };
+    } finally { for (const room of rooms) { const reserved = this.remoteReservations.get(room); reserved?.delete(env.id); if (!reserved?.size) this.remoteReservations.delete(room); } }
   }
 
   isRostered(peer: PeerId): boolean { return this.opts.rostered?.(peer) ?? true; }
@@ -798,7 +1068,7 @@ export class Bus {
   /** Who an envelope is queued for: its `to`, or every peer but its sender. */
   audience(env: Envelope): PeerId[] {
     const known = new Set([...this.peers.keys(), ...this.queues.keys(), ...(this.journal?.list().map((d) => d.peer) ?? [])]);
-    return (env.to ?? [...this.peers.keys()]).filter((id) => id !== env.from && (known.has(id) || !this.isRostered(id)) && (env.to !== undefined || this.isRostered(id)));
+    return (env.to ?? [...this.peers.keys()]).filter((id) => id !== env.from && (known.has(id) || !this.isRostered(id)) && (env.to !== undefined || this.isRostered(id)) && (env.to !== undefined || !remoteId(id)));
   }
 
   /** The recipients of `env` that the silence policy holds it back from, each with why (issue #107). */
@@ -875,7 +1145,7 @@ export class Bus {
   }
 
   private memoryDelivery(peer: PeerId, id: string, out: Envelope[], field: "rendered" | "delivered", originals: Envelope[] = out): void {
-    if ([...out, ...originals].some(env => env.private)) return;
+    if (remoteId(peer) || [...out, ...originals].some(env => env.private || remoteId(env.from) || env.to?.some(remoteId))) return;
     try { this.onMemoryDelivery?.(peer, id, out, field); } catch { /* optional telemetry never alters delivery */ }
   }
 
@@ -896,6 +1166,54 @@ export class Bus {
     return this.queues.get(id)?.length ?? 0;
   }
 
+  /** New automatic offers use only bounded pending metadata, never queue/history bodies. */
+  assignmentQueue(peer: PeerId): QueuePressure {
+    const queued = this.queued(peer), tracking = this.trackingQueuePressure();
+    if (this.storageError) return { queued };
+    if (queued === 0) return { queued: 0, oldestQueuedAt: null };
+    if (!tracking) return { queued };
+    // A durable summary cannot revive provenance that this host discarded while tracking was off.
+    const times = this.queueTimes.get(peer);
+    let oldest: number | undefined;
+    for (const env of this.queues.get(peer) ?? []) {
+      const at = times?.get(env.id);
+      if (typeof at !== "number" || !Number.isSafeInteger(at) || at <= 0) return { queued };
+      oldest = oldest === undefined ? at : Math.min(oldest, at);
+    }
+    if (this.journal) {
+      try {
+        const saved = this.journal.pendingQueueMetadata(peer);
+        return saved?.queued === queued ? saved : { queued };
+      } catch { return { queued }; }
+    }
+    return oldest === undefined ? { queued } : { queued, oldestQueuedAt: oldest };
+  }
+
+  private trackingQueuePressure(): boolean {
+    let tracking = false;
+    try { tracking = this.opts.trackQueuePressure?.() === true; } catch { /* unknown policy is not enabled */ }
+    if (!tracking && this.queuePressureWasTracked) { this.queueTimes.clear(); this.queueTimeEntries = 0; }
+    this.queuePressureWasTracked = tracking;
+    this.journal?.setQueueMetadataTracking(tracking);
+    return tracking;
+  }
+
+  private recordQueueTime(peer: PeerId, id: string, at: number | null): void {
+    if (!this.trackingQueuePressure()) return;
+    let times = this.queueTimes.get(peer);
+    if (!times) {
+      if (this.queueTimes.size >= QUEUE_TIME_PEERS_CAP) this.dropQueueTimes(this.queueTimes.keys().next().value!);
+      this.queueTimes.set(peer, times = new Map());
+    }
+    if (!times.has(id)) { times.set(id, at); this.queueTimeEntries++; }
+    while (times.size > QUEUE_TIME_CAP) { times.delete(times.keys().next().value!); this.queueTimeEntries--; }
+    while (this.queueTimeEntries > QUEUE_TIME_TOTAL_CAP) this.dropQueueTimes(this.queueTimes.keys().next().value!);
+  }
+  private dropQueueTimes(peer: PeerId): void {
+    this.queueTimeEntries -= this.queueTimes.get(peer)?.size ?? 0;
+    this.queueTimes.delete(peer);
+  }
+
   /**
    * Queued envelopes that skip the batch window (issue #41: `queued 3` hid which ones the peer still waits out).
    * An `important` envelope that is in a queue is one that could not be steered, so it does not interrupt a
@@ -930,8 +1248,14 @@ export class Bus {
     const replace = !front && key ? queue.findIndex((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`)) : -1;
     const preparing = !front && key ? this.preparing.get(id)?.find((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`) && !this.withdrawn.has(old.id)) : undefined;
     let queuedEnv = preparing ? { ...env, ts: Math.min(preparing.ts, env.ts) } : env;
+    const clock = this.trackingQueuePressure() ? Date.now() : 0;
+    let enteredAt = this.queueTimes.get(id)?.has(env.id) ? this.queueTimes.get(id)!.get(env.id)!
+      : front || this.flushingHub || !Number.isSafeInteger(clock) || clock <= 0 ? null : clock;
+    if (this.trackingQueuePressure() && !this.queueTimes.get(id)?.has(env.id) && queue.some(old => old.id === env.id)) enteredAt = null;
+    if (preparing) enteredAt = this.queueTimes.get(id)?.get(preparing.id) ?? null;
     if (replace >= 0) {
       const old = queue[replace]!;
+      enteredAt = this.queueTimes.get(id)?.get(old.id) ?? null;
       // Keep the first milestone's deadline, so continuous updates cannot create another batching window.
       queuedEnv = { ...queuedEnv, ts: Math.min(old.ts, queuedEnv.ts) };
       queue[replace] = queuedEnv;
@@ -939,16 +1263,26 @@ export class Bus {
       this.discardQueued(id, old, "superseded supervision milestone");
     } else if (front) queue.unshift(queuedEnv);
     else queue.push(queuedEnv);
+    this.recordQueueTime(id, queuedEnv.id, enteredAt);
     if (preparing && !this.withdrawn.has(preparing.id)) {
       this.markWithdrawn(preparing.id);
       this.discardQueued(id, preparing, "superseded supervision milestone during preparation");
     }
-    if (queue.length > this.opts.queueCap) {
+    if (!remoteId(id) && queue.length > this.opts.queueCap) {
       const victim = queue.findIndex((e) => e.priority !== "important");
       const [lost] = queue.splice(victim === -1 ? 0 : victim, 1);
       if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer: id, state: "failed", createdAt: Date.now(), originals: [lost!], out: [], reason: "queue capacity exceeded" });
       this.emit({ t: "overflow", env: lost!, peer: id });
     }
+    if (remoteId(id) && !front) {
+      const room = this.peers.get(id)?.remoteRoom;
+      if (room !== undefined) this.remoteQueueRooms.set(id, room);
+      const member = this.peers.get(id)?.remoteMember;
+      if (member !== undefined) this.remoteQueueMembers.set(id, member);
+      const expiries = this.remoteQueueExpires.get(id) ?? new Map<string, number>();
+      if (!expiries.has(env.id)) expiries.set(env.id, Date.now() + (this.peers.get(id)?.remoteQueueTtlMs ?? REMOTE_QUEUE_TTL_MS));
+      this.remoteQueueExpires.set(id, expiries);
+    }
     if (queuedEnv.priority === "important" && this.peers.get(id)?.pullOnly) {
       // Advisory only (issue #398): the envelope stays queued for `pull`; the hook must never affect it.
       const counts = { queued: queue.length, important: queue.filter((e) => e.priority === "important").length };
@@ -1009,7 +1343,9 @@ export class Bus {
 
   /** A push may go out now: nothing holds the queue, the peer is idle, and its session shows pushes (issue #205). */
   private deliverable(id: PeerId): boolean {
-    return !this.held(id) && this.stateOf(id) === "idle" && !this.peers.get(id)?.pullOnly;
+    const peer = this.peers.get(id);
+    const remoteBinding = !remoteId(id) || !!peer?.remoteRoom && this.remoteQueueRooms.get(id) === peer.remoteRoom && this.remoteQueueMembers.get(id) === peer.remoteMember;
+    return remoteBinding && !this.held(id) && this.stateOf(id) === "idle" && !peer?.pullOnly;
   }
 
   /**
@@ -1024,6 +1360,7 @@ export class Bus {
    * steps if loss is ever observed.
    */
   pull(id: PeerId): Envelope[] | undefined {
+    if (remoteId(id)) return undefined; // A local inbox read is not signed remote queue admission.
     if (this.storageError) throw new Error("delivery journal unavailable");
     if (this.held(id)) return undefined;
     const queue = this.queues.get(id) ?? [];
@@ -1061,22 +1398,23 @@ export class Bus {
 
   private async drain(id: PeerId): Promise<void> {
     if (this.storageError || this.draining.has(id) || !this.peers.has(id)) return;
+    if (remoteId(id)) this.expireRemoteQueues();
     this.draining.add(id);
     try {
       const peer = this.peers.get(id)!;
       const queue = this.queues.get(id)!;
       while (!this.storageError && queue.length && this.deliverable(id)) {
         if (this.dropIrrelevant(id, queue) && !queue.length) break;
-        const delay = this.wait(queue);
+        const delay = remoteId(id) ? 0 : this.wait(queue);
         if (delay > 0) { this.arm(id, delay); break; }
-        const preface = this.prefaces.get(id);
+        const preface = remoteId(id) ? undefined : this.prefaces.get(id);
         // Durable queues retain the batch while asynchronous condensation runs. Another publish
         // may checkpoint during that wait; it must not checkpoint the batch out of existence.
         if (!this.journal) this.prefaces.delete(id);
         const batch = this.take(id, queue, !this.journal);
         this.preparing.set(id, batch);
         const delivery = preface ? [preface, ...batch] : batch;
-        const mayCondense = this.opts.condense && !delivery.some((e) => e.priority === "important");
+        const mayCondense = this.opts.condense && !remoteId(id) && !delivery.some((e) => e.priority === "important" || remoteId(e.from));
         this.condensing += mayCondense ? 1 : 0;
         let out: Envelope[];
         try {
@@ -1096,7 +1434,7 @@ export class Bus {
         }
         const deliveryId = crypto.randomUUID();
         if (this.journal) {
-          if (this.prefaces.get(id) !== preface || batch.some((e) => !queue.some((item) => item.id === e.id))) continue;
+          if ((!remoteId(id) && this.prefaces.get(id) !== preface) || batch.some((e) => !queue.some((item) => item.id === e.id))) continue;
           const queued = [...queue], seen = [...this.seen];
           for (const env of batch) queue.splice(queue.findIndex((item) => item.id === env.id), 1);
           this.prefaces.delete(id);
@@ -1112,8 +1450,14 @@ export class Bus {
           this.activeDeliveries.set(deliveryId, id);
         } else this.remember(out);
         this.lastDelivery.set(id, { out, originals: delivery });
+        if (remoteId(id)) this.remoteTransport.set(deliveryId, { peer: id, originals: delivery });
         this.preparing.delete(id); // from here on the transport/journal owns settlement
         try {
+          if (remoteId(id)) {
+            const env = delivery[0], expiry = env && this.remoteQueueExpires.get(id)?.get(env.id);
+            if (!env || delivery.length !== 1 || expiry === undefined || expiry <= Date.now() || !peer.setRemoteDeadline) throw new Error("remote queue deadline unavailable");
+            peer.setRemoteDeadline(env.id, expiry);
+          }
           try { this.onDeliver?.(id, delivery); } catch { /* observation must never affect delivery */ }
           if (this.journal) await peer.deliver(out, deliveryId);
           else { await peer.deliver(out); this.delivered(id, delivery); }
@@ -1121,7 +1465,7 @@ export class Bus {
           if (this.journal) this.uncertain(id, deliveryId, "adapter delivery outcome is uncertain");
           else this.failed(id, delivery);
           break;
-        }
+        } finally { this.remoteTransport.delete(deliveryId); }
       }
     } catch { this.storageError = "delivery journal unavailable"; }
     finally { this.preparing.delete(id); this.draining.delete(id); this.onQueues?.(); }
@@ -1166,13 +1510,14 @@ export class Bus {
    * An envelope that already failed once goes alone, so a poison one cannot take a digest down with it.
    */
   private take(id: PeerId, queue: Envelope[], remove = true): Envelope[] {
+    const digestMax = this.opts.digestMax?.() ?? DIGEST_MAX;
     const ordered = [...queue.filter((e) => e.priority === "important"), ...queue.filter((e) => e.priority !== "important")];
     const batch: Envelope[] = [];
     for (const env of ordered) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
       batch.push(env);
-      if (failedBefore || batch.length === DIGEST_MAX) break;
+      if (failedBefore || remoteId(id) || batch.length === digestMax) break;
     }
     if (remove) for (const env of batch) queue.splice(queue.indexOf(env), 1);
     return batch;
@@ -1184,13 +1529,14 @@ export class Bus {
    * envelope cannot stall the queue. An envelope that already failed once still goes alone, as in `take`.
    */
   private takeBudget(id: PeerId, queue: Envelope[]): Envelope[] {
+    const pullBudgetBytes = this.opts.pullBudgetBytes?.() ?? PULL_BUDGET_BYTES;
     const batch: Envelope[] = [];
     let bytes = 0;
     for (const env of queue) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
       const size = Buffer.byteLength(frame(env)) + 2;
-      if (batch.length && bytes + size > PULL_BUDGET_BYTES) break;
+      if (batch.length && bytes + size > pullBudgetBytes) break;
       batch.push(env); bytes += size;
       if (failedBefore) break;
     }
@@ -1216,11 +1562,12 @@ export class Bus {
   }
 
   private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail", quota = false): void {
+    const maxAttempts = this.opts.maxAttempts?.() ?? MAX_ATTEMPTS;
     if (!this.journal) this.deliveryFailed(id);
     // A quota refusal ran no work. The budget pause fences retries until reset; it is not a poison attempt.
     const quotaPaused = quota && this.paused.has(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
-    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
+    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= maxAttempts)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);
     }
     const keep = envs.filter((env) => {
@@ -1232,7 +1579,7 @@ export class Bus {
       if (quotaPaused) return true;
       const key = `${id}:${env.id}`;
       const n = (this.attempts.get(key) ?? 0) + 1;
-      if (n < MAX_ATTEMPTS) return this.attempts.set(key, n);
+      if (n < maxAttempts) return this.attempts.set(key, n);
       this.attempts.delete(key);
       this.emit({ t: "undeliverable", env, peer: id, reason: this.lastFailure.get(id) });
       return false;
@@ -1245,6 +1592,10 @@ export class Bus {
 
   private emit(e: BusEvent): void {
     if (this.flushingHub) { this.deferredEvents.push(e); return; }
+    if ("env" in e && (remoteId(e.env.from) || e.env.to?.some(remoteId) || ("peer" in e && remoteId(e.peer)))) {
+      const { refs: _, ...env } = e.env;
+      e = { ...e, env: { ...env, body: "[remote room message withheld]", ...(env.to ? { to: env.to.filter(id => /^[a-z][a-z0-9-]{0,31}$/.test(id) || !!parseRemotePeerId(id)) } : {}) }, ...("reason" in e ? { reason: "remote room delivery" } : {}) };
+    }
     for (const tap of this.taps) tap(e);
   }
 }