@axiom-lattice/gateway 4.7.0 → 4.8.0

package/dist/embed/embed-page.js

@@ -1,4 +1,4 @@
-import{b as f}from"./embed-page-chunk-OHDEKFTU.js";import"./embed-page-chunk-XIXSRYJY.js";import"./embed-page-chunk-HEMNMC4X.js";import{a as b}from"./embed-page-chunk-MB65DZAX.js";import"./embed-page-chunk-VW3NF5NT.js";import"./embed-page-chunk-5JDQ456X.js";import"./embed-page-chunk-Z7USDLHI.js";import{a as g}from"./embed-page-chunk-O4QK5LWZ.js";import"./embed-page-chunk-4BKXE5ON.js";import"./embed-page-chunk-IX4WLWCY.js";import"./embed-page-chunk-EUOOO2LS.js";import{b as U,e as s}from"./embed-page-chunk-6Y3UYJ6Z.js";var h=U(d=>{"use strict";var E=g();d.createRoot=E.createRoot,d.hydrateRoot=E.hydrateRoot;var ee});var T=s(h()),k=s(g());var y="axiom-web-app-embed";var x=["axiom:hello","axiom:identity","axiom:send","axiom:config"];function w(e,t){return{source:y,version:1,type:e,payload:t}}var N=6,z=40,B=500;function H(e){if(typeof e!="object"||e===null||Array.isArray(e))return!1;let t=e,n=Object.keys(t);return n.length!==2||!n.includes("label")||!n.includes("text")?!1:typeof t.label=="string"&&t.label.length>=1&&t.label.length<=z&&typeof t.text=="string"&&t.text.length>=1&&t.text.length<=B}function Q(e){if(!Array.isArray(e))return[];let t=[];for(let n of e){if(t.length>=N)break;H(n)&&t.push({label:n.label,text:n.text})}return t}function _(e){if(typeof e!="object"||e===null)return null;let t=e,n={};if(typeof t.welcome=="string"&&t.welcome.length>0&&(n.welcome=t.welcome),Array.isArray(t.quicks)){let r=Q(t.quicks);(r.length>0||t.quicks.length===0)&&(n.quicks=r)}return n.welcome===void 0&&n.quicks===void 0?null:n}function R(e,t){if(typeof e!="object"||e===null)return null;let n=e;return n.source!==y||n.version!==1||typeof n.type!="string"||!t.includes(n.type)?null:{type:n.type,payload:n.payload}}var p=s(b()),P=/^[A-Za-z0-9._:@-]{1,128}$/,q="Open this chat from the host page embed to start chatting.",v="axiom-embed-root",C="axiom-embed-style",A=32768,G=`
+import{b as f}from"./embed-page-chunk-O72XBKQH.js";import"./embed-page-chunk-QMVIL4BJ.js";import"./embed-page-chunk-YPNSOZYW.js";import{a as b}from"./embed-page-chunk-MB65DZAX.js";import"./embed-page-chunk-VW3NF5NT.js";import"./embed-page-chunk-5JDQ456X.js";import"./embed-page-chunk-Z7USDLHI.js";import{a as g}from"./embed-page-chunk-O4QK5LWZ.js";import"./embed-page-chunk-4BKXE5ON.js";import"./embed-page-chunk-IX4WLWCY.js";import"./embed-page-chunk-EUOOO2LS.js";import{b as U,e as s}from"./embed-page-chunk-6Y3UYJ6Z.js";var h=U(d=>{"use strict";var E=g();d.createRoot=E.createRoot,d.hydrateRoot=E.hydrateRoot;var ee});var T=s(h()),k=s(g());var y="axiom-web-app-embed";var x=["axiom:hello","axiom:identity","axiom:send","axiom:config"];function w(e,t){return{source:y,version:1,type:e,payload:t}}var N=6,z=40,B=500;function H(e){if(typeof e!="object"||e===null||Array.isArray(e))return!1;let t=e,n=Object.keys(t);return n.length!==2||!n.includes("label")||!n.includes("text")?!1:typeof t.label=="string"&&t.label.length>=1&&t.label.length<=z&&typeof t.text=="string"&&t.text.length>=1&&t.text.length<=B}function Q(e){if(!Array.isArray(e))return[];let t=[];for(let n of e){if(t.length>=N)break;H(n)&&t.push({label:n.label,text:n.text})}return t}function _(e){if(typeof e!="object"||e===null)return null;let t=e,n={};if(typeof t.welcome=="string"&&t.welcome.length>0&&(n.welcome=t.welcome),Array.isArray(t.quicks)){let r=Q(t.quicks);(r.length>0||t.quicks.length===0)&&(n.quicks=r)}return n.welcome===void 0&&n.quicks===void 0?null:n}function R(e,t){if(typeof e!="object"||e===null)return null;let n=e;return n.source!==y||n.version!==1||typeof n.type!="string"||!t.includes(n.type)?null:{type:n.type,payload:n.payload}}var p=s(b()),P=/^[A-Za-z0-9._:@-]{1,128}$/,q="Open this chat from the host page embed to start chatting.",v="axiom-embed-root",C="axiom-embed-style",A=32768,G=`
 html, body, #${v} { height: 100%; margin: 0; }
 .axiom-embed-fill { height: 100% !important; min-height: 0 !important; }
 .axiom-embed-card { display: flex; align-items: center; justify-content: center; height: 100%; margin: 0; font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; font-size: 14px; color: #64748b; padding: 24px; box-sizing: border-box; text-align: center; }

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, OutboxStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent, TaskRunRegistry } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
 
@@ -177,6 +177,7 @@ interface ProjectRoomEventBrokerOptions {
     maxGlobalEvents?: number;
     maxGlobalBytes?: number;
     initialSequence?: number;
+    sourceKeyLimit?: number;
     log?: {
         warn(message: string, context: Record<string, unknown>): void;
     };
@@ -195,22 +196,53 @@ declare class ProjectRoomEventBroker {
     private readonly maxRooms;
     private readonly maxGlobalEvents;
     private readonly maxGlobalBytes;
+    private readonly sourceKeyLimit;
     private readonly log;
     private readonly rooms;
     private readonly sequenceScopes;
+    private readonly seenSourceKeys;
     private sequence;
     private eventCount;
     private byteCount;
     private subscriberCount;
     private usageClock;
     private closed;
+    private broadcast;
     constructor(options?: ProjectRoomEventBrokerOptions);
     /** Number of currently registered subscriptions across all rooms. */
     get activeSubscriberCount(): number;
     /** Exact UTF-8 byte count of all retained serialized scoped events. */
     get retainedBytes(): number;
-    /** Atomically stores an immutable event before queueing detached listener callbacks. */
-    publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft): ProjectRoomScopedBusinessEvent;
+    /**
+     * Installs (or clears) a hook invoked after a locally published event is stored
+     * and queued to local subscribers. Used to mirror events to other replicas via
+     * a shared transport. Best-effort: a throwing hook never affects `publish`.
+     */
+    setBroadcastHook(hook: ((scope: ProjectRoomEventScope, serializedEvent: string, sourceKey?: string) => void) | undefined): void;
+    /**
+     * Atomically stores an immutable event before queueing detached listener callbacks.
+     *
+     * @param sourceKey Optional caller-owned fact key; when present it is retained
+     * for bounded cross-replica duplicate suppression so a later foreign copy of the
+     * same fact (or a local publish) is dropped by {@link ingestForeignEvent}.
+     */
+    publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft, sourceKey?: string): ProjectRoomScopedBusinessEvent;
+    /**
+     * Delivers one event published by ANOTHER replica to this process's local
+     * subscribers for its room, without adding it to the local replay ring or
+     * consuming a local sequence (its id carries the origin replica's epoch).
+     *
+     * @param serializedEvent A serialized scoped business event produced by a peer.
+     * @param sourceKey Optional caller-owned fact key shared by every replica's copy
+     * of the same committed fact. When it was already seen (locally published or
+     * ingested from a peer) the event is dropped to avoid N× duplicate delivery.
+     * @returns True when it was queued to at least one local subscription.
+     * @remarks Source-key deduplication is process-local and bounded, so it caps
+     * duplicate fan-out within the retention window without replacing REST, which
+     * remains the authority. A malformed payload or a room with no local
+     * subscribers is ignored.
+     */
+    ingestForeignEvent(serializedEvent: string, sourceKey?: string): boolean;
     /** Atomically resolves replay and registers a distinct subscription for live events. */
     subscribe(scope: ProjectRoomEventScope, afterEventId: string | undefined, listener: Listener): ProjectRoomEventSubscription;
     /** Clears retained state, marks every subscription closed, and permanently closes the broker. */
@@ -232,6 +264,7 @@ declare class ProjectRoomEventBroker {
     private assertOpen;
     private createRoom;
     private touch;
+    private rememberSourceKey;
 }
 
 /**
@@ -307,11 +340,18 @@ interface ProjectTaskMachineScope {
 /**
  * Serializes Project task machine operations by tenant, Assistant, and Project.
  *
- * This mutex is process-local: callers must share one instance, and deployments
- * with multiple Gateway processes need an external lease for cross-process
- * exclusion. Acquisition is FIFO and intentionally non-reentrant; an operation
- * must not await another acquisition of its own machine key. When an operation
- * also needs the Project mutation mutex, it must acquire this machine mutex first.
+ * The local FIFO lock is process-local: callers must share one instance.
+ * Acquisition is FIFO and intentionally non-reentrant; an operation must not
+ * await another acquisition of its own machine key. When an operation also needs
+ * the Project mutation mutex, it must acquire this machine mutex first.
+ *
+ * A coordination lease store may be installed process-wide
+ * ({@link configureCoordinationLeaseStore}). When present, each critical section
+ * additionally holds a bounded distributed lease
+ * (`project-task-machine:<tenant>:<assistant>:<project>`) so operations on the
+ * same machine serialize across replicas, not just within this process. The local
+ * FIFO lock is always retained; the lease only adds cross-replica exclusion. When
+ * no store is configured (single process, tests), behavior is unchanged.
  */
 declare class ProjectTaskExecutionMutex {
     private readonly queues;
@@ -397,6 +437,11 @@ type ProjectTaskRunOutcome = {
     task: TaskItem;
     thread: Thread;
     messageId: string;
+} | {
+    kind: "deferred";
+    task: TaskItem;
+    thread: Thread;
+    messageId: string;
 };
 /** Stable classification of the queue fact used to recover an in-progress Project Task. */
 type ProjectTaskRecoveryClassification = {
@@ -764,6 +809,37 @@ declare class AgentTaskConsumer {
     trigger_agent_task(taskRequest: AgentTaskRequest): void;
 }
 
+/** Cross-replica liveness probe: resolves true when a peer still owns the task's run. */
+type TaskLivenessProbe = (task: TaskItem) => Promise<boolean>;
+/**
+ * Builds a cross-replica task-liveness probe from the registered `"lease"` store.
+ *
+ * @returns A {@link TaskLivenessProbe}, or `undefined` only when no `lease`
+ *   store is registered (a test-only path); with the default in-memory lease
+ *   store a probe is always returned (single-process safe because the in-memory
+ *   store has no peer).
+ * @remarks
+ * A task is considered live when EITHER lease is currently held:
+ * - `task-run:<taskId>` — the immediate executor's run-lifetime lease, or
+ * - `thread-run:<tenantId>:<ownerId>:<thread_id>` — the queue processor
+ *   executing the task's run thread (dispatched workers run through this).
+ *
+ * Fail-safe: any lease-store error resolves `true`, so an unknown liveness
+ * state never causes a live run to be converged as an orphan.
+ *
+ * The probe is advisory: there is a benign race between the probe read and
+ * `failTask` (a run could acquire its lease in that window), and no
+ * fencing/heartbeat-expiry detection is provided yet — consistent with the
+ * framework's current no-lease posture.
+ *
+ * @example
+ * ```ts
+ * const probe = createTaskRunLiveness();
+ * if (probe && await probe(task)) return; // a peer replica owns it
+ * ```
+ */
+declare function createTaskRunLiveness(): TaskLivenessProbe | undefined;
+
 /** Minimal caller-graph client surface used by recovery. */
 interface RecoveryCallerClient {
     getState(config: unknown): Promise<unknown>;
@@ -789,6 +865,12 @@ interface TopCallerRecoveryDeps {
     registry?: {
         isLive(taskId: string): boolean;
     };
+    /**
+     * Optional cross-replica liveness probe consulted by Guard B, so a run held
+     * by a peer replica is not converged/backfilled. Mutually additive with the
+     * process-local `registry`.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Resume the continuation (tests can call client.invoke(null, config)). */
     resume(client: RecoveryCallerClient, config: unknown, agent?: unknown): Promise<void>;
 }
@@ -808,6 +890,12 @@ interface RecoverTaskDeps {
      * immediate (frozen) caller. Defaults to `[converged]` when omitted.
      */
     orphans?: TaskItem[];
+    /**
+     * Optional cross-replica liveness probe consulted by Guard B, so a run held
+     * by a peer replica is not converged. Forwarded to
+     * {@link reconcileStaleTaskRuns} and to {@link recoverTopCaller}.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Resolve a caller's agent client + config from the resolved top caller. */
     callerFor: TopCallerRecoveryDeps["callerFor"];
     /** Resume the continuation (tests can call client.invoke(null, config)). */
@@ -862,9 +950,10 @@ declare function recoverTopCaller(task: TaskItem, top: {
  * being mistaken for a direct child of its frozen immediate caller.
  *
  * This is an **offline/maintenance** entry point (the `task:recover` CLI): run
- * it when the Gateway is stopped, or from within the Gateway process. The
- * `live` guard reads the process-local {@link taskRunRegistry}, so it is
- * meaningful only in-process and cannot detect a run held by another process.
+ * it when the Gateway is stopped, or from within the Gateway process. Guard B
+ * reads the process-local {@link taskRunRegistry}; when the optional
+ * `isTaskLive` cross-replica probe is supplied (the gateway's lease-backed
+ * probe), it also detects a run held by a peer replica.
  *
  * The convergence actor is `system:on-demand-recovery` (distinct from the
  * startup sweep's `system:orphan-recovery`), so on-demand convergences are
@@ -891,6 +980,7 @@ declare function runOrphanRecovery(deps: {
     }>;
     callerFor: TopCallerRecoveryDeps["callerFor"];
     resume: TopCallerRecoveryDeps["resume"];
+    isTaskLive?: TaskLivenessProbe;
     log: {
         info(msg: string, ctx: Record<string, unknown>): void;
         warn(msg: string, ctx: Record<string, unknown>): void;
@@ -925,6 +1015,11 @@ interface OrphanRecoveryRuntimeDeps {
     callerFor: TopCallerRecoveryDeps["callerFor"];
     /** Resume the continuation (tests can call client.invoke(null, config)). */
     resume: TopCallerRecoveryDeps["resume"];
+    /**
+     * Cross-replica liveness probe; defaults to the shared cross-replica probe
+     * ({@link createTaskRunLiveness()}); inherit it unless a test injects one.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Structured logger. */
     log: {
         info(msg: string, ctx: Record<string, unknown>): void;
@@ -942,9 +1037,11 @@ interface OrphanRecoveryRuntime {
      * On-demand recovery of exactly one task within one tenant.
      *
      * @remarks Offline/maintenance: run when the Gateway is stopped, or from the
-     * Gateway process. The `live` guard reads the process-local task registry and
-     * cannot see a run held by another process. Governed Project tasks are refused
-     * (`skipped:project_task`) so this never bypasses their managed runtime.
+     * Gateway process. The `live` guard reads the process-local task registry and,
+     * when a lease store is registered, also consults the cross-replica liveness
+     * probe so a run held by another process is not converged. Governed Project
+     * tasks are refused (`skipped:project_task`) so this never bypasses their
+     * managed runtime.
      */
     recoverTask(input: {
         tenantId: string;
@@ -962,8 +1059,12 @@ interface OrphanRecoveryRuntime {
  * observer-based reconciliation) and from `recoverTask()`
  * (`skipped:project_task`), so the on-demand entry can never bypass the managed
  * Project runtime. `recoverTask()` delegates to {@link recoverSingleTask} with
- * the shared lifecycle and the process-local live-run registry, so it never
- * converges a task a live run still holds — in-process only.
+ * the shared lifecycle, the process-local live-run registry, and the
+ * cross-replica liveness probe (built from the shared `"lease"` store unless
+ * `isTaskLive` is supplied), so it does not converge a task a live run still
+ * holds — in this process or a peer replica. The liveness probe is advisory: a
+ * benign race exists between the probe read and `failTask` (no
+ * fencing/heartbeat support yet).
  *
  * @example
  * ```ts
@@ -987,6 +1088,34 @@ declare function createOrphanRecoveryRuntime(deps: OrphanRecoveryRuntimeDeps): O
  */
 declare function createRecoveryCallerDeps(): Pick<TopCallerRecoveryDeps, "callerFor" | "resume">;
 
+/** Outbox topic carrying cross-replica Project Room realtime events. */
+declare const ROOM_EVENT_TOPIC = "room-event";
+/**
+ * Mirrors one locally published Project Room event to the shared outbox.
+ *
+ * @param outbox Shared append-only outbox log.
+ * @param owner Origin replica id, so its own poller skips the row.
+ * @param scope Room scope the event was published for.
+ * @param serialized Canonical serialized scoped event.
+ * @param sourceKey Optional caller-owned fact key carried to peer replicas for
+ * bounded duplicate suppression at their broker.
+ * @returns A promise that settles once the append attempt completes.
+ * @remarks Best-effort: an append failure is swallowed because REST remains the
+ * authority and clients refetch on reconnect.
+ */
+declare function publishRoomEvent(outbox: OutboxStore, owner: string, scope: ProjectRoomEventScope, serialized: string, sourceKey?: string): Promise<void>;
+/**
+ * Delivers one foreign outbox payload to the local broker's subscribers.
+ *
+ * @param payload Raw outbox payload; expected `{ serialized: string, sourceKey?: string }`.
+ * @param broker The process-local Project Room event broker.
+ * @returns True when the broker queued the event to at least one local subscription.
+ * @remarks Malformed payloads are ignored. The broker drops events whose
+ * source key it already saw; the poller additionally skips rows authored by this
+ * replica.
+ */
+declare function ingestRoomEvent(payload: unknown, broker: ProjectRoomEventBroker): boolean;
+
 /**
  * Logger configuration for gateway
  */
@@ -1017,4 +1146,4 @@ declare const LatticeGateway: {
     AgentTaskConsumer: typeof AgentTaskConsumer;
 };
 
-export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, type RecoverTaskDeps, type RecoverTaskResult, createOrphanRecoveryRuntime, createRecoveryCallerDeps, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };
+export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, type RecoverTaskDeps, type RecoverTaskResult, type TaskLivenessProbe, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createTaskRunLiveness, ingestRoomEvent, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, OutboxStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent, TaskRunRegistry } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
 
@@ -177,6 +177,7 @@ interface ProjectRoomEventBrokerOptions {
     maxGlobalEvents?: number;
     maxGlobalBytes?: number;
     initialSequence?: number;
+    sourceKeyLimit?: number;
     log?: {
         warn(message: string, context: Record<string, unknown>): void;
     };
@@ -195,22 +196,53 @@ declare class ProjectRoomEventBroker {
     private readonly maxRooms;
     private readonly maxGlobalEvents;
     private readonly maxGlobalBytes;
+    private readonly sourceKeyLimit;
     private readonly log;
     private readonly rooms;
     private readonly sequenceScopes;
+    private readonly seenSourceKeys;
     private sequence;
     private eventCount;
     private byteCount;
     private subscriberCount;
     private usageClock;
     private closed;
+    private broadcast;
     constructor(options?: ProjectRoomEventBrokerOptions);
     /** Number of currently registered subscriptions across all rooms. */
     get activeSubscriberCount(): number;
     /** Exact UTF-8 byte count of all retained serialized scoped events. */
     get retainedBytes(): number;
-    /** Atomically stores an immutable event before queueing detached listener callbacks. */
-    publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft): ProjectRoomScopedBusinessEvent;
+    /**
+     * Installs (or clears) a hook invoked after a locally published event is stored
+     * and queued to local subscribers. Used to mirror events to other replicas via
+     * a shared transport. Best-effort: a throwing hook never affects `publish`.
+     */
+    setBroadcastHook(hook: ((scope: ProjectRoomEventScope, serializedEvent: string, sourceKey?: string) => void) | undefined): void;
+    /**
+     * Atomically stores an immutable event before queueing detached listener callbacks.
+     *
+     * @param sourceKey Optional caller-owned fact key; when present it is retained
+     * for bounded cross-replica duplicate suppression so a later foreign copy of the
+     * same fact (or a local publish) is dropped by {@link ingestForeignEvent}.
+     */
+    publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft, sourceKey?: string): ProjectRoomScopedBusinessEvent;
+    /**
+     * Delivers one event published by ANOTHER replica to this process's local
+     * subscribers for its room, without adding it to the local replay ring or
+     * consuming a local sequence (its id carries the origin replica's epoch).
+     *
+     * @param serializedEvent A serialized scoped business event produced by a peer.
+     * @param sourceKey Optional caller-owned fact key shared by every replica's copy
+     * of the same committed fact. When it was already seen (locally published or
+     * ingested from a peer) the event is dropped to avoid N× duplicate delivery.
+     * @returns True when it was queued to at least one local subscription.
+     * @remarks Source-key deduplication is process-local and bounded, so it caps
+     * duplicate fan-out within the retention window without replacing REST, which
+     * remains the authority. A malformed payload or a room with no local
+     * subscribers is ignored.
+     */
+    ingestForeignEvent(serializedEvent: string, sourceKey?: string): boolean;
     /** Atomically resolves replay and registers a distinct subscription for live events. */
     subscribe(scope: ProjectRoomEventScope, afterEventId: string | undefined, listener: Listener): ProjectRoomEventSubscription;
     /** Clears retained state, marks every subscription closed, and permanently closes the broker. */
@@ -232,6 +264,7 @@ declare class ProjectRoomEventBroker {
     private assertOpen;
     private createRoom;
     private touch;
+    private rememberSourceKey;
 }
 
 /**
@@ -307,11 +340,18 @@ interface ProjectTaskMachineScope {
 /**
  * Serializes Project task machine operations by tenant, Assistant, and Project.
  *
- * This mutex is process-local: callers must share one instance, and deployments
- * with multiple Gateway processes need an external lease for cross-process
- * exclusion. Acquisition is FIFO and intentionally non-reentrant; an operation
- * must not await another acquisition of its own machine key. When an operation
- * also needs the Project mutation mutex, it must acquire this machine mutex first.
+ * The local FIFO lock is process-local: callers must share one instance.
+ * Acquisition is FIFO and intentionally non-reentrant; an operation must not
+ * await another acquisition of its own machine key. When an operation also needs
+ * the Project mutation mutex, it must acquire this machine mutex first.
+ *
+ * A coordination lease store may be installed process-wide
+ * ({@link configureCoordinationLeaseStore}). When present, each critical section
+ * additionally holds a bounded distributed lease
+ * (`project-task-machine:<tenant>:<assistant>:<project>`) so operations on the
+ * same machine serialize across replicas, not just within this process. The local
+ * FIFO lock is always retained; the lease only adds cross-replica exclusion. When
+ * no store is configured (single process, tests), behavior is unchanged.
  */
 declare class ProjectTaskExecutionMutex {
     private readonly queues;
@@ -397,6 +437,11 @@ type ProjectTaskRunOutcome = {
     task: TaskItem;
     thread: Thread;
     messageId: string;
+} | {
+    kind: "deferred";
+    task: TaskItem;
+    thread: Thread;
+    messageId: string;
 };
 /** Stable classification of the queue fact used to recover an in-progress Project Task. */
 type ProjectTaskRecoveryClassification = {
@@ -764,6 +809,37 @@ declare class AgentTaskConsumer {
     trigger_agent_task(taskRequest: AgentTaskRequest): void;
 }
 
+/** Cross-replica liveness probe: resolves true when a peer still owns the task's run. */
+type TaskLivenessProbe = (task: TaskItem) => Promise<boolean>;
+/**
+ * Builds a cross-replica task-liveness probe from the registered `"lease"` store.
+ *
+ * @returns A {@link TaskLivenessProbe}, or `undefined` only when no `lease`
+ *   store is registered (a test-only path); with the default in-memory lease
+ *   store a probe is always returned (single-process safe because the in-memory
+ *   store has no peer).
+ * @remarks
+ * A task is considered live when EITHER lease is currently held:
+ * - `task-run:<taskId>` — the immediate executor's run-lifetime lease, or
+ * - `thread-run:<tenantId>:<ownerId>:<thread_id>` — the queue processor
+ *   executing the task's run thread (dispatched workers run through this).
+ *
+ * Fail-safe: any lease-store error resolves `true`, so an unknown liveness
+ * state never causes a live run to be converged as an orphan.
+ *
+ * The probe is advisory: there is a benign race between the probe read and
+ * `failTask` (a run could acquire its lease in that window), and no
+ * fencing/heartbeat-expiry detection is provided yet — consistent with the
+ * framework's current no-lease posture.
+ *
+ * @example
+ * ```ts
+ * const probe = createTaskRunLiveness();
+ * if (probe && await probe(task)) return; // a peer replica owns it
+ * ```
+ */
+declare function createTaskRunLiveness(): TaskLivenessProbe | undefined;
+
 /** Minimal caller-graph client surface used by recovery. */
 interface RecoveryCallerClient {
     getState(config: unknown): Promise<unknown>;
@@ -789,6 +865,12 @@ interface TopCallerRecoveryDeps {
     registry?: {
         isLive(taskId: string): boolean;
     };
+    /**
+     * Optional cross-replica liveness probe consulted by Guard B, so a run held
+     * by a peer replica is not converged/backfilled. Mutually additive with the
+     * process-local `registry`.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Resume the continuation (tests can call client.invoke(null, config)). */
     resume(client: RecoveryCallerClient, config: unknown, agent?: unknown): Promise<void>;
 }
@@ -808,6 +890,12 @@ interface RecoverTaskDeps {
      * immediate (frozen) caller. Defaults to `[converged]` when omitted.
      */
     orphans?: TaskItem[];
+    /**
+     * Optional cross-replica liveness probe consulted by Guard B, so a run held
+     * by a peer replica is not converged. Forwarded to
+     * {@link reconcileStaleTaskRuns} and to {@link recoverTopCaller}.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Resolve a caller's agent client + config from the resolved top caller. */
     callerFor: TopCallerRecoveryDeps["callerFor"];
     /** Resume the continuation (tests can call client.invoke(null, config)). */
@@ -862,9 +950,10 @@ declare function recoverTopCaller(task: TaskItem, top: {
  * being mistaken for a direct child of its frozen immediate caller.
  *
  * This is an **offline/maintenance** entry point (the `task:recover` CLI): run
- * it when the Gateway is stopped, or from within the Gateway process. The
- * `live` guard reads the process-local {@link taskRunRegistry}, so it is
- * meaningful only in-process and cannot detect a run held by another process.
+ * it when the Gateway is stopped, or from within the Gateway process. Guard B
+ * reads the process-local {@link taskRunRegistry}; when the optional
+ * `isTaskLive` cross-replica probe is supplied (the gateway's lease-backed
+ * probe), it also detects a run held by a peer replica.
  *
  * The convergence actor is `system:on-demand-recovery` (distinct from the
  * startup sweep's `system:orphan-recovery`), so on-demand convergences are
@@ -891,6 +980,7 @@ declare function runOrphanRecovery(deps: {
     }>;
     callerFor: TopCallerRecoveryDeps["callerFor"];
     resume: TopCallerRecoveryDeps["resume"];
+    isTaskLive?: TaskLivenessProbe;
     log: {
         info(msg: string, ctx: Record<string, unknown>): void;
         warn(msg: string, ctx: Record<string, unknown>): void;
@@ -925,6 +1015,11 @@ interface OrphanRecoveryRuntimeDeps {
     callerFor: TopCallerRecoveryDeps["callerFor"];
     /** Resume the continuation (tests can call client.invoke(null, config)). */
     resume: TopCallerRecoveryDeps["resume"];
+    /**
+     * Cross-replica liveness probe; defaults to the shared cross-replica probe
+     * ({@link createTaskRunLiveness()}); inherit it unless a test injects one.
+     */
+    isTaskLive?: TaskLivenessProbe;
     /** Structured logger. */
     log: {
         info(msg: string, ctx: Record<string, unknown>): void;
@@ -942,9 +1037,11 @@ interface OrphanRecoveryRuntime {
      * On-demand recovery of exactly one task within one tenant.
      *
      * @remarks Offline/maintenance: run when the Gateway is stopped, or from the
-     * Gateway process. The `live` guard reads the process-local task registry and
-     * cannot see a run held by another process. Governed Project tasks are refused
-     * (`skipped:project_task`) so this never bypasses their managed runtime.
+     * Gateway process. The `live` guard reads the process-local task registry and,
+     * when a lease store is registered, also consults the cross-replica liveness
+     * probe so a run held by another process is not converged. Governed Project
+     * tasks are refused (`skipped:project_task`) so this never bypasses their
+     * managed runtime.
      */
     recoverTask(input: {
         tenantId: string;
@@ -962,8 +1059,12 @@ interface OrphanRecoveryRuntime {
  * observer-based reconciliation) and from `recoverTask()`
  * (`skipped:project_task`), so the on-demand entry can never bypass the managed
  * Project runtime. `recoverTask()` delegates to {@link recoverSingleTask} with
- * the shared lifecycle and the process-local live-run registry, so it never
- * converges a task a live run still holds — in-process only.
+ * the shared lifecycle, the process-local live-run registry, and the
+ * cross-replica liveness probe (built from the shared `"lease"` store unless
+ * `isTaskLive` is supplied), so it does not converge a task a live run still
+ * holds — in this process or a peer replica. The liveness probe is advisory: a
+ * benign race exists between the probe read and `failTask` (no
+ * fencing/heartbeat support yet).
  *
  * @example
  * ```ts
@@ -987,6 +1088,34 @@ declare function createOrphanRecoveryRuntime(deps: OrphanRecoveryRuntimeDeps): O
  */
 declare function createRecoveryCallerDeps(): Pick<TopCallerRecoveryDeps, "callerFor" | "resume">;
 
+/** Outbox topic carrying cross-replica Project Room realtime events. */
+declare const ROOM_EVENT_TOPIC = "room-event";
+/**
+ * Mirrors one locally published Project Room event to the shared outbox.
+ *
+ * @param outbox Shared append-only outbox log.
+ * @param owner Origin replica id, so its own poller skips the row.
+ * @param scope Room scope the event was published for.
+ * @param serialized Canonical serialized scoped event.
+ * @param sourceKey Optional caller-owned fact key carried to peer replicas for
+ * bounded duplicate suppression at their broker.
+ * @returns A promise that settles once the append attempt completes.
+ * @remarks Best-effort: an append failure is swallowed because REST remains the
+ * authority and clients refetch on reconnect.
+ */
+declare function publishRoomEvent(outbox: OutboxStore, owner: string, scope: ProjectRoomEventScope, serialized: string, sourceKey?: string): Promise<void>;
+/**
+ * Delivers one foreign outbox payload to the local broker's subscribers.
+ *
+ * @param payload Raw outbox payload; expected `{ serialized: string, sourceKey?: string }`.
+ * @param broker The process-local Project Room event broker.
+ * @returns True when the broker queued the event to at least one local subscription.
+ * @remarks Malformed payloads are ignored. The broker drops events whose
+ * source key it already saw; the poller additionally skips rows authored by this
+ * replica.
+ */
+declare function ingestRoomEvent(payload: unknown, broker: ProjectRoomEventBroker): boolean;
+
 /**
  * Logger configuration for gateway
  */
@@ -1017,4 +1146,4 @@ declare const LatticeGateway: {
     AgentTaskConsumer: typeof AgentTaskConsumer;
 };
 
-export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, type RecoverTaskDeps, type RecoverTaskResult, createOrphanRecoveryRuntime, createRecoveryCallerDeps, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };
+export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, type RecoverTaskDeps, type RecoverTaskResult, type TaskLivenessProbe, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createTaskRunLiveness, ingestRoomEvent, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };