@axiom-lattice/gateway 6.0.1 → 7.0.0

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
-import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent, TaskLivenessProbe, TaskRunRegistry } from '@axiom-lattice/core';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, AgentRunJsonObject, TrustedRunContext, AgentRunRecord, TaskLifecycleService, IAgentRunLedger, AppendLog, TaskLivenessProbe, TaskRunRegistry, AgentLifecycleTapEvent, AgentLifecycleEventName, AgentThreadInterface, AgentCheckpointTip, ExecuteRunInput, ExecuteRunResult, AgentRunSource, AgentRunStatus, ThreadRunLeaseHandle } from '@axiom-lattice/core';
 export { TaskLivenessProbe } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
-import { RouteGenericInterface, FastifyRequest, FastifyReply } from 'fastify';
+import { RouteGenericInterface, FastifyRequest, FastifyReply, FastifyInstance } from 'fastify';
 
 /** Public publisher surface for committed Project Room business facts. */
 interface ProjectRoomRealtimePublisher {
@@ -93,6 +93,15 @@ interface MessageRouterConfig {
     adapterRegistry: ChannelAdapterRegistry;
     installationStore: ChannelInstallationStore;
     trustedDispatcher?: TrustedAgentMessageDispatcher;
+    /**
+     * Route non-Room public ingress through a durable pending run plus
+     * {@link ChannelReplyJob} instead of executing in-process.
+     *
+     * @remarks Default `false` so existing deployments/tests keep the legacy
+     * `agent.addMessage` + `reply:ready` path. Room and trusted dispatch are
+     * never affected.
+     */
+    durableChannelRuns?: boolean;
 }
 /** Host-trusted options for internal orchestration only. Public routes must not provide these. */
 interface InternalMessageDispatchOptions {
@@ -123,6 +132,7 @@ declare class MessageRouter {
     private adapterRegistry;
     private installationStore;
     private trustedDispatcher?;
+    private durableChannelRuns;
     private replySubscriptions;
     /** Recent answer-by-message resumes per presence thread (first answer wins). */
     private recentResumes;
@@ -157,10 +167,31 @@ declare class MessageRouter {
      */
     dispatch(message: InboundMessage, options?: InternalMessageDispatchOptions): Promise<DispatchResult>;
     private dispatchInternal;
+    /**
+     * Creates the durable pending run and its reply job for non-Room ingress.
+     *
+     * @returns The serialized queued result for {@link DispatchResult.result}.
+     */
+    private dispatchDurableChannelRun;
     private runMiddlewares;
-    /** 流式中途刷新的节流间隔与上限（微信单会话 30 条/分钟，留余量）。 */
+    /**
+     * 流式中途刷新的节流间隔与上限。
+     *
+     * 企业微信单会话限制 30 条/分钟（含占位、收尾和卡片）。2500ms 约 24 次
+     * 刷新/分钟，再加最多 3 条生命周期消息仍留有余量。
+     */
     private static readonly STREAM_CHUNK_INTERVAL_MS;
     private static readonly MAX_STREAM_CHUNKS;
+    /** 流式回复的硬超时：企微要求 10 分钟内 `finish=true`，留 2 分钟余量。 */
+    private static readonly STREAM_TIMEOUT_MS;
+    /**
+     * `MESSAGE_COMPLETED` 后等待 `reply:ready` 的宽限。
+     *
+     * 正常完成通常由 `reply:ready` 用权威全文收尾；但最终 AI 消息为空时
+     * （例如模型只调用了 `wecom_card`、没有产出文字）不会触发 `reply:ready`，
+     * 这里兜底自行收尾，避免流挂住、卡片丢失。
+     */
+    private static readonly COMPLETION_GRACE_MS;
     /**
      * 消费 agent 的逐块输出，把**中途**内容推给支持流式的渠道适配器。
      *
@@ -211,6 +242,23 @@ interface ModelProviderServiceDeps {
         has(tenantId: string, modelKey: string): boolean;
         remove(tenantId: string, modelKey: string): boolean;
         listRegistered(tenantId: string): RegisteredModel[];
+        /**
+         * Drop this replica's cached clients for one provider, plus the tenant's
+         * resolved default.
+         *
+         * The registry's positive entries have no TTL — once a key is resolved the
+         * store is never read again — so a changed `extra`, apiKey or baseURL is
+         * otherwise invisible until the process restarts. Evicting is enough:
+         * resolution re-materialises the row from the shared store, which is how a
+         * replica that never saw the change already works.
+         *
+         * Optional so existing constructions keep working, but a caller that omits
+         * it silently loses change propagation.
+         *
+         * @param providerId clears that `${providerId}/` prefix; omit to clear only
+         *   the tenant default.
+         */
+        evictProviderCache?(tenantId: string, providerId?: string): void;
         /**
          * Drop the registry's cached "this tenant has no default model" answer.
          *
@@ -315,14 +363,17 @@ declare class ModelProviderService {
      */
     setModels(userId: string | undefined, tenantId: string, id: string, selection: ModelSelection[]): Promise<ModelProviderPublicEntry>;
     /**
-     * Give a tenant's sole model the default flag.
+     * Give a tenant's sole **chat** model the default flag.
+     *
+     * A tenant with exactly one runnable chat model has an obvious default, and
+     * saying so is what keeps the invariant the rest of the feature leans on: a
+     * tenant either has no chat model at all — and falls back to the deployment's
+     * default — or has a default, which cannot be deleted. Without this a tenant
+     * could sit with one model and no default, and deleting that model would
+     * leave nothing behind.
      *
-     * A tenant with exactly one runnable model has an obvious default, and saying
-     * so is what keeps the invariant the rest of the feature leans on: a tenant
-     * either has no models at all — and falls back to the deployment's default —
-     * or has a default, which cannot be deleted. Without this a tenant could sit
-     * with one model and no default, and deleting that model would leave nothing
-     * behind.
+     * Chat only: a bare `"default"` key resolves to a chat client, so an
+     * embedding or ASR row must never be marked as one.
      *
      * Deliberately narrow: more than one model is the tenant's choice to make,
      * and a disabled model is not a candidate for "the model this tenant runs".
@@ -690,6 +741,16 @@ declare class ProjectTaskThreadService {
     private readonly deps;
     /** @param deps Thread persistence and unique-ID generation dependencies. */
     constructor(deps: ProjectTaskThreadServiceDependencies);
+    /**
+     * Reads the persisted Thread without creating or validating it.
+     *
+     * @param tenantId Tenant scope.
+     * @param threadId Thread identifier.
+     * @returns The stored Thread snapshot, or `undefined` when it is unreadable.
+     * @remarks Used by the run planner to rebuild trusted context from canonical
+     * rows; it never mutates Thread state.
+     */
+    getThreadById(tenantId: string, threadId: string): Promise<Thread | undefined>;
     /**
      * Ensures a canonical Task execution Thread for the requested ownership mode.
      *
@@ -701,60 +762,470 @@ declare class ProjectTaskThreadService {
     private assertThread;
 }
 
-/** Result of one Project Task Agent execution settlement. */
-type ProjectTaskRunOutcome = {
-    kind: "completed";
-    task: TaskItem;
-    thread: Thread;
-    messageId: string;
-} | {
-    kind: "cancelled";
+/** Execution mode of a Project Task run intent. */
+type ProjectTaskRunMode = "start" | "resume";
+
+/** HITL resume command carried into a Project Task run intent. */
+type ProjectTaskRunCommand = AgentRunJsonObject;
+/** Fields shared by both Project Task run intent variants. */
+interface ProjectTaskRunIntentBase {
+    source: "project_task";
+    taskId: string;
+    tenantId: string;
+    workspaceId: string;
+    projectId: string;
+    assistantId: string;
+    threadId: string;
+    config: {
+        taskId: string;
+        execution: {
+            taskId: string;
+        };
+    };
+    metadata: {
+        taskId: string;
+        projectId: string;
+        workspaceId: string;
+        actor: string;
+        mode: ProjectTaskRunMode;
+    };
+}
+/**
+ * Durable Project Task run intent produced from canonical rows.
+ *
+ * @remarks A run carries exactly one of `input` (normal start/resume) or
+ * `command` (HITL resume), matching `CreatePendingAgentRunInput`.
+ */
+type ProjectTaskRunIntent = (ProjectTaskRunIntentBase & {
+    input: {
+        id: string;
+        message: string;
+    };
+    command?: never;
+}) | (ProjectTaskRunIntentBase & {
+    command: ProjectTaskRunCommand;
+    input?: never;
+});
+/**
+ * Validated plan for one Project Task execution attempt.
+ *
+ * @remarks The planner never persists the trusted context: callers pass it to
+ * the run worker, while `run` is the durable queue intent.
+ */
+interface ProjectTaskRunPlan {
+    run: ProjectTaskRunIntent;
+    trustedContext: TrustedRunContext;
+}
+/** Collaborators required to validate Project Task runs. */
+interface ProjectTaskRunPlannerDependencies {
+    tasks: Pick<TaskStore, "getById">;
+    projects: Pick<ProjectStore, "getProjectById">;
+    rooms: Pick<ProjectRoomStore, "getMainRoom">;
+    bots: Pick<ProjectBotMembershipStore, "findByAssistant">;
+    threads: Pick<ThreadStore, "getThreadById">;
+    /** JIT-materializes a public-project task owner so it has a room anchor to post/reply. */
+    ensurePublicOwner?: (input: {
+        tenantId: string;
+        projectId: string;
+        assistantId: string;
+    }) => Promise<unknown>;
+    /** Run input id factory; defaults to `randomUUID`. */
+    idFactory?: () => string;
+}
+/** Input for planning one Project Task run. */
+interface PlanProjectTaskRunInput {
     task: TaskItem;
     thread: Thread;
-    messageId: string;
-} | {
-    kind: "failed";
+    mode: ProjectTaskRunMode;
+    actor?: string;
+    /** Optional HITL resume command passed through for Task 4 to attach. */
+    command?: ProjectTaskRunCommand;
+}
+/**
+ * Converts validated Project Task rows into a durable run intent and rebuilds
+ * trusted context from canonical rows when a worker executes the run.
+ *
+ * @remarks The planner performs no lifecycle or queue mutation and never trusts
+ * `run.config` for authority.
+ */
+declare class ProjectTaskRunPlanner {
+    private readonly deps;
+    private readonly targets;
+    /** @param deps Canonical Task, Project, room, roster, and Thread reads. */
+    constructor(deps: ProjectTaskRunPlannerDependencies);
+    /**
+     * Validates canonical Project Task rows and returns a run intent.
+     *
+     * @param input Task snapshot, canonical Thread, dispatch mode, actor, and optional command.
+     * @returns The run intent plus trusted context for tests/diagnostics.
+     * @throws {@link ProjectTaskRunPlanError} when scope, status, roster, Thread, or dependencies drift.
+     */
+    plan(input: PlanProjectTaskRunInput): Promise<ProjectTaskRunPlan>;
+    /**
+     * Rebuilds trusted Project Task context for a claimed run.
+     *
+     * @param run Durable run record claimed by the worker.
+     * @returns The trusted context wrapper, or `undefined` for non-ProjectTask sources.
+     * @throws {@link ProjectTaskRunPlanError} when the canonical scope has drifted.
+     * @remarks `run.config` is never read for authority.
+     */
+    resolveTrustedRunContext(run: AgentRunRecord): Promise<TrustedRunContext | undefined>;
+    private requireTask;
+    private assertStatus;
+}
+
+/**
+ * Admission modes with their exact allowed Task statuses.
+ *
+ * @remarks `plan_*` modes accept the pre- and post-transition status so a
+ * planner can run on either side of the lifecycle claim.
+ */
+type ProjectTaskAdmissionMode = "start" | "resume" | "restart" | "recovery" | "plan_start" | "plan_resume";
+/** Exact task load input; `expectedTask` requires the caller snapshot to still match. */
+interface RequireProjectTaskInput {
+    tenantId: string;
+    taskId: string;
+    expectedTask?: TaskItem;
+}
+/** Non-roster Project Task scope resolved before any public-owner materialization. */
+interface ProjectTaskTargetContext {
     task: TaskItem;
-    thread: Thread;
-    messageId: string;
-    error: string;
-    cause: "agent_failed" | "queue_rejected" | "settlement_timeout" | "recovery_ended" | "interruption_not_durable" | "startup_cancelled";
-    lifecycleHandled: boolean;
-} | {
-    kind: "interrupted";
+    project: Project;
+    room: ProjectRoom;
+    rosterExempt: boolean;
+}
+/** Fully admitted Project Task target including the owner membership. */
+interface ProjectTaskTarget extends ProjectTaskTargetContext {
+    membership: ProjectBotMembership;
+}
+/** Options for target context resolution. */
+interface ResolveProjectTaskContextOptions {
+    /**
+     * Whether to require completed dependencies (default `true`).
+     *
+     * @remarks Recovery revalidation skips dependency reads because the task was
+     * already admitted when it started; planning/start always checks them.
+     */
+    dependencies?: boolean;
+}
+/** Collaborators required to resolve Project Task admission facts. */
+interface ProjectTaskTargetResolverDependencies {
+    tasks: Pick<TaskStore, "getById">;
+    projects: Pick<ProjectStore, "getProjectById">;
+    rooms: Pick<ProjectRoomStore, "getMainRoom">;
+    bots: Pick<ProjectBotMembershipStore, "findByAssistant">;
+    /** JIT-materializes a public-project task owner so it has a room anchor to post/reply. */
+    ensurePublicOwner?: (input: {
+        tenantId: string;
+        projectId: string;
+        assistantId: string;
+    }) => Promise<unknown>;
+}
+/**
+ * Single admission authority for Project Task planning and execution.
+ *
+ * @remarks All reads are canonical store reads; the only write is the optional
+ * public-project owner materialization, which runs only after task scope,
+ * project, room, and dependency checks pass.
+ */
+declare class ProjectTaskTargetResolver {
+    private readonly deps;
+    /** @param deps Canonical Task, Project, room, and roster reads plus public JIT. */
+    constructor(deps: ProjectTaskTargetResolverDependencies);
+    /**
+     * Loads an exact Project Task and optionally rejects caller-snapshot drift.
+     *
+     * @param input Tenant, task id, and optional caller snapshot.
+     * @returns The canonical Task.
+     * @throws {@link ProjectTaskTargetError} when the task is missing, out of scope, or drifted.
+     */
+    requireTask(input: RequireProjectTaskInput): Promise<TaskItem>;
+    /**
+     * Asserts that a Task status is admissible for a mode.
+     *
+     * @param task Canonical Project Task.
+     * @param mode Admission mode.
+     * @throws {@link ProjectTaskTargetError} when the status is not allowed.
+     */
+    assertModeStatus(task: TaskItem, mode: ProjectTaskAdmissionMode): void;
+    /**
+     * Resolves project, main room, and dependency admission.
+     *
+     * @param task Canonical Project Task.
+     * @param options Dependency toggle (recovery skips dependencies).
+     * @returns The non-roster scope.
+     * @throws {@link ProjectTaskTargetError} on scope or dependency drift.
+     */
+    resolveContext(task: TaskItem, options?: ResolveProjectTaskContextOptions): Promise<ProjectTaskTargetContext>;
+    /**
+     * Resolves the owner membership, materializing a public-project owner first.
+     *
+     * @param task Canonical Project Task.
+     * @param context Non-roster scope from {@link resolveContext}.
+     * @returns The fully admitted target.
+     * @throws {@link ProjectTaskTargetError} when roster authority is invalid.
+     */
+    resolveOwner(task: TaskItem, context: ProjectTaskTargetContext): Promise<ProjectTaskTarget>;
+    /**
+     * Resolves the full target (scope, dependencies, then owner membership).
+     *
+     * @param task Canonical Project Task.
+     * @param options Dependency toggle.
+     * @returns The fully admitted target.
+     */
+    resolveTarget(task: TaskItem, options?: ResolveProjectTaskContextOptions): Promise<ProjectTaskTarget>;
+    /**
+     * Validates canonical Task Thread metadata against stable scope.
+     *
+     * @param task Canonical Project Task.
+     * @param thread Candidate Task execution Thread.
+     * @param roomId Exact Project main room id.
+     * @param owner Optional admitted owner; when supplied, a non-exempt project
+     *   additionally requires the metadata membership id to equal the roster id.
+     * @returns The canonical Thread snapshot.
+     * @remarks The metadata's `membershipId` is accepted as canonical for public
+     * projects: a synthetic owner membership and the materialized Thread's real
+     * roster membership id legitimately differ. Business projects must match.
+     * @throws {@link ProjectTaskTargetError} on any scope, membership, or parent-task mismatch.
+     */
+    requireThread(task: TaskItem, thread: Thread, roomId: string, owner?: Pick<ProjectTaskTarget, "membership" | "rosterExempt">): Thread;
+    private assertDependenciesReady;
+}
+
+/** Input identifying the Project Task to create a run for. */
+interface ProjectTaskRunInput {
+    /** Tenant that owns the task. */
+    tenantId: string;
+    /** Persisted Project Task identifier. */
+    taskId: string;
+    /** Actor attributed to the lifecycle transition; defaults to the service actor. */
+    actor?: string;
+}
+/** Resume input carrying the optional HITL command. */
+interface ProjectTaskResumeInput extends ProjectTaskRunInput {
+    /** HITL resume command; when omitted the run carries a normal resume input. */
+    command?: ProjectTaskRunCommand;
+}
+/** Successful dispatch result returned after the pending run row is committed. */
+interface ProjectTaskRunDispatchResult {
+    /** Discriminator for callers switching on the result shape. */
+    kind: "dispatched";
+    /** Task snapshot after the lifecycle transition. */
     task: TaskItem;
-    thread: Thread;
-    messageId: string;
-} | {
-    kind: "aborted";
+    /** Canonical Task execution Thread the run executes on. */
+    threadId: string;
+    /** Identifier of the committed pending run. */
+    runId: string;
+}
+/** Compatibility options accepted by {@link ProjectTaskRunService.dispatchDetached}. */
+interface ProjectTaskDetachedOptions {
+    /** HITL resume command; only attached when the task is genuinely interrupted. */
+    command?: ProjectTaskRunCommand;
+    /** Expected task status guard evaluated before routing; defaults to no guard. */
+    expectedStatus?: TaskItem["status"];
+}
+/** Detached dispatch result matching the Project Task execution caller contract. */
+interface ProjectTaskRunDetachedResult {
+    /** Task snapshot after the lifecycle transition. */
     task: TaskItem;
-    thread: Thread;
-    messageId: string;
-} | {
+    /** Canonical Task execution Thread the run executes on. */
+    threadId: string;
+    /** The pending run row was committed. */
+    queued: true;
+    /** Identifier of the committed pending run. */
+    runId: string;
+}
+/** Structured warning sink used for observable convergence failures. */
+interface ProjectTaskRunLogger {
+    /**
+     * @param message Human-readable warning.
+     * @param context Structured diagnostic fields (`taskId`, `code`, `error`, …).
+     */
+    warn(message: string, context: Record<string, unknown>): void;
+}
+/** Collaborators required to transition a Project Task and create its run. */
+interface ProjectTaskRunServiceDependencies {
+    /** Canonical task reads used for admission. */
+    tasks: Pick<TaskStore, "getById">;
+    /** Project reads used for scope admission. */
+    projects: Pick<ProjectStore, "getProjectById">;
+    /** Main-room reads used for scope admission. */
+    rooms: Pick<ProjectRoomStore, "getMainRoom">;
+    /** Roster reads used to authorize the task owner. */
+    bots: Pick<ProjectBotMembershipStore, "findByAssistant">;
+    /** Canonical Project Task Thread resolution. */
+    threads: ProjectTaskThreadService;
+    /** Governed task lifecycle operations. */
+    lifecycle: TaskLifecycleService;
+    /** Durable run ledger that owns the pending queue row. */
+    ledger: IAgentRunLedger;
+    /** Best-effort wake after the pending row commits. */
+    wake: () => Promise<void>;
+    /** JIT-materializes a public-project task owner so it has a room anchor to post/reply. */
+    ensurePublicOwner?: (input: {
+        tenantId: string;
+        projectId: string;
+        assistantId: string;
+    }) => Promise<unknown>;
+    /** Run id factory; defaults to `randomUUID`. */
+    idFactory?: () => string;
+    /** Default actor when a dispatch omits one; defaults to `system`. */
+    actor?: string;
+    /** Optional structured warning sink for failed task convergence; defaults to no-op. */
+    log?: ProjectTaskRunLogger;
+    /** Injectable admission resolver for tests; defaults to a canonical resolver. */
+    targets?: ProjectTaskTargetResolver;
+    /** Injectable run planner for tests; defaults to a canonical planner. */
+    planner?: ProjectTaskRunPlanner;
+}
+/**
+ * Creates durable Project Task runs after applying the canonical lifecycle transition.
+ *
+ * @remarks This service replaces only the Project Task dispatch transport. It
+ * performs admission through {@link ProjectTaskTargetResolver}, resolves the
+ * canonical Thread through {@link ProjectTaskThreadService}, builds one
+ * `source="project_task"` intent through {@link ProjectTaskRunPlanner}, commits
+ * the pending {@link IAgentRunLedger} row, and wakes the run queue. It never
+ * enqueues on the legacy thread message queue and never waits for execution
+ * settlement; Task completion remains the worker's `manage_task` write.
+ */
+declare class ProjectTaskRunService {
+    private readonly deps;
+    private readonly targets;
+    private readonly planner;
+    private readonly runBridge;
+    private readonly idFactory;
+    private readonly log;
+    /** @param deps Canonical stores, lifecycle, ledger, and queue wake collaborators. */
+    constructor(deps: ProjectTaskRunServiceDependencies);
+    /**
+     * Starts a pending Project Task and creates its first run.
+     *
+     * @param input Tenant, task id, and optional actor.
+     * @returns The `in_progress` task snapshot and committed run id.
+     * @throws {@link ProjectTaskRunDispatchError} when admission, the lifecycle
+     * CAS, or run creation fails.
+     */
+    start(input: ProjectTaskRunInput): Promise<ProjectTaskRunDispatchResult>;
+    /**
+     * Resumes an interrupted Project Task and creates its continuation run.
+     *
+     * @param input Tenant, task id, optional actor, and optional HITL command.
+     * @returns The `in_progress` task snapshot and committed run id.
+     * @throws {@link ProjectTaskRunDispatchError} when admission, the resume
+     * transition, or run creation fails.
+     */
+    resume(input: ProjectTaskResumeInput): Promise<ProjectTaskRunDispatchResult>;
+    /**
+     * Retries a failed or reopens a terminal Project Task, then creates an input run.
+     *
+     * @param input Tenant, task id, and optional actor.
+     * @returns The `in_progress` task snapshot and committed run id.
+     * @throws {@link ProjectTaskRunDispatchError} when admission, the retry/reopen
+     * transition, or run creation fails.
+     */
+    restart(input: ProjectTaskRunInput): Promise<ProjectTaskRunDispatchResult>;
+    /**
+     * Routes a Project Task to the transition its current status requires.
+     *
+     * @param input Tenant, task id, optional actor, and optional resume command.
+     * @returns The `in_progress` task snapshot and committed run id.
+     * @throws {@link ProjectTaskRunDispatchError} when the task is already
+     * `in_progress` or any transition/run creation fails.
+     * @remarks `pending` starts, `interrupted` resumes, and `failed`/`completed`/
+     * `cancelled` retry or reopen. A resume command is only attached to an
+     * interrupted-task resume.
+     */
+    dispatch(input: ProjectTaskResumeInput): Promise<ProjectTaskRunDispatchResult>;
+    /**
+     * Creates the run without awaiting execution.
+     *
+     * @param input Tenant, task id, and optional actor.
+     * @param _signal Retained for the existing caller shape; dispatch never waits.
+     * @param options Optional expected-status guard and HITL resume command.
+     * @returns The `in_progress` task snapshot, `queued: true`, and committed run id.
+     * @throws {@link ProjectTaskRunDispatchError} with
+     * `PROJECT_TASK_NOT_RESUMABLE` when `expectedStatus` no longer matches.
+     * @remarks Run creation is already detached (this service never waits for
+     * settlement). A resume command is only attached when the task is genuinely
+     * interrupted, matching {@link dispatch}.
+     */
+    dispatchDetached(input: ProjectTaskRunInput, _signal?: AbortSignal, options?: ProjectTaskDetachedOptions): Promise<ProjectTaskRunDetachedResult>;
+    /**
+     * Reads the active (`pending`/`running`) run for a Project Task.
+     *
+     * @param input Tenant and persisted task id.
+     * @returns The active run record, or `undefined` when no run is active.
+     * @remarks Recovery uses this instead of queue-row classification; a missing
+     * row means no executor owns the task, not that work is still queued.
+     */
+    getActiveRun(input: {
+        tenantId: string;
+        taskId: string;
+    }): Promise<AgentRunRecord | undefined>;
+    /**
+     * Reads the newest durable run recorded for a Project Task Thread.
+     *
+     * @param input Tenant, task id, and canonical Task Thread id.
+     * @returns The newest matching `source="project_task"` run for the task, or `undefined`.
+     * @remarks Used by startup recovery to settle a lost terminal run when no
+     * active run exists. Reads the run ledger directly; the legacy queue is never
+     * consulted.
+     */
+    getLatestRun(input: {
+        tenantId: string;
+        taskId: string;
+        threadId: string;
+    }): Promise<AgentRunRecord | undefined>;
+    private dispatchLoaded;
+    private startValidated;
+    private resumeValidated;
+    private restartValidated;
+    /**
+     * Resolves an already-active run for the same task and Thread.
+     *
+     * @param task Canonical task snapshot.
+     * @param thread Canonical execution Thread.
+     * @param actor Actor attributed to convergence if the ledger lookup fails.
+     * @param conflictCode Typed code used when the active run belongs to another
+     *   Thread or, when required, when no active run exists.
+     * @param requireActive Whether a missing active run is a conflict.
+     * @returns The idempotent dispatched result, or `undefined` when no active run
+     *   exists and `requireActive` is false.
+     * @throws {@link ProjectTaskRunDispatchError} with
+     * `PROJECT_TASK_RUN_LOOKUP_FAILED` after converging the task when the ledger
+     * lookup itself fails.
+     */
+    private idempotentDispatch;
+    /**
+     * Plans the run intent and commits the pending row, converging on failure.
+     *
+     * @remarks A planner or ledger failure after the lifecycle transition calls
+     * `bridge.settleRun(failed)` best-effort so the task never stays `in_progress`
+     * without a durable run. An already-active run for this task makes the
+     * dispatch idempotent instead of creating a second run.
+     */
+    private planAndCreate;
+    private convergeFailure;
+    private wakeSafely;
+    private requireTask;
+    private resolveTarget;
+    private ensureThread;
+    private assertAgentOwned;
+    private assertStatus;
+    private resolveActor;
+}
+
+/** Result of one Project Task dispatch committed to the durable run queue. */
+interface ProjectTaskRunOutcome {
     kind: "deferred";
     task: TaskItem;
     thread: Thread;
     messageId: string;
-};
-/** Stable classification of the queue fact used to recover an in-progress Project Task. */
-type ProjectTaskRecoveryClassification = {
-    kind: "pending" | "processing";
-    inputMessageId: string;
-} | {
-    kind: "missing";
-} | {
-    kind: "invalid";
-    reason: string;
-};
-/** Runtime bounds for Project Task settlement. */
-interface ProjectTaskExecutionOptions {
-    /** Maximum time to retain Agent listeners while awaiting execution settlement. */
-    settlementTimeoutMs: number;
-    /** Maximum time to await lifecycle persistence after a failed or inconsistent execution. */
-    lifecycleSettlementTimeoutMs: number;
-    /** Queue message id factory; defaults to `randomUUID`. */
-    idFactory?: () => string;
+    runId: string;
 }
+/** Durable run-queue port used by the Project Task dispatch path. */
+type ProjectTaskRunServicePort = Pick<ProjectTaskRunService, "start" | "resume" | "dispatch" | "dispatchDetached" | "getActiveRun" | "getLatestRun">;
 /**
  * Optional resume command threaded into the queued trusted run message.
  *
@@ -775,92 +1246,61 @@ interface ProjectTaskResumeOptions {
      */
     expectedStatus?: TaskItem["status"];
 }
-/** Collaborators required to validate, dispatch, recover, and settle Project Task executions. */
+/** Collaborators required to dispatch Project Task executions. */
 interface ProjectTaskExecutionDependencies {
-    tasks: TaskStore;
-    projects: Pick<ProjectStore, "getProjectById">;
-    rooms: Pick<ProjectRoomStore, "getMainRoom">;
-    bots: Pick<ProjectBotMembershipStore, "findByAssistant">;
-    threads: ProjectTaskThreadService;
-    lifecycle: TaskLifecycleService;
-    dispatcher: TrustedAgentMessageDispatcher;
-    queue: IMessageQueueStore;
-    agentFor: (task: TaskItem, thread: Thread) => Agent;
-    /** JIT-materializes a public-project task owner so it has a room anchor to post/reply. */
-    ensurePublicOwner?: (input: {
-        tenantId: string;
-        projectId: string;
-        assistantId: string;
-    }) => Promise<unknown>;
-    /**
-     * Optional gateway hook: a task thread paused with a durable interruption.
-     *
-     * @remarks Best-effort and fire-and-forget: it never blocks or alters
-     * settlement. It may fire more than once for the same interrupt (the
-     * `message:interrupted` event path and the recovery path), so consumers must
-     * dedupe using the correlation key derived from `messageId`.
-     */
-    onTaskInterrupted?: (input: {
-        task: TaskItem;
-        thread: Thread;
-        messageId: string;
-        state: unknown;
-    }) => void | Promise<void>;
-}
-/** Input for recovering exactly one persisted Project Task queue execution. */
-interface RecoverProjectTaskExecutionInput {
-    task: TaskItem;
-    thread: Thread;
-    inputMessageId: string;
-    mode: "pending" | "processing";
+    /** Canonical Task Thread reads used to map a committed run to its thread. */
+    threads: Pick<ProjectTaskThreadService, "getThreadById">;
+    /** Durable run-queue dispatch and run-ledger read port. */
+    runService: ProjectTaskRunServicePort;
 }
 /**
- * Executes and recovers Project Tasks on canonical Task Threads.
+ * Dispatches Project Tasks on the durable run queue.
  *
- * The service arms exact Agent listeners before enqueue/recovery and treats Task lifecycle
- * persistence as authoritative. Its caller owns machine serialization through the returned
- * settlement promise; a generic Agent completion never completes a Task by itself.
+ * @remarks This service is a thin adapter over {@link ProjectTaskRunService}.
+ * The run worker owns execution and settlement; dispatch only commits one
+ * `source="project_task"` pending run and returns a deferred outcome. Recovery is
+ * owned by {@link ProjectTaskObserver} through the active/latest run reads exposed
+ * here.
  */
 declare class ProjectTaskExecutionService {
     private readonly deps;
-    private readonly options;
-    private readonly runBridge;
     /**
-     * @param deps Persistence, lifecycle, dispatch, and Agent collaborators.
-     * @param options Settlement watchdog bounds.
+     * @param deps Canonical Thread reads and the durable run-queue port.
      */
-    constructor(deps: ProjectTaskExecutionDependencies, options: ProjectTaskExecutionOptions);
-    /** Validates, atomically starts, dispatches, and settles a pending Project Task. */
+    constructor(deps: ProjectTaskExecutionDependencies);
+    /** Reads the active durable run for a Project Task. */
+    getActiveProjectTaskRun(task: TaskItem): Promise<AgentRunRecord | undefined>;
+    /**
+     * Reads the newest durable run for an `in_progress` Project Task.
+     *
+     * @returns The newest matching run, or `undefined` when the task has no
+     * recorded run or no canonical Thread.
+     */
+    getLatestProjectTaskRun(task: TaskItem): Promise<AgentRunRecord | undefined>;
+    /** Validates, starts, and dispatches a pending Project Task run. */
     start(input: {
         tenantId: string;
         taskId: string;
         actor?: string;
     }, signal?: AbortSignal): Promise<ProjectTaskRunOutcome>;
-    /** Performs the pending→in_progress transition and loads the exact current task. */
-    private prepareStart;
-    /** Resumes an interrupted Project Task on its canonical existing Thread. */
+    /** Resumes an interrupted Project Task and creates its continuation run. */
     resume(input: {
         tenantId: string;
         taskId: string;
         actor?: string;
     }, signal?: AbortSignal, options?: ProjectTaskResumeOptions): Promise<ProjectTaskRunOutcome>;
-    /** Clears the durable interruption and loads the exact resumed task. */
-    private prepareResume;
     /**
      * Dispatches a Project Task by selecting the correct pre-run transition for
-     * its current status, then running it.
+     * its current status, then committing one run.
      *
      * @param input Tenant, task identity, and optional command actor.
-     * @param signal Optional cancellation signal for the armed settlement.
-     * @param options Optional resume command carried into the queued run message.
-     * @returns The settled run outcome.
+     * @param signal Optional cancellation signal checked before dispatch.
+     * @param options Optional resume command carried into the queued run.
+     * @returns The deferred run outcome.
      * @remarks `start` semantics: make this task run. `pending` starts,
      * `interrupted` resumes, `failed` retries, and `completed`/`cancelled`
      * reopen, each followed by a trusted run dispatch. `in_progress` is a
-     * conflict. This is a record transition plus an application-layer side
-     * effect; the kernel only records the status change. `actor` attributes the
-     * start/resume/retry/reopen transition and defaults to the system actor.
-     * `options.command` is only carried on an interrupted-task resume.
+     * conflict. `options.command` is only carried on an interrupted-task resume.
      */
     dispatch(input: {
         tenantId: string;
@@ -868,17 +1308,12 @@ declare class ProjectTaskExecutionService {
         actor?: string;
     }, signal?: AbortSignal, options?: ProjectTaskResumeOptions): Promise<ProjectTaskRunOutcome>;
     /**
-     * Dispatches a Project Task without awaiting its settlement.
+     * Dispatches a Project Task without awaiting execution.
      *
      * @param input Tenant, task identity, and optional command actor.
-     * @param signal Optional cancellation signal for the pre-run transition.
-     * @param options Optional resume command carried into the queued run message.
+     * @param signal Optional cancellation signal checked before dispatch.
+     * @param options Optional expected-status guard and HITL resume command.
      * @returns The `in_progress` task snapshot and whether the run was queued.
-     * @remarks Intended for command HTTP handlers that must release the Project
-     * mutation mutex immediately: the armed settlement keeps running in the
-     * background (completion, watchdog, and convergence) but the caller never
-     * awaits it. Enqueue failure converges the task exactly like the awaited
-     * path before throwing, so no phantom run is left behind.
      */
     dispatchDetached(input: {
         tenantId: string;
@@ -888,79 +1323,9 @@ declare class ProjectTaskExecutionService {
         task: TaskItem;
         queued: boolean;
     }>;
-    /** Recovers one exact pending or processing queue row without dispatching a duplicate input. */
-    recover(input: RecoverProjectTaskExecutionInput, signal?: AbortSignal): Promise<ProjectTaskRunOutcome>;
-    /** Classifies one exact Task Thread queue fact with transition-safe repeated reads. */
-    classifyRecovery(task: TaskItem, thread: Thread): Promise<ProjectTaskRecoveryClassification>;
-    private requireTask;
-    private validateReadyTask;
-    private validateResumableTask;
-    /**
-     * Retries a failed task or reopens a terminal task, then runs it on its
-     * canonical existing Thread.
-     *
-     * @param task Task snapshot already routed to the restartable branch.
-     * @param actor Actor attributed to the retry/reopen transition.
-     * @param signal Optional cancellation signal for the armed settlement.
-     * @returns The settled run outcome.
-     */
-    private dispatchRestartable;
-    /** Retries a failed task or reopens a terminal task, then loads the exact current task. */
-    private prepareRestartable;
-    private validateRestartableTask;
-    private validateReadyTaskSnapshot;
-    private requireRoom;
-    private requireMembership;
-    private requireCurrentThread;
-    private dispatchRun;
-    /**
-     * Arms the exact settlement and enqueues the trusted run without awaiting settlement.
-     *
-     * @returns The armed settlement plus the enqueue result. A declined or thrown
-     *   enqueue yields `queued: false` with a stable reason; the caller decides
-     *   whether to converge only (awaited path) or converge and throw (detached).
-     */
-    private armAndEnqueue;
-    /**
-     * Arms and enqueues a run, then returns an `in_progress` snapshot immediately.
-     *
-     * @remarks The settlement continues in the background. On enqueue failure the
-     * task is converged exactly like the awaited path before throwing, so no
-     * phantom in-progress run is left behind.
-     */
-    private enqueueDetached;
-    private claimDispatchFailure;
-    private armSettlement;
+    private dispatchRunQueue;
+    private toDetachedOptions;
     private throwIfCancelled;
-    private awaitSettlementCancellation;
-    private cancelSettlement;
-    private compensateCancellation;
-    private reloadTask;
-    private settleInterruptedEvent;
-    /**
-     * Fire-and-forget best-effort projection of a durable interruption.
-     *
-     * @remarks Never awaited and never allowed to affect settlement. The state is
-     * resolved lazily so a missing/undefined event state only triggers a thread
-     * read when the hook is actually wired.
-     */
-    private emitInterrupted;
-    /** Reads the paused thread snapshot when no interrupt event payload is available (recovery). */
-    private readInterruptedThreadState;
-    /**
-     * Persists a durable `missing_input` interruption for a paused clarify question.
-     *
-     * @remarks The task must survive the pause so the room can answer it; the
-     * agent resumes the same run once the answer arrives.
-     */
-    private interruptForClarify;
-    private settleEndedRecovery;
-    private terminalOutcome;
-    private matchesExecution;
-    private failSettledTaskAwaited;
-    private withLifecycleTimeout;
-    private failSettledTask;
-    private validateExistingExecution;
 }
 
 /** Aggregate result of one bounded deterministic startup reconciliation. */
@@ -1096,64 +1461,85 @@ declare const defaultSwaggerUiConfig: {
     transformStaticCSP: (header: string) => string;
 };
 
-type QueueServiceType = "memory" | "redis";
+/** Optional startup/shutdown hooks for host-provided Gateway resources. */
+interface GatewayLifespan {
+    /** Optional name used in shutdown error logs. */
+    name?: string;
+    /** Runs after the Fastify app is ready, before listen resolves. */
+    onStartup?: (app: FastifyInstance) => void | Promise<void>;
+    /** Runs when the Fastify app closes (signal or host close). */
+    onShutdown?: (app: FastifyInstance) => void | Promise<void>;
+}
+/** Minimal logger seam for best-effort shutdown diagnostics. */
+interface LifespanLogger {
+    /** Log a warning without failing shutdown. */
+    warn(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Install ordered Gateway lifespan hooks exactly once per Fastify instance.
+ *
+ * Startup hooks run in array order and a failure rejects `app.ready()` /
+ * `listen`. Shutdown hooks also run in order, but failures are logged and do
+ * not prevent later hooks or app close from completing.
+ *
+ * @param app - Fastify instance.
+ * @param lifespans - One hook or an ordered array.
+ * @param log - Optional logger for shutdown failures.
+ */
+declare function installLifespanHooks(app: FastifyInstance, lifespans?: GatewayLifespan | GatewayLifespan[], log?: LifespanLogger): void;
+
+/**
+ * Redis Streams implementation of the core {@link AppendLog} port.
+ *
+ * Each append is one `XADD` entry carrying the JSON payload in the `v` field.
+ * Readers use a dedicated duplicated connection so a blocking `XREAD` never
+ * stalls ordinary appends or ranges on the base connection.
+ */
 
-interface AgentTaskRequest {
-    assistant_id: string;
-    input: any;
-    thread_id: string;
-    "x-tenant-id": string;
-    command?: any;
-    callback_event?: string;
-    runConfig?: Record<string, any>;
-    main_thread_id?: string;
-    main_tenant_id?: string;
-    main_assistant_id?: string;
+/** Structured logger accepted by the Redis append-log adapter. */
+interface RedisAppendLogLogger {
+    /** Report a connection or decoding problem with context. */
+    warn(message: string, context: Record<string, unknown>): void;
+}
+/** Optional adapter configuration. */
+interface RedisAppendLogOptions {
+    /** Logger for connection errors and corruption diagnostics. */
+    logger?: RedisAppendLogLogger;
+    /** Key prefix applied by the caller's buffer (documented for diagnostics). */
+    keyPrefix?: string;
+}
+/** Handle owning a Redis-backed append log and its base connection. */
+interface RedisAppendLogHandle {
+    /** Shared append log backed by Redis Streams. */
+    log: AppendLog;
+    /** Close the base connection (readers own their own connections). */
+    close(): Promise<void>;
 }
 /**
- * Agent任务消费者
- * 负责监听和执行Agent任务事件，同时从队列中消费任务
+ * Raised when a Redis Stream entry cannot be decoded.
+ *
+ * Corrupt entries fail loudly instead of being skipped: silently dropping a
+ * trailing malformed record would make a tailing reader spin forever.
  */
-declare class AgentTaskConsumer {
-    private isPolling;
-    private pollingInterval;
-    private pollingIntervalMs;
-    private maxConcurrentTasks;
-    private activeTasks;
-    private processing;
-    private immediateProcessingEnabled;
-    gatewayPort: number;
-    static agent_run_endpoint: string;
-    constructor(gatewayPort: number, pollingIntervalMs?: number);
-    /**
-     * 初始化事件监听和队列轮询
-     */
-    private initialize;
-    /**
-     * 启动队列轮询
-     */
-    startPollingQueue(): void;
+declare class ChunkLogCorruptionError extends Error {
+    /** Cursor of the offending stream entry. */
+    readonly cursor: string;
+    /** Machine-readable error code. */
+    readonly code = "CHUNK_LOG_CORRUPTION";
     /**
-     * 停止队列轮询
+     * @param cursor - Cursor of the offending stream entry
+     * @param reason - Why the entry could not be decoded
      */
-    stopPollingQueue(): void;
-    /**
-     * 处理单个任务并在完成后立即尝试处理下一个
-     */
-    processNextTask(): Promise<boolean>;
-    /**
-     * 检查队列中是否有任务并处理
-     */
-    checkQueueForTasks(): Promise<void>;
-    /**
-     * 从队列中消费任务
-     */
-    consumeFromQueue(): Promise<void>;
-    /**
-     * 处理通过事件触发的任务
-     */
-    trigger_agent_task(taskRequest: AgentTaskRequest): void;
+    constructor(cursor: string, reason: string);
 }
+/**
+ * Create a Redis Streams append log.
+ *
+ * @param url - Redis connection URL (for example `redis://localhost:6379`)
+ * @param options - Optional logger/diagnostics configuration
+ * @returns A handle exposing the log and a close function
+ */
+declare function createRedisAppendLog(url: string, options?: RedisAppendLogOptions): Promise<RedisAppendLogHandle>;
 
 /**
  * Builds a cross-replica task-liveness probe from the registered `"lease"` store.
@@ -1462,6 +1848,91 @@ declare function publishRoomEvent(outbox: OutboxStore, owner: string, scope: Pro
  */
 declare function ingestRoomEvent(payload: unknown, broker: ProjectRoomEventBroker): boolean;
 
+/** Outbox topic carrying mirrored Agent lifecycle events across replicas. */
+declare const AGENT_LIFECYCLE_TOPIC = "agent-lifecycle";
+/**
+ * Agent lifecycle events that are mirrored through the durable outbox.
+ *
+ * Only events consumed by cross-replica delivery paths are mirrored
+ * (`MessageRouter` replies and task settlement); high-frequency execution
+ * progress events stay process-local.
+ */
+declare const MIRRORED_AGENT_EVENTS: readonly ["reply:ready", "message:completed", "message:failed", "message:interrupted"];
+/** Minimal local Agent surface needed to deliver a mirrored event. */
+interface AgentLifecycleTarget {
+    /**
+     * Publish an externally sourced lifecycle event to local subscribers.
+     *
+     * @param eventName Lifecycle event name.
+     * @param data Event payload.
+     */
+    publishExternal(eventName: AgentLifecycleEventName, data: unknown): void;
+}
+/** Scope passed to the local Agent resolver. */
+interface AgentLifecycleTargetScope {
+    /** Assistant owning the thread. */
+    assistant_id: string;
+    /** Thread that emitted the original event. */
+    thread_id: string;
+    /** Tenant owning the thread. */
+    tenant_id: string;
+    /** Workspace scope, when known. */
+    workspace_id?: string;
+    /** Project scope, when known. */
+    project_id?: string;
+}
+/** Dependencies for {@link handleAgentLifecycle}. */
+interface AgentLifecycleHandlerDeps {
+    /**
+     * Resolves or creates the local Agent instance for a thread.
+     *
+     * Defaults to the process-wide `agentInstanceManager`; tests may inject a
+     * fake to assert delivery without constructing a real Agent.
+     */
+    getAgent?: (scope: AgentLifecycleTargetScope) => AgentLifecycleTarget;
+}
+/**
+ * Best-effort publish of one mirrored Agent lifecycle event to the durable
+ * outbox.
+ *
+ * @param outbox Shared outbox store.
+ * @param owner This replica id (recorded as the event origin).
+ * @param event Event scope and payload to mirror.
+ * @returns A promise that resolves once the append is attempted.
+ *
+ * @remarks Never throws: mirroring is best-effort / at-most-once, and a lost
+ * event must not affect the local run.
+ */
+declare function publishAgentLifecycle(outbox: OutboxStore, owner: string, event: AgentLifecycleTapEvent): Promise<void>;
+/**
+ * Installs the process-wide Agent lifecycle tap that mirrors selected events
+ * into the shared outbox.
+ *
+ * @param params Outbox plus this replica's id.
+ *
+ * @remarks Only {@link MIRRORED_AGENT_EVENTS} are mirrored. Calling this again
+ * replaces the previous tap.
+ */
+declare function installAgentLifecycleSync(params: {
+    outbox: OutboxStore;
+    owner: string;
+}): void;
+/**
+ * Delivers one foreign outbox payload to the local Agent event bus.
+ *
+ * @param payload Outbox event payload, expected to carry `tenantId`,
+ * `assistantId`, `threadId`, a mirrored `eventName`, and optional scope ids.
+ * @param deps Optional resolver seam (defaults to `agentInstanceManager`).
+ * @returns `true` when the event was delivered; `false` for malformed payloads
+ * or non-mirrored event names.
+ *
+ * @remarks The local Agent is resolved with the mirror's scope so subscribers
+ * attached to that thread receive the event; delivery goes through
+ * {@link AgentLifecycleTarget.publishExternal} and is therefore never mirrored
+ * again.
+ */
+declare function handleAgentLifecycle(payload: unknown, deps?: AgentLifecycleHandlerDeps): boolean;
+
 /** Outbox topic carrying cross-replica A2A API-key invalidation. */
 declare const A2A_KEY_CHANGED_TOPIC = "a2a-key-changed";
 /**
@@ -1578,6 +2049,799 @@ declare class A2AAuthService {
     private extractToken;
 }
 
+/** Default concurrent executing runs per worker (`N_JOBS_PER_WORKER`). */
+declare const DEFAULT_RUN_TASK_JOBS = 10;
+/** Default poll interval when no wake signal arrives. */
+declare const DEFAULT_RUN_TASK_SCAN_MS = 500;
+/** Default run (row) lease duration. */
+declare const DEFAULT_RUN_TASK_LEASE_TTL_MS = 60000;
+/** Default thread-run lease duration. */
+declare const DEFAULT_THREAD_RUN_LEASE_TTL_MS = 60000;
+/**
+ * Shared execution-slot limiter for the scanning worker and recovery loop.
+ *
+ * @remarks Recovered executions consume the same slots as claimed pending
+ * runs, so `N_JOBS_PER_WORKER` is a per-worker bound across both paths.
+ */
+declare class RunTaskConcurrencyLimiter {
+    readonly max: number;
+    private active;
+    /** @param max Maximum concurrently executing runs. */
+    constructor(max: number);
+    /** Slots currently in use. */
+    get inUse(): number;
+    /** Slots currently available. */
+    get available(): number;
+    /** Whether at least one slot is free. */
+    hasCapacity(): boolean;
+    /**
+     * Reserves one slot.
+     *
+     * @returns `true` when a slot was reserved, `false` when the bound is full.
+     */
+    tryAcquire(): boolean;
+    /** Releases one reserved/running slot (idempotent at zero). */
+    release(): void;
+}
+/** Point-in-time worker posture exposed by {@link RunTaskWorker.stats}. */
+interface RunTaskWorkerStats {
+    /** Whether the polling loop is running. */
+    running: boolean;
+    /** Executions currently tracked by the worker. */
+    inFlight: number;
+    /** Concurrency slots currently reserved. */
+    activeSlots: number;
+    /** Concurrency slots still available. */
+    availableSlots: number;
+    /** Configured maximum concurrent executions. */
+    maxConcurrentJobs: number;
+    /** Poll interval used when no wake is delivered. */
+    scanIntervalMs: number;
+    /** Run row lease TTL. */
+    leaseTtlMs: number;
+}
+/** Structured logger accepted by the worker. */
+interface RunTaskLogger {
+    info?(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+}
+/** Minimal Agent surface required to execute one durable run. */
+interface RunTaskAgent {
+    /** Current checkpoint id at the thread tip, when one exists. */
+    getCurrentCheckpointId(): Promise<string | undefined>;
+    /**
+     * Current checkpoint tip plus the run that produced it.
+     *
+     * @remarks Optional for older fakes; without it the worker cannot prove
+     * ownership and therefore treats the run as having no progress.
+     */
+    getCurrentCheckpointTip?(): Promise<AgentCheckpointTip>;
+    /** Execute the run without entering the legacy message queue. */
+    executeRun(input: ExecuteRunInput): Promise<ExecuteRunResult>;
+}
+/** Dependencies accepted by {@link RunTaskWorker}. */
+interface RunTaskWorkerDependencies {
+    /** Durable run ledger/task queue. */
+    ledger: IAgentRunLedger;
+    /** Shared lease store that provides per-thread execution exclusion. */
+    leaseStore: LeaseStore;
+    /** Resolve the managed Agent for a run's thread identity. */
+    getAgent(params: AgentThreadInterface): RunTaskAgent;
+    /** Resolve the checkpoint rollback store, or `undefined` when unsupported. */
+    resolveRollbackStore?(): CheckpointMaintenance | undefined;
+    /** Stable worker identity; used for both the run row and thread-run lease. */
+    owner: string;
+    /** Maximum concurrent executing runs (default 10). */
+    maxConcurrentJobs?: number;
+    /**
+     * Maximum `running` rows per tenant across the selected sources (default
+     * unlimited).
+     *
+     * @remarks The global `maxConcurrentJobs` limiter still applies. This cap is
+     * per tenant and counts only the worker's selected `sources`; it lets a scan
+     * skip tenants already at their cap (best-effort fairness), not strict
+     * round-robin scheduling.
+     */
+    maxRunningPerTenant?: number;
+    /**
+     * Sources this worker may scan and claim.
+     *
+     * @remarks Defaults to `["run_api"]`. Include `"project_task"` to execute
+     * ProjectTask queue work without importing Project or Room modules here.
+     *
+     * @default ["run_api"]
+     */
+    sources?: readonly AgentRunSource[];
+    /**
+     * Rebuild trusted host-authenticated context for a claimed run.
+     *
+     * @remarks Called once before execution. Returning `undefined` executes
+     * without trusted context. Rejecting settles the run through the normal error
+     * path.
+     */
+    resolveTrustedRunContext?: (run: AgentRunRecord) => Promise<TrustedRunContext | undefined>;
+    /**
+     * Best-effort terminal observer for run-queue work.
+     *
+     * @remarks Invoked once after a run settles terminally, including recovered
+     * runs. Failures are logged and never alter the persisted run status.
+     */
+    onRunTerminal?: (input: {
+        run: AgentRunRecord;
+        status: Exclude<AgentRunStatus, "pending" | "running">;
+        error?: string;
+    }) => Promise<void>;
+    /** Shared limiter; when supplied, `maxConcurrentJobs` is ignored. */
+    limiter?: RunTaskConcurrencyLimiter;
+    /** Poll interval used when no wake is delivered (default 500ms). */
+    scanIntervalMs?: number;
+    /** Run row lease TTL (default 60s). */
+    leaseTtlMs?: number;
+    /** Run lease heartbeat interval (default `leaseTtlMs / 3`, min 100ms). */
+    heartbeatMs?: number;
+    /** Cancellation/rollback flag poll interval (default 1000ms). */
+    cancelPollMs?: number;
+    /** Maximum rollback failures before terminal convergence (default 3). */
+    maxRollbackAttempts?: number;
+    /** Thread-run lease heartbeat interval (default `leaseTtlMs / 3`, min 100ms). */
+    threadHeartbeatMs?: number;
+    /** Optional structured logger. */
+    logger?: RunTaskLogger;
+    /** Clock seam for backoff/tests (default `Date.now`). */
+    now?: () => number;
+    /** Bounded wait for in-flight runs on stop (default 30s). */
+    shutdownTimeoutMs?: number;
+}
+type RunTaskAbortReason = "cancel" | "rollback" | "lease" | "shutdown";
+/** In-flight execution handle shared with the run-task recovery loop. */
+interface RunTaskExecutionState {
+    readonly controller: AbortController;
+    abortReason?: RunTaskAbortReason;
+    promise: Promise<void>;
+}
+/**
+ * Claims and executes durable run-queue pending runs for `sources`.
+ *
+ * @remarks
+ * - The run row and the existing `thread-run` lease share one owner identity.
+ * - A candidate is claimed only after the thread-run lease is acquired; a lost
+ *   claim releases the lease and leaves the row untouched.
+ * - Pending work is discovered by a fair tenant-interleaved scan, so one
+ *   blocked thread or noisy tenant cannot head-of-line block unrelated runs.
+ * - Redis wake is optional: {@link wake} is best-effort and polling is the
+ *   durable fallback.
+ * - Legacy `source='legacy'` rows are never listed or executed here.
+ * - ProjectTask behavior is injected through `resolveTrustedRunContext` and
+ *   `onRunTerminal`; this module never imports Project or Room code.
+ */
+declare class RunTaskWorker {
+    private readonly ledger;
+    private readonly leaseStore;
+    private readonly getAgent;
+    private readonly resolveRollbackStore;
+    private readonly owner;
+    private readonly maxRunningPerTenant?;
+    private readonly sources;
+    private readonly resolveTrustedRunContext?;
+    private readonly onRunTerminal?;
+    private readonly limiter;
+    private readonly scanIntervalMs;
+    private readonly leaseTtlMs;
+    private readonly heartbeatMs;
+    private readonly cancelPollMs;
+    private readonly maxRollbackAttempts;
+    private readonly threadHeartbeatMs;
+    private readonly logger?;
+    private readonly now;
+    private readonly shutdownTimeoutMs;
+    private running;
+    private scanLoop?;
+    private scanAgain;
+    private pollTimer?;
+    private readonly executions;
+    /** @param deps Ledger, leases, Agent resolver, and worker identity/limits. */
+    constructor(deps: RunTaskWorkerDependencies);
+    /**
+     * Returns the worker's current execution posture.
+     *
+     * @returns Running state, in-flight count, and concurrency slots.
+     */
+    stats(): RunTaskWorkerStats;
+    /** Starts the polling loop and an immediate scan. */
+    start(): void;
+    /**
+     * Requests an immediate scan.
+     *
+     * @returns A promise that resolves when the requested scans finish claiming
+     * eligible work. Executions themselves continue in the background.
+     */
+    wake(): Promise<void>;
+    /**
+     * Stops scanning and waits for in-flight runs to settle.
+     *
+     * @param timeoutMs Optional override for the bounded shutdown wait.
+     * @remarks After the deadline the worker aborts remaining executions so they
+     * settle `interrupted` and release their leases before a caller force-exits.
+     */
+    stop(timeoutMs?: number): Promise<void>;
+    /**
+     * Executes a run already claimed/recovered by another component.
+     *
+     * @param run Running record owned by this worker identity.
+     * @param lease Held thread-run lease; released by this method when done.
+     * @param execution Abort state owned by the caller (recovery tracks stop).
+     * @remarks Recovery uses this to run an expired row without requeueing it.
+     */
+    executeRecoveredRun(run: AgentRunRecord, lease: ThreadRunLeaseHandle, execution: RunTaskExecutionState): Promise<void>;
+    private scan;
+    private claimAndStart;
+    private executeClaimed;
+    private buildExecutionRequest;
+    private readCheckpointTip;
+    private startHeartbeat;
+    private heartbeat;
+    private completeRollback;
+    private failRollback;
+    private persistRevision;
+    private settle;
+    private settleOrRollback;
+    private notifyTerminal;
+    private readRun;
+    private warn;
+}
+
+/** Default execution attempts before an expired run settles `timeout`. */
+declare const DEFAULT_RUN_TASK_MAX_ATTEMPTS = 3;
+/** Point-in-time recovery posture exposed by {@link RunTaskRecovery.stats}. */
+interface RunTaskRecoveryStats {
+    /** Whether the periodic recovery loop is running. */
+    running: boolean;
+    /** Recovered executions currently in flight. */
+    active: number;
+    /** Configured maximum concurrent recovered executions. */
+    maxConcurrentJobs: number;
+    /** Recovery scan interval. */
+    intervalMs: number;
+    /** Thread-run lease TTL. */
+    leaseTtlMs: number;
+}
+/**
+ * Executes a run already reclaimed by recovery while the caller holds the
+ * thread-run lease. The executor owns releasing that lease.
+ */
+type RunTaskRecoveredExecutor = (run: AgentRunRecord, lease: ThreadRunLeaseHandle, execution: RunTaskExecutionState) => Promise<void>;
+/** Dependencies accepted by {@link RunTaskRecovery}. */
+interface RunTaskRecoveryDependencies {
+    /** Durable run ledger/task queue. */
+    ledger: IAgentRunLedger;
+    /** Shared lease store used to serialize thread execution and rollback. */
+    leaseStore: LeaseStore;
+    /** Resolve the checkpoint rollback store, or `undefined` when unsupported. */
+    resolveRollbackStore?(): CheckpointMaintenance | undefined;
+    /**
+     * Execute a recovered run through the normal run-task execution path.
+     *
+     * @remarks Absent on API-only replicas. Without it, recovery only finishes
+     * cancel/rollback work and leaves other expired running rows untouched so
+     * they keep blocking queued runs until a worker replica reclaims them.
+     */
+    executeRun?: RunTaskRecoveredExecutor;
+    /**
+     * Best-effort terminal observer for runs recovery settles directly.
+     *
+     * @remarks Covers cancel, attempts-exhausted timeout, lease-loss and rollback
+     * failure settlements. Recovered executions report through the worker hook.
+     * Failures are logged and never alter the recovery outcome.
+     */
+    onRunTerminal?: (input: {
+        run: AgentRunRecord;
+        status: Exclude<AgentRunStatus, "pending" | "running">;
+        error?: string;
+    }) => Promise<void>;
+    /** Stable worker/recovery identity used for the run and thread-run leases. */
+    owner: string;
+    /**
+     * Shared execution-slot limiter with the scanning worker.
+     *
+     * @remarks Recovered executions consume the same `N_JOBS_PER_WORKER` slots as
+     * pending claims. When omitted, recovery creates its own limiter from
+     * `maxConcurrentJobs`.
+     */
+    limiter?: RunTaskConcurrencyLimiter;
+    /** Recovery-only limiter size when no shared limiter is supplied (default 10). */
+    maxConcurrentJobs?: number;
+    /**
+     * Sources this recovery loop may reap.
+     *
+     * @remarks Defaults to `["run_api"]`. Add `"project_task"` to recover
+     * ProjectTask queue work; executed runs flow through the worker's trusted
+     * context and terminal hooks. This list only scopes {@link reapExpired};
+     * pending rollback work remains `run_api`-only because rollback is not
+     * supported for ProjectTask runs.
+     *
+     * @default ["run_api"]
+     */
+    sources?: readonly AgentRunSource[];
+    /** Attempts allowed before a run settles `timeout` (default 3). */
+    maxAttempts?: number;
+    /** Bounded rollback attempts before terminal ROLLBACK_FAILED (default 3). */
+    maxRollbackAttempts?: number;
+    /** Base backoff between failed rollback attempts (default 1000ms). */
+    rollbackBackoffBaseMs?: number;
+    /** Maximum rollback backoff (default 60000ms). */
+    rollbackBackoffMaxMs?: number;
+    /** Scan interval in milliseconds (default 500). */
+    intervalMs?: number;
+    /** Thread-run lease TTL (default 60s). */
+    leaseTtlMs?: number;
+    /** Thread-run lease heartbeat interval (default `leaseTtlMs / 3`). */
+    threadHeartbeatMs?: number;
+    /** Bounded wait for in-flight recovered executions on stop (default 30s). */
+    shutdownTimeoutMs?: number;
+    /** Optional structured logger. */
+    logger?: RunTaskLogger;
+    /** Clock seam for tests (default `Date.now`). */
+    now?: () => number;
+}
+/**
+ * Recovers expired run-queue executions and unfinished rollbacks.
+ *
+ * @remarks
+ * - Only rows whose source is in `sources` (default `["run_api"]`) are
+ *   observed; legacy ledger rows are left to the existing supervisor.
+ * - An expired running row is never requeued. Recovery acquires the
+ *   `thread-run` lease, atomically reclaims the row with a fresh run lease, and
+ *   executes it in place. The row stays `running`, so queued runs on the same
+ *   thread remain blocked until it settles.
+ * - Cancel/rollback requests are routed to `interrupted`. Rollback work then
+ *   acquires the thread-run lease and completes the checkpoint rewind and row
+ *   deletion idempotently.
+ * - A failed checkpoint rewind leaves the run `interrupted` with
+ *   `rollbackRequested=true`, and {@link IAgentRunLedger.listRollbackRuns}
+ *   makes it retryable on later ticks.
+ * - Exhausted attempts settle `timeout`.
+ */
+declare class RunTaskRecovery {
+    private readonly ledger;
+    private readonly leaseStore;
+    private readonly resolveRollbackStore;
+    private readonly executeRun?;
+    private readonly onRunTerminal?;
+    private readonly sources;
+    private readonly limiter;
+    private readonly owner;
+    private readonly maxAttempts;
+    private readonly maxRollbackAttempts;
+    private readonly rollbackBackoffBaseMs;
+    private readonly rollbackBackoffMaxMs;
+    private readonly intervalMs;
+    private readonly leaseTtlMs;
+    private readonly threadHeartbeatMs;
+    private readonly shutdownTimeoutMs;
+    private readonly logger?;
+    private readonly now;
+    private running;
+    private timer?;
+    private tickLoop?;
+    private readonly active;
+    /** @param deps Ledger, leases, recovery policy, and identity. */
+    constructor(deps: RunTaskRecoveryDependencies);
+    /**
+     * Returns the recovery loop's current posture.
+     *
+     * @returns Running state, active recovered executions, and bounds.
+     */
+    stats(): RunTaskRecoveryStats;
+    /** Starts periodic recovery scans and an immediate tick. */
+    start(): void;
+    /**
+     * Stops periodic recovery and waits for in-flight executions to settle.
+     *
+     * @param timeoutMs Optional override for the bounded wait.
+     */
+    stop(timeoutMs?: number): Promise<void>;
+    /**
+     * Runs one recovery scan.
+     *
+     * @remarks Single-flight: concurrent calls share the in-progress scan.
+     */
+    tick(): Promise<void>;
+    private runTick;
+    private recoverAndExecute;
+    private recoverRollback;
+    private failRollbackRecovery;
+    private rollbackBackoffFor;
+    private settleExpired;
+    private notifyTerminal;
+    private warn;
+}
+
+/**
+ * Best-effort wake surface for the durable run task queue.
+ *
+ * @remarks A wake only nudges the local process; the DB pending scan remains
+ * authoritative, so callers may ignore failures.
+ */
+interface RunTaskWake {
+    /** Requests an immediate local scan. */
+    wake(): Promise<void>;
+}
+/** Point-in-time runtime posture exposed by {@link RunTaskRuntime.stats}. */
+interface RunTaskRuntimeStats {
+    /** Whether {@link RunTaskRuntime.start} has run without a later stop. */
+    started: boolean;
+    /** Worker posture, absent on API-only replicas. */
+    worker?: RunTaskWorkerStats;
+    /** Recovery posture. */
+    recovery: RunTaskRecoveryStats;
+}
+/** Dependencies accepted by {@link RunTaskRuntime}. */
+interface RunTaskRuntimeDependencies {
+    /** Durable run ledger/task queue. */
+    ledger: IAgentRunLedger;
+    /** Shared lease store for thread-run exclusion. */
+    leaseStore: LeaseStore;
+    /** Resolve the managed Agent for a run's thread identity. */
+    getAgent(params: AgentThreadInterface): RunTaskAgent;
+    /**
+     * Sources the worker and recovery may scan/reap.
+     *
+     * @remarks Defaults to `["run_api"]` in both loops. Include `"project_task"`
+     * to execute ProjectTask queue work; Task 6 enables it at the composition
+     * root after settlement/observer cutover.
+     *
+     * @default ["run_api"]
+     */
+    sources?: readonly AgentRunSource[];
+    /**
+     * Rebuild trusted host-authenticated context for a claimed run.
+     *
+     * @remarks Forwarded to the worker, including runs recovered by the recovery
+     * loop (recovered executions run through the worker's executor).
+     */
+    resolveTrustedRunContext?: RunTaskWorkerDependencies["resolveTrustedRunContext"];
+    /** Resolve the checkpoint rollback store, or `undefined` when unsupported. */
+    resolveRollbackStore?(): CheckpointMaintenance | undefined;
+    /** Stable worker/recovery identity. */
+    owner: string;
+    /**
+     * Start the execution worker (default `true`).
+     *
+     * @remarks Set `false` on API-only replicas. Recovery still starts so
+     * rollback requests left by another replica can be completed.
+     */
+    executeEnabled?: boolean;
+    /** Maximum concurrent executing runs (default 10). */
+    maxConcurrentJobs?: number;
+    /**
+     * Maximum `running` rows per tenant across the selected sources (default
+     * unlimited).
+     *
+     * @remarks Global `maxConcurrentJobs` still bounds this worker. The cap is
+     * per tenant and used by pending scans/claims for best-effort fairness; it is
+     * not strict round-robin scheduling.
+     */
+    maxRunningPerTenant?: number;
+    /**
+     * Best-effort terminal observer shared by the worker and recovery.
+     *
+     * @remarks Invoked once per run that becomes terminal, whether claimed by the
+     * worker or settled directly by recovery. Failures are logged and never alter
+     * run status or recovery outcome.
+     */
+    onRunTerminal?: RunTaskWorkerDependencies["onRunTerminal"];
+    /** Pending-run poll interval (default 500ms). */
+    scanIntervalMs?: number;
+    /** Recovery scan interval (default 500ms). */
+    recoveryIntervalMs?: number;
+    /** Run/thread lease TTL (default 60s). */
+    leaseTtlMs?: number;
+    /** Run lease heartbeat interval. */
+    heartbeatMs?: number;
+    /** Cancellation/rollback flag poll interval (default 1000ms). */
+    cancelPollMs?: number;
+    /** Bounded rollback attempts before terminal ROLLBACK_FAILED. */
+    maxRollbackAttempts?: number;
+    /** Base backoff between failed rollback attempts. */
+    rollbackBackoffBaseMs?: number;
+    /** Maximum rollback backoff. */
+    rollbackBackoffMaxMs?: number;
+    /** Thread-run lease heartbeat interval. */
+    threadHeartbeatMs?: number;
+    /** Execution attempts before an expired run settles `timeout`. */
+    maxAttempts?: number;
+    /** Bounded shutdown wait. */
+    shutdownTimeoutMs?: number;
+    /** Optional structured logger. */
+    logger?: RunTaskLogger;
+    /** Clock seam for tests. */
+    now?: () => number;
+}
+/**
+ * Process-level runtime for the durable run task queue.
+ *
+ * @remarks Starts the execution worker (unless this is an API-only replica) and
+ * the recovery loop. Recovery always runs because durable rollback requests can
+ * exist even when this replica never executes agent code.
+ */
+declare class RunTaskRuntime implements RunTaskWake {
+    /** Execution worker, absent when this replica is API-only. */
+    readonly worker?: RunTaskWorker;
+    /** Expired-run and rollback recovery loop. */
+    readonly recovery: RunTaskRecovery;
+    private started;
+    /** @param deps Ledger, leases, worker/recovery policy, and identity. */
+    constructor(deps: RunTaskRuntimeDependencies);
+    /**
+     * Returns the runtime, worker, and recovery posture.
+     *
+     * @returns Snapshot with worker stats omitted on API-only replicas.
+     */
+    stats(): RunTaskRuntimeStats;
+    /** Starts the worker (when present) and recovery. */
+    start(): void;
+    /** Stops both loops and waits for in-flight work within their bounds. */
+    stop(): Promise<void>;
+    /**
+     * Requests an immediate worker scan.
+     *
+     * @remarks No-op on API-only replicas.
+     */
+    wake(): Promise<void>;
+}
+
+/** Single channel shared by every run-task wake publisher and worker. */
+declare const RUN_TASK_WAKE_CHANNEL = "run-task:wake";
+/** Small cross-replica wake frame; the durable pending scan remains authority. */
+interface RunTaskWakeFrame {
+    /** Replica that published the wake, used to skip self-delivery. */
+    source: string;
+    /** Publication timestamp for diagnostics only. */
+    at: string;
+}
+/** Payload handler registered on the subscribed Redis channel. */
+type RunTaskWakeRedisMessageHandler = (message: string, channel: string) => void | Promise<void>;
+/**
+ * Minimal Redis pub/sub surface used by {@link RedisRunTaskWake}.
+ *
+ * @remarks Deliberately narrower than the `redis` package client so tests can
+ * inject a deterministic fake without a server. The production adapter relies
+ * on node-redis for reconnects and resubscribes; this interface only exposes
+ * the lifecycle events needed for diagnostics and teardown.
+ */
+interface RunTaskWakeRedisClient {
+    /** Whether the client currently has an open connection. */
+    readonly isOpen: boolean;
+    /** Open the connection (no-op when already open). */
+    connect(): Promise<void>;
+    /** Close the connection; teardown is best-effort. */
+    disconnect(): Promise<void>;
+    /** Publish a payload and return the number of subscribers reached. */
+    publish(channel: string, message: string): Promise<number>;
+    /** Subscribe a handler to a channel. */
+    subscribe(channel: string, listener: RunTaskWakeRedisMessageHandler): Promise<void>;
+    /** Unsubscribe from a channel. */
+    unsubscribe(channel: string): Promise<void>;
+    /** Register a connection lifecycle listener. */
+    on(event: "error" | "end" | "reconnecting" | "ready", listener: (...args: unknown[]) => void): void;
+    /** Abort the socket immediately when supported (optional). */
+    destroy?(): void;
+}
+/** Publish side registered with the process-local wake registry. */
+interface RunTaskWakePublisher {
+    /**
+     * Best-effort cross-replica wake.
+     *
+     * @returns Number of subscriber replicas reached; `0` on transport failure.
+     * @remarks Implementations must never throw: the durable row is already
+     * committed and polling is the fallback.
+     */
+    publish(): Promise<number>;
+}
+/** Point-in-time wake transport posture exposed by {@link RedisRunTaskWake.stats}. */
+interface RunTaskWakeStats {
+    /** Whether the subscriber loop is running. */
+    started: boolean;
+    /** Whether the lazy publisher connection is currently open. */
+    publisherConnected: boolean;
+    /** Whether the subscriber connection is currently open. */
+    subscriberConnected: boolean;
+}
+/** Structured logger used for best-effort transport diagnostics. */
+interface RunTaskWakeLogger {
+    /** Report the first transport problem with context. */
+    warn(message: string, context: Record<string, unknown>): void;
+    /** Report connection recovery after a failure (optional). */
+    info?(message: string, context: Record<string, unknown>): void;
+}
+/** Dependencies required by {@link RedisRunTaskWake}. */
+interface RedisRunTaskWakeDependencies {
+    /** Stable identity of this replica; used to skip self-published frames. */
+    owner: string;
+    /** Wake the local worker; only called by the subscriber path. */
+    wake: () => Promise<void> | void;
+    /** Factory for independent pub/sub connections (publisher is lazy). */
+    clientFactory: () => RunTaskWakeRedisClient;
+    /** Optional structured logger. */
+    logger?: RunTaskWakeLogger;
+    /** Clock seam for the frame timestamp (default `new Date`). */
+    now?: () => Date;
+    /**
+     * Bound for connect/subscribe/publish/teardown operations (default 2000ms).
+     *
+     * @remarks A hung Redis operation must never block gateway startup or
+     * graceful shutdown; polling remains the durable fallback.
+     */
+    operationTimeoutMs?: number;
+    /**
+     * Backoff sequence between background subscription retries.
+     *
+     * @remarks Defaults to 500ms, 2s, 5s, then 10s for every later attempt. Tests
+     * may inject a shorter sequence. Non-positive entries are ignored.
+     */
+    retryDelaysMs?: readonly number[];
+}
+/**
+ * Redis pub/sub wake transport for the durable run task queue.
+ *
+ * @remarks
+ * `publish` lazily owns a publisher connection; every worker replica calls
+ * {@link start} to subscribe and wake its local runtime. API-only replicas may
+ * publish without subscribing. {@link start} schedules the subscription in the
+ * background and resolves immediately, so a hung Redis handshake cannot block
+ * gateway startup. {@link stop} bounds every teardown operation. All Redis
+ * failures are swallowed: the durable pending row and the PostgreSQL poll remain
+ * authoritative, so a lost wake only delays work until the next scan.
+ *
+ * The subscriber ignores frames published by this replica. The registry always
+ * wakes the local runtime directly after publishing, so self-delivery would
+ * only duplicate the same coalesced scan.
+ */
+declare class RedisRunTaskWake implements RunTaskWakePublisher {
+    private readonly owner;
+    private readonly wake;
+    private readonly clientFactory;
+    private readonly logger?;
+    private readonly now;
+    private readonly operationTimeoutMs;
+    private readonly retryDelaysMs;
+    private subscriber?;
+    private subscriberEpoch;
+    private retryAttempt;
+    private retryTimer?;
+    private publisher?;
+    private publisherPromise?;
+    private pendingPublisherClient?;
+    private publisherEpoch;
+    private readonly connectionErrorsReported;
+    private running;
+    /** @param dependencies Replica identity, local wake, and transport factory. */
+    constructor(dependencies: RedisRunTaskWakeDependencies);
+    /**
+     * Returns the wake transport's current connection posture.
+     *
+     * @returns Started flag plus publisher/subscriber connection state.
+     */
+    stats(): RunTaskWakeStats;
+    /**
+     * Publish one wake frame for every worker replica.
+     *
+     * @returns Number of Redis subscribers reached, or `0` on failure.
+     * @remarks Never throws. A failed publisher connection is reset so the next
+     * create can reconnect.
+     */
+    publish(): Promise<number>;
+    /**
+     * Schedule subscription to the shared wake channel.
+     *
+     * @returns A promise that resolves immediately; connection work continues in
+     * the background.
+     * @remarks Idempotent while a subscription is active. A call during a retry
+     * backoff cancels the timer and retries immediately. Connection failures are
+     * retried automatically with capped exponential backoff; startup and request
+     * paths never wait on Redis. Polling remains the durable fallback.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the subscriber and close the transport connections.
+     *
+     * @remarks Idempotent and bounded, so a hung Redis handshake cannot block
+     * graceful shutdown. Pending clients are aborted/destroyed when supported and
+     * every teardown operation has a timeout.
+     */
+    stop(): Promise<void>;
+    private frame;
+    private launchConnect;
+    private connectSubscriber;
+    private scheduleRetry;
+    private clearRetryTimer;
+    private bindSubscriberLifecycle;
+    private getPublisher;
+    private onMessage;
+    private reportConnectionFailure;
+    private reportConnectionRecovered;
+    private closeClient;
+    private warn;
+}
+/** Options for {@link createRedisRunTaskWake}. */
+interface CreateRedisRunTaskWakeOptions extends Omit<RedisRunTaskWakeDependencies, "clientFactory"> {
+    /** Redis connection URL, for example `redis://localhost:6379`. */
+    url: string;
+}
+/**
+ * Create a wake transport backed by real `redis` pub/sub connections.
+ *
+ * @param options Redis URL, replica identity, and local wake callback.
+ * @returns A transport ready for {@link RedisRunTaskWake.publish} / `start`.
+ */
+declare function createRedisRunTaskWake(options: CreateRedisRunTaskWakeOptions): RedisRunTaskWake;
+/**
+ * Create the transport only when a Redis URL is configured.
+ *
+ * @param options Same as {@link createRedisRunTaskWake}, with an optional URL.
+ * @returns The transport, or `undefined` when Redis wake is not configured.
+ * @remarks Without Redis the registry still wakes the local worker, and the
+ * durable PostgreSQL scan remains the fallback for every other replica.
+ */
+declare function createConfiguredRedisRunTaskWake(options: Omit<CreateRedisRunTaskWakeOptions, "url"> & {
+    url?: string;
+}): RedisRunTaskWake | undefined;
+
+/** Structural source of wake transport posture for process metrics. */
+interface RunTaskWakeStatsSource {
+    /** Returns a point-in-time wake posture snapshot. */
+    stats(): RunTaskWakeStats;
+}
+/**
+ * Registers the process-local run task runtime.
+ *
+ * @param runtime The running runtime, or `undefined` on shutdown.
+ * @remarks The registry is intentionally process-local: it can only wake the
+ * worker in this process. Other replicas still discover pending runs through DB
+ * polling, which remains authoritative.
+ */
+declare function setRunTaskRuntime(runtime?: RunTaskRuntime): void;
+/**
+ * Returns the process-local run task runtime, when this replica runs one.
+ *
+ * @returns The registered runtime, or `undefined`.
+ */
+declare function getRunTaskRuntime(): RunTaskRuntime | undefined;
+/**
+ * Registers the best-effort cross-replica wake publisher.
+ *
+ * @param next The Redis-backed publisher, or `undefined` on shutdown.
+ * @remarks API-only replicas may register a publisher without subscribing. A
+ * missing publisher leaves the process-local wake (and DB polling) intact.
+ */
+declare function setRunTaskWakePublisher(next?: RunTaskWakePublisher): void;
+/**
+ * Registers the process-local wake transport used for metrics.
+ *
+ * @param next The wake transport, or `undefined` on shutdown.
+ * @remarks Kept separate from the publish registry so API-only replicas can
+ * expose publisher connection posture even without a local worker.
+ */
+declare function setRunTaskWakeStatsSource(next?: RunTaskWakeStatsSource): void;
+/**
+ * Returns the process-local wake transport registered for metrics.
+ *
+ * @returns The wake stats source, or `undefined` when no Redis wake exists.
+ */
+declare function getRunTaskWakeStatsSource(): RunTaskWakeStatsSource | undefined;
+/**
+ * Best-effort wake for newly created pending runs.
+ *
+ * @returns A promise that resolves after the local wake attempt; the Redis
+ * publish continues in the background.
+ * @remarks Never authoritative and never throws. The local runtime is woken
+ * first so a hung or failed publisher cannot suppress it. The cross-replica
+ * publish is fire-and-forget and wakes other worker replicas; this replica does
+ * not depend on round-tripping its own frame. A missing runtime, missing
+ * publisher, or transport failure leaves the durable run to polling.
+ */
+declare function wakeRunTaskQueue(): Promise<void>;
+
 /**
  * Logger configuration for gateway
  */
@@ -1592,10 +2856,6 @@ interface GatewayLoggerConfig {
 }
 interface LatticeGatewayConfig {
     port?: number;
-    queueServiceConfig?: {
-        type: QueueServiceType;
-        defaultStartPollingQueue: boolean;
-    };
     loggerConfig?: Partial<GatewayLoggerConfig>;
     /**
      * Install SIGTERM/SIGINT graceful-shutdown handlers (default `true`). On a
@@ -1607,6 +2867,8 @@ interface LatticeGatewayConfig {
     gracefulShutdown?: boolean;
     /** Force-exit deadline for graceful shutdown in ms (default 10_000). */
     gracefulShutdownTimeoutMs?: number;
+    /** Optional host startup/shutdown hooks. */
+    lifespans?: GatewayLifespan | GatewayLifespan[];
 }
 declare const LatticeGateway: {
     startAsHttpEndpoint: (config?: LatticeGatewayConfig) => Promise<void>;
@@ -1615,7 +2877,6 @@ declare const LatticeGateway: {
     app: fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault> & PromiseLike<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>> & {
         __linterBrands: "SafePromiseLike";
     };
-    AgentTaskConsumer: typeof AgentTaskConsumer;
 };
 
-export { A2AAuthService, A2A_KEY_CHANGED_TOPIC, type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, MODEL_PROVIDER_CHANGED_TOPIC, ModelProviderService, type ModelProviderServiceDeps, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, type RecoverTaskDeps, type RecoverTaskResult, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createTaskRunLiveness, handleA2AKeyChanged, handleModelProviderChanged, ingestRoomEvent, parseEnvKeys, publishA2AKeyChanged, publishModelProviderChanged, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };
+export { A2AAuthService, A2A_KEY_CHANGED_TOPIC, AGENT_LIFECYCLE_TOPIC, type AgentLifecycleHandlerDeps, type AgentLifecycleTarget, type AgentLifecycleTargetScope, ChunkLogCorruptionError, type CreateRedisRunTaskWakeOptions, DEFAULT_RUN_TASK_JOBS, DEFAULT_RUN_TASK_LEASE_TTL_MS, DEFAULT_RUN_TASK_MAX_ATTEMPTS, DEFAULT_RUN_TASK_SCAN_MS, DEFAULT_THREAD_RUN_LEASE_TTL_MS, type GatewayLifespan, type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type LifespanLogger, MIRRORED_AGENT_EVENTS, MODEL_PROVIDER_CHANGED_TOPIC, ModelProviderService, type ModelProviderServiceDeps, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, RUN_TASK_WAKE_CHANNEL, type RecoverTaskDeps, type RecoverTaskResult, type RedisAppendLogHandle, type RedisAppendLogLogger, type RedisAppendLogOptions, RedisRunTaskWake, type RedisRunTaskWakeDependencies, type RunTaskAgent, RunTaskConcurrencyLimiter, type RunTaskLogger, RunTaskRecovery, type RunTaskRecoveryDependencies, type RunTaskRecoveryStats, RunTaskRuntime, type RunTaskRuntimeDependencies, type RunTaskRuntimeStats, type RunTaskWake, type RunTaskWakeFrame, type RunTaskWakeLogger, type RunTaskWakePublisher, type RunTaskWakeRedisClient, type RunTaskWakeRedisMessageHandler, type RunTaskWakeStats, type RunTaskWakeStatsSource, RunTaskWorker, type RunTaskWorkerDependencies, type RunTaskWorkerStats, createConfiguredRedisRunTaskWake, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createRedisAppendLog, createRedisRunTaskWake, createTaskRunLiveness, getRunTaskRuntime, getRunTaskWakeStatsSource, handleA2AKeyChanged, handleAgentLifecycle, handleModelProviderChanged, ingestRoomEvent, installAgentLifecycleSync, installLifespanHooks, parseEnvKeys, publishA2AKeyChanged, publishAgentLifecycle, publishModelProviderChanged, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery, setRunTaskRuntime, setRunTaskWakePublisher, setRunTaskWakeStatsSource, wakeRunTaskQueue };