@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/runtime/run-jobs.d.ts

@@ -1,6 +1,8 @@
 import type { Job, Queue } from "bullmq";
-import type { ConversationKind } from "../db/kernel-schema.js";
+import type { ConversationKind, KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 /** 内核运行队列的 BullMQ 队列名（不含 `:`；与插件队列 `cap.<插件>.<名>` 不会重名）。 */
 export declare const RUN_QUEUE_NAME = "cap-kernel-runs";
@@ -10,9 +12,23 @@ export declare const RUN_QUEUE_NAME = "cap-kernel-runs";
  */
 export declare const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
 /** The run queue of a conversation kind: sub-agent conversations have their own. */
-export declare const runQueueNameFor: (kind: ConversationKind) => string;
+export declare const runQueueNameFor: (kind: ConversationKind) => typeof RUN_QUEUE_NAME | typeof SUBAGENT_RUN_QUEUE_NAME;
 /** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
 export declare const ACTIVE_RUN_STATUSES: readonly ["queued", "running", "waiting"];
+/** 运行的终态。 */
+export type TerminalStatus = "completed" | "failed" | "aborted";
+/** The terminal run statuses (here, not in `run-finish.ts`, which the sub-agent modules import). */
+export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+/**
+ * Locks a run's approval and input request rows (`FOR UPDATE`, in id order) in the caller's
+ * transaction, after its conversation row and before its run row: the one lock order of every path
+ * that writes them (conversation, decided rows, run; ruling R19), so a stop, a run's end, a decision
+ * and a timeout never deadlock. Returns whether any of them is still pending.
+ */
+export declare function lockWaitRowsIn(t: KernelSchemaDb, runId: string): Promise<{
+    approvals: boolean;
+    questions: boolean;
+}>;
 /** 运行任务的数据。 */
 export interface RunJobData {
     runId: string;
@@ -21,26 +37,92 @@ export interface RunJobData {
 /** 同一触发点（会话 + 最新用户消息 seq）只投递一次。 */
 export declare const runJobId: (conversationId: string, maxUserSeq: number) => string;
 /**
- * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): adds
- * run jobs under the caller's job id and looks them up. The run queue (`ensureRun`, orphan
- * repairs), the waits (resumes) and the sub-agent dispatch enqueue through it; the run worker
- * consumes both queues.
+ * A resumed run's job id: apart from the per-message `run-<conversationId>-<seq>`, and one per
+ * wait, so the same wait resumes its run once.
+ */
+export declare const resumeJobId: (conversationId: string, waitId: string) => string;
+/** The BullMQ job name of every run job, on both run queues (an outbox registry name). */
+export declare const RUN_JOB = "run";
+/**
+ * The ensure-run backstop (transactional outbox spec §6 "Sending a message"): a maintenance job
+ * that calls `RunQueue.ensureRun` for a conversation. Every transaction that may start a run
+ * after its commit (a message, a queue change, a background task's finish, a sub-agent's delivery,
+ * a run's end) owes one, {@link ENSURE_RUN_BACKSTOP_MS} later, and its caller still calls
+ * `ensureRun` right after the commit: the job only matters when that call never happened (the
+ * process died) or failed (Redis was down).
+ */
+export declare const ENSURE_RUN_JOB = "ensure-run";
+/** How long after its transaction the ensure-run backstop fires (a backstop, not a second call). */
+export declare const ENSURE_RUN_BACKSTOP_MS = 30000;
+/** The ensure-run job's data. */
+export interface EnsureRunJobData {
+    conversationId: string;
+}
+/**
+ * The ensure-run job id: one per conversation and the seq of the event the transaction wrote (a
+ * write without an event of its own uses the conversation's newest seq; no `:`).
+ */
+export declare const ensureRunJobId: (conversationId: string, seq: number | string) => string;
+/**
+ * Owes the ensure-run backstop of `conversationId` in the caller's transaction (throws outside
+ * one). False when the same job id is already owed (the owed job does the same).
+ */
+export declare function oweEnsureRun(outbox: Pick<OutboxService, "add">, conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
+/**
+ * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): owes
+ * run jobs in the caller's transaction ({@link owe}: `ensureRun`, the sub-agent dispatch, the
+ * `run-orphan-check`) and looks them up; the run worker consumes both queues.
  */
 export declare class RunJobs {
-    private readonly kdb;
+    private readonly outbox;
     private readonly queues;
-    constructor(kdb: KernelDb, runs: Queue<RunJobData>, subagentRuns: Queue<RunJobData>, log: KernelLogger);
+    constructor(runs: Queue<RunJobData>, subagentRuns: Queue<RunJobData>, log: KernelLogger, outbox: OutboxService);
     /** The BullMQ queue `name` (default: conversation runs). */
     queue(name?: string): Queue<RunJobData>;
     /** A run job by id on the queue `name`, or undefined. */
     getJob(jobId: string, name?: string): Promise<Job<RunJobData> | undefined>;
     /**
-     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
-     * queue follows the conversation's kind (a sub-agent's runs go to
-     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
+     * Owes the run job in the caller's transaction (transactional outbox spec §6): the outbox row
+     * commits or rolls back with the run row, on the queue of the conversation's `kind`. Returns
+     * false when the same job id is already owed (nothing written; the caller creates no run).
      */
-    enqueue(data: RunJobData, jobId: string, kind?: ConversationKind): Promise<void>;
+    owe(data: RunJobData, jobId: string, kind: ConversationKind, orgId: string): Promise<boolean>;
+    /** {@link oweEnsureRun} in the caller's transaction. */
+    oweEnsureRun(conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
 }
-/** The run queues' producer (the sub-agent dispatch, the run queue and the waits use it). */
+/**
+ * What {@link RunResume.resumeIn} found: `queued`, the run was waiting on nothing else and now is
+ * queued with its resume job owed; `still-running`, the run has not reached `waiting` yet (its
+ * suspend's re-check resumes it); `other-wait-pending`, the run still waits on another approval,
+ * input request or fork sub-agent; `not-waiting`, the run is queued or finished (or gone).
+ */
+export type ResumeOutcome = "queued" | "still-running" | "other-wait-pending" | "not-waiting";
+/**
+ * The resume of a waiting run (transactional outbox spec §6 "Resumes and timeouts", "Decisions
+ * resume in their own transaction"), in the caller's transaction. A decision (approvals, questions,
+ * a reply's skips) calls it after writing the decided row, so the lock order is the decided row,
+ * then the `runs` row. It lives beside the run jobs, not in `Waits`, so the tools domain (which the
+ * runtime imports) can call it; `Waits.resume` wraps it in a transaction of its own.
+ */
+export declare class RunResume {
+    private readonly kdb;
+    private readonly outbox;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, outbox: Pick<OutboxService, "add">, txHost: TransactionHost);
+    /**
+     * Locks the run row (`FOR UPDATE`); when it is `waiting` and waits on nothing else (no pending
+     * approval or input request, no active fork sub-agent), sets it `queued` (adding this wait's
+     * time to `waited_ms`, recording the resume job id) and owes the resume job
+     * {@link resumeJobId}`(conversation, waitId)` on its conversation kind's run queue. A `running`
+     * run is left alone: its suspend has not set `waiting` yet and re-checks the wait after.
+     */
+    resumeIn(runId: string, waitId: string): Promise<ResumeOutcome>;
+}
+/**
+ * The run queues' producer (the sub-agent dispatch, the run queue and the waits use it), the
+ * resume of a waiting run (the waits and the decisions of the tools domain use it) and the
+ * lost-jobs canary of the run queues (the `run-orphan-check` reports it, the admin overview reads
+ * it).
+ */
 export declare class RunJobsModule {
 }

package/dist/runtime/run-jobs.js

@@ -9,9 +9,15 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Module } from "@nestjs/common";
+import { sql } from "kysely";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+import { QueueLostJobs } from "./queue-lost-jobs.js";
 /** 内核运行队列的 BullMQ 队列名（不含 `:`；与插件队列 `cap.<插件>.<名>` 不会重名）。 */
 export const RUN_QUEUE_NAME = "cap-kernel-runs";
 /**
@@ -23,21 +29,87 @@ export const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
 export const runQueueNameFor = (kind) => kind === "subagent" ? SUBAGENT_RUN_QUEUE_NAME : RUN_QUEUE_NAME;
 /** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
 export const ACTIVE_RUN_STATUSES = ["queued", "running", "waiting"];
+/** The terminal run statuses (here, not in `run-finish.ts`, which the sub-agent modules import). */
+export const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "aborted",
+]);
+/**
+ * Locks a run's approval and input request rows (`FOR UPDATE`, in id order) in the caller's
+ * transaction, after its conversation row and before its run row: the one lock order of every path
+ * that writes them (conversation, decided rows, run; ruling R19), so a stop, a run's end, a decision
+ * and a timeout never deadlock. Returns whether any of them is still pending.
+ */
+export async function lockWaitRowsIn(t, runId) {
+    const approvals = await t
+        .selectFrom("approvals")
+        .select("status")
+        .where("run_id", "=", runId)
+        .orderBy("id")
+        .forUpdate()
+        .execute();
+    const questions = await t
+        .selectFrom("questions")
+        .select("status")
+        .where("run_id", "=", runId)
+        .orderBy("id")
+        .forUpdate()
+        .execute();
+    return {
+        approvals: approvals.some((r) => r.status === "pending"),
+        questions: questions.some((r) => r.status === "pending"),
+    };
+}
 /** 同一触发点（会话 + 最新用户消息 seq）只投递一次。 */
 export const runJobId = (conversationId, maxUserSeq) => `run-${conversationId}-${maxUserSeq}`;
-/** The options of every run job: one attempt (the run's own paths handle failures), not kept. */
-const RUN_JOB_OPTIONS = { attempts: 1, removeOnComplete: true, removeOnFail: true };
 /**
- * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): adds
- * run jobs under the caller's job id and looks them up. The run queue (`ensureRun`, orphan
- * repairs), the waits (resumes) and the sub-agent dispatch enqueue through it; the run worker
- * consumes both queues.
+ * A resumed run's job id: apart from the per-message `run-<conversationId>-<seq>`, and one per
+ * wait, so the same wait resumes its run once.
+ */
+export const resumeJobId = (conversationId, waitId) => `run-${conversationId}-resume-${waitId}`;
+/** The BullMQ job name of every run job, on both run queues (an outbox registry name). */
+export const RUN_JOB = "run";
+/**
+ * The ensure-run backstop (transactional outbox spec §6 "Sending a message"): a maintenance job
+ * that calls `RunQueue.ensureRun` for a conversation. Every transaction that may start a run
+ * after its commit (a message, a queue change, a background task's finish, a sub-agent's delivery,
+ * a run's end) owes one, {@link ENSURE_RUN_BACKSTOP_MS} later, and its caller still calls
+ * `ensureRun` right after the commit: the job only matters when that call never happened (the
+ * process died) or failed (Redis was down).
+ */
+export const ENSURE_RUN_JOB = "ensure-run";
+/** How long after its transaction the ensure-run backstop fires (a backstop, not a second call). */
+export const ENSURE_RUN_BACKSTOP_MS = 30_000;
+/**
+ * The ensure-run job id: one per conversation and the seq of the event the transaction wrote (a
+ * write without an event of its own uses the conversation's newest seq; no `:`).
+ */
+export const ensureRunJobId = (conversationId, seq) => `ensure-run-${conversationId}-${seq}`;
+/**
+ * Owes the ensure-run backstop of `conversationId` in the caller's transaction (throws outside
+ * one). False when the same job id is already owed (the owed job does the same).
+ */
+export function oweEnsureRun(outbox, conversationId, seq, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: ENSURE_RUN_JOB,
+        jobId: ensureRunJobId(conversationId, seq),
+        data: { conversationId },
+        runAt: new Date(Date.now() + ENSURE_RUN_BACKSTOP_MS),
+        orgId,
+    });
+}
+/**
+ * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): owes
+ * run jobs in the caller's transaction ({@link owe}: `ensureRun`, the sub-agent dispatch, the
+ * `run-orphan-check`) and looks them up; the run worker consumes both queues.
  */
 let RunJobs = class RunJobs {
-    kdb;
+    outbox;
     queues;
-    constructor(kdb, runs, subagentRuns, log) {
-        this.kdb = kdb;
+    constructor(runs, subagentRuns, log, outbox) {
+        this.outbox = outbox;
         this.queues = { [RUN_QUEUE_NAME]: runs, [SUBAGENT_RUN_QUEUE_NAME]: subagentRuns };
         for (const [name, q] of Object.entries(this.queues)) {
             q.on("error", (err) => log.error("run queue error", { err, queue: name }));
@@ -55,39 +127,138 @@ let RunJobs = class RunJobs {
         return this.queue(name).getJob(jobId);
     }
     /**
-     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
-     * queue follows the conversation's kind (a sub-agent's runs go to
-     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
+     * Owes the run job in the caller's transaction (transactional outbox spec §6): the outbox row
+     * commits or rolls back with the run row, on the queue of the conversation's `kind`. Returns
+     * false when the same job id is already owed (nothing written; the caller creates no run).
      */
-    async enqueue(data, jobId, kind) {
-        const k = kind ??
-            (await this.kdb.db
-                .selectFrom("conversations")
-                .select("kind")
-                .where("id", "=", data.conversationId)
-                .executeTakeFirst())?.kind ??
-            "chat";
-        await this.queue(runQueueNameFor(k)).add("run", data, { jobId, ...RUN_JOB_OPTIONS });
+    owe(data, jobId, kind, orgId) {
+        return this.outbox.add({
+            queue: runQueueNameFor(kind),
+            name: RUN_JOB,
+            jobId,
+            data,
+            orgId,
+        });
+    }
+    /** {@link oweEnsureRun} in the caller's transaction. */
+    oweEnsureRun(conversationId, seq, orgId) {
+        return oweEnsureRun(this.outbox, conversationId, seq, orgId);
     }
 };
 RunJobs = __decorate([
     Injectable(),
-    __param(0, Inject(KernelDb)),
-    __param(1, Inject(getQueueToken(RUN_QUEUE_NAME))),
-    __param(2, Inject(getQueueToken(SUBAGENT_RUN_QUEUE_NAME))),
-    __param(3, Inject(KERNEL_LOGGER))
+    __param(0, Inject(getQueueToken(RUN_QUEUE_NAME))),
+    __param(1, Inject(getQueueToken(SUBAGENT_RUN_QUEUE_NAME))),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(OutboxService))
 ], RunJobs);
 export { RunJobs };
+/**
+ * The resume of a waiting run (transactional outbox spec §6 "Resumes and timeouts", "Decisions
+ * resume in their own transaction"), in the caller's transaction. A decision (approvals, questions,
+ * a reply's skips) calls it after writing the decided row, so the lock order is the decided row,
+ * then the `runs` row. It lives beside the run jobs, not in `Waits`, so the tools domain (which the
+ * runtime imports) can call it; `Waits.resume` wraps it in a transaction of its own.
+ */
+let RunResume = class RunResume {
+    kdb;
+    outbox;
+    txHost;
+    constructor(kdb, outbox, txHost) {
+        this.kdb = kdb;
+        this.outbox = outbox;
+        this.txHost = txHost;
+    }
+    /**
+     * Locks the run row (`FOR UPDATE`); when it is `waiting` and waits on nothing else (no pending
+     * approval or input request, no active fork sub-agent), sets it `queued` (adding this wait's
+     * time to `waited_ms`, recording the resume job id) and owes the resume job
+     * {@link resumeJobId}`(conversation, waitId)` on its conversation kind's run queue. A `running`
+     * run is left alone: its suspend has not set `waiting` yet and re-checks the wait after.
+     */
+    async resumeIn(runId, waitId) {
+        const t = this.kdb.db;
+        const run = await t
+            .selectFrom("runs")
+            .select("status")
+            .where("id", "=", runId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (run?.status === "running")
+            return "still-running";
+        if (run?.status !== "waiting")
+            return "not-waiting";
+        const row = await t
+            .updateTable("runs")
+            .set({
+            status: "queued",
+            queued_at: sql `now()`,
+            job_id: sql `'run-' || conversation_id || '-resume-' || ${waitId}::text`,
+            waited_ms: sql `waited_ms + COALESCE(floor(extract(epoch FROM now() - waiting_since) * 1000), 0)::bigint`,
+            waiting_since: null,
+            wait_expires_at: null,
+        })
+            .where("id", "=", runId)
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom("approvals")
+            .select(sql `1`.as("one"))
+            .where("approvals.run_id", "=", runId)
+            .where("approvals.status", "=", "pending"))))
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom("questions")
+            .select(sql `1`.as("one"))
+            .where("questions.run_id", "=", runId)
+            .where("questions.status", "=", "pending"))))
+            // a fork invocation's sub-agent (agent map spec §5.4: background `Agent` children never
+            // hold their parent run) is no longer active
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom("subagent_dispatches as sd")
+            .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
+            .select(sql `1`.as("one"))
+            .where("sd.parent_run_id", "=", runId)
+            .where("sd.for_skill", "=", true)
+            .where("cr.status", "in", ACTIVE_RUN_STATUSES))))
+            .returning("conversation_id")
+            .executeTakeFirst();
+        if (!row)
+            return "other-wait-pending";
+        const conv = await t
+            .selectFrom("conversations")
+            .select(["kind", "org_id"])
+            .where("id", "=", row.conversation_id)
+            .executeTakeFirstOrThrow();
+        await this.outbox.add({
+            queue: runQueueNameFor(conv.kind),
+            name: RUN_JOB,
+            jobId: resumeJobId(row.conversation_id, waitId),
+            data: { runId, conversationId: row.conversation_id },
+            orgId: conv.org_id,
+        });
+        return "queued";
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], RunResume.prototype, "resumeIn", null);
+RunResume = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OutboxService)),
+    __param(2, Inject(TransactionHost))
+], RunResume);
+export { RunResume };
 /** The run queues' registration (re-exported: the admin health reads their counts). */
 const RUN_QUEUES_MODULE = QueueModule.registerQueue(RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME);
-/** The run queues' producer (the sub-agent dispatch, the run queue and the waits use it). */
+/**
+ * The run queues' producer (the sub-agent dispatch, the run queue and the waits use it), the
+ * resume of a waiting run (the waits and the decisions of the tools domain use it) and the
+ * lost-jobs canary of the run queues (the `run-orphan-check` reports it, the admin overview reads
+ * it).
+ */
 let RunJobsModule = class RunJobsModule {
 };
 RunJobsModule = __decorate([
     Module({
         imports: [RUN_QUEUES_MODULE],
-        providers: [RunJobs],
-        exports: [RunJobs, RUN_QUEUES_MODULE],
+        providers: [RunJobs, RunResume, QueueLostJobs],
+        exports: [RunJobs, RunResume, QueueLostJobs, RUN_QUEUES_MODULE],
     })
 ], RunJobsModule);
 export { RunJobsModule };

package/dist/runtime/run-orphan-check.job.d.ts

@@ -0,0 +1,142 @@
+import { EventLog } from "../conversations/event-log.js";
+import type { ConversationKind, KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
+import { ConversationLock } from "./conversation-lock.js";
+import { QueueLostJobs } from "./queue-lost-jobs.js";
+import { RunFinish } from "./run-finish.js";
+import { RunJobs } from "./run-jobs.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+/** The check's `@LockedInterval` job name (its run lock key is the default `cron:run-orphan-check`). */
+export declare const RUN_ORPHAN_CHECK_JOB = "run-orphan-check";
+/** The check's period: a fixed constant, not a config field. */
+export declare const RUN_ORPHAN_CHECK_PERIOD_MS = 60000;
+/**
+ * How long a run must have been in its state (queued, or running since its last start) before it
+ * can count as an orphan: a transition in flight is never repaired.
+ */
+export declare const RUN_ORPHAN_MIN_AGE_MS = 60000;
+/** The candidates one page of a pass reads (a keyset page over the state's start time and id). */
+export declare const RUN_ORPHAN_CHECK_BATCH = 500;
+/**
+ * The most pages one pass reads: a bound on its work. Healthy long runs and queued runs waiting
+ * for a quota slot are passed over page by page, so a real orphan behind them is still reached;
+ * beyond this many candidates the rest wait for the next minute.
+ */
+export declare const RUN_ORPHAN_CHECK_MAX_PAGES = 10;
+/** The error the canary logs (transactional outbox spec §8.3). */
+export declare const QUEUE_LOST_JOBS_MESSAGE = "queued run without a job: the queue lost jobs";
+/** What one pass of {@link RunOrphanCheck.check} repaired. */
+export interface RunOrphanCheckResult {
+    /** `running` runs nobody runs, failed `run.orphaned`. */
+    runningRepaired: number;
+    /** `queued` runs whose job was lost, owed again (each one is the canary). */
+    queuedReadded: number;
+}
+/** An active run that may be an orphan, with where its job lives. */
+export interface OrphanCandidate {
+    runId: string;
+    conversationId: string;
+    orgId: string;
+    kind: ConversationKind;
+    status: "queued" | "running";
+    /** The run's job id (a resume's `runs.job_id`, else its trigger's) and queue. */
+    jobId: string;
+    queue: string;
+    /** When the run entered its state, as PG prints it (compared again in the repair). */
+    since: string;
+}
+/**
+ * One page of the active runs of chat and sub-agent conversations in `statuses` that entered their
+ * state more than `minAgeMs` ago, by (state start, id), after `after` (an eval's hidden
+ * conversation drives its runs itself).
+ */
+export declare function orphanCandidates(db: KernelSchemaDb, statuses: readonly ("queued" | "running")[], minAgeMs: number, limit: number, after?: Pick<OrphanCandidate, "since" | "runId">): Promise<OrphanCandidate[]>;
+/**
+ * Whether the outbox holds the job `jobId` on `queue`: a pending row (it is still owed) or a dead
+ * one (the outbox gave up on it; the super admin sees it under `outbox_dead` and retries or
+ * discards it, so it is not a job the queue lost).
+ */
+export declare function jobInOutbox(db: KernelSchemaDb, queue: string, jobId: string): Promise<boolean>;
+/**
+ * The `queued` runs (in their state for over `minAgeMs`) whose job is neither in the outbox
+ * (owed, or dead) nor in BullMQ (`jobExists`), and that are still queued after both looks: the run
+ * queue lost their jobs. The outbox is read before BullMQ (a row is deleted only after its job was added) and the
+ * run again after both (a job that finished took its run out of `queued` first), so a run in
+ * flight is never reported. The `run-orphan-check` uses it; so does the dual-replica test harness,
+ * which asserts at its teardown that the kernel left none (`minAgeMs` 0).
+ */
+export declare function queuedRunsWithoutJob(db: KernelSchemaDb, jobExists: (queue: string, jobId: string) => Promise<boolean>, opts: {
+    minAgeMs: number;
+}): Promise<OrphanCandidate[]>;
+/**
+ * The `run-orphan-check` (transactional outbox spec §6 "Replica death during a run", §8.3): once a
+ * minute across replicas (worker role), the one repair of a run nobody runs. A run counts when it
+ * has been in its state for over {@link RUN_ORPHAN_MIN_AGE_MS} with neither its BullMQ job nor a
+ * conversation lock holder:
+ * - `running`: its replica died while running it (BullMQ's stalled re-deliveries ran out, or the
+ *   process died inside `onFailed`; run jobs are `attempts: 1, removeOnFail`). It is failed
+ *   `run.orphaned` (its terminal transaction cancels its waits and owes what every run end owes),
+ *   then, after the commit, its checkpoints are dropped, its fork child stopped (`run.orphaned`), a
+ *   sub-agent's failure delivered to its parent at once and the conversation's next run started.
+ * - `queued`, with no outbox row either (pending or dead): a canary. Every queued run has its job owed in its
+ *   own transaction, so this means Redis lost data. It is logged as an error, counted for the admin
+ *   overview ({@link QueueLostJobs}) and its job owed again so the run is not stuck.
+ * Redis is read before each repair's transaction, which then re-reads the run under its
+ * conversation row lock and acts only if it is still in the same state since the same time. Read
+ * paths never repair runs.
+ */
+export declare class RunOrphanCheck {
+    private readonly kdb;
+    private readonly jobs;
+    private readonly lock;
+    private readonly finisher;
+    private readonly eventLog;
+    private readonly checkpoints;
+    /** A failed sub-agent run reports to its parent at once ({@link Waits.childFinished}). */
+    private readonly waits;
+    /** The conversation's next run, after a repaired run's end. */
+    private readonly queue;
+    private readonly lostJobs;
+    private readonly events;
+    readonly txHost: TransactionHost;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(kdb: KernelDb, jobs: Pick<RunJobs, "getJob" | "owe">, lock: Pick<ConversationLock, "holder">, finisher: Pick<RunFinish, "finishIn">, eventLog: Pick<EventLog, "notify" | "publishChanged">, checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, 
+    /** A failed sub-agent run reports to its parent at once ({@link Waits.childFinished}). */
+    waits: Pick<Waits, "childFinished">, 
+    /** The conversation's next run, after a repaired run's end. */
+    queue: Pick<RunQueue, "ensureRun">, lostJobs: Pick<QueueLostJobs, "report">, events: KernelEvents, txHost: TransactionHost, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    private get db();
+    run(): Promise<void>;
+    /** One pass: repairs the orphans it finds (each on its own; a failure is logged). */
+    check(): Promise<RunOrphanCheckResult>;
+    /**
+     * Neither a conversation lock holder nor the run's job in BullMQ (nor, queued, in the outbox: an
+     * owed row is delivered by the relay, a dead one waits for the super admin).
+     */
+    private withoutJobOrHolder;
+    /**
+     * Fails a `running` orphan (`run.orphaned`), then does what its end causes after the commit:
+     * the open pages hear it, its checkpoints go, its fork child stops, a sub-agent reports to its
+     * parent and the conversation's next run starts (each also owed by the terminal transaction).
+     */
+    private failRunning;
+    /** {@link failRunning}'s transaction: the terminal state, if the run is still the same orphan. */
+    private failIn;
+    /** Owes a lost queued run's job again under its own id, if it is still the same orphan. */
+    private oweAgainIn;
+    /**
+     * Under the conversation row lock (the first lock of every path that changes a run's state): the
+     * run is still in the state and since the time the pass read. Not `FOR UPDATE` on the run: the
+     * terminal transaction locks it after the run's wait rows.
+     */
+    private stillIn;
+}