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

package/dist/runtime/queue-lost-jobs.d.ts

@@ -0,0 +1,24 @@
+import type { Redis } from "ioredis";
+/** The Redis hash of the lost-jobs canary: `count` and `lastAt` (ISO). */
+export declare const QUEUE_LOST_JOBS_KEY = "capk:queue-lost-jobs";
+/** How long the canary stays after its last report (then the overview drops it). */
+export declare const QUEUE_LOST_JOBS_TTL_SECONDS: number;
+/** What the admin overview shows: how many run jobs the queue lost, and when it last did. */
+export interface QueueLostJobsSummary {
+    count: number;
+    lastAt: string;
+}
+/**
+ * The "queue lost jobs" canary (transactional outbox spec §8.3): the `run-orphan-check` found
+ * queued runs whose job is neither in BullMQ nor owed by the outbox, which the outbox makes
+ * impossible unless Redis lost data (its durability broke). Each report adds to a count in Redis
+ * that the admin overview shows as an attention item until a week after the last report.
+ */
+export declare class QueueLostJobs {
+    private readonly redis;
+    constructor(redis: Redis);
+    /** Adds `n` lost jobs to the canary (no-op for 0). */
+    report(n: number): Promise<void>;
+    /** The canary, or null when no job was lost in the last week. */
+    summary(): Promise<QueueLostJobsSummary | null>;
+}

package/dist/runtime/queue-lost-jobs.js

@@ -0,0 +1,51 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { REDIS } from "../infra/tokens.js";
+/** The Redis hash of the lost-jobs canary: `count` and `lastAt` (ISO). */
+export const QUEUE_LOST_JOBS_KEY = "capk:queue-lost-jobs";
+/** How long the canary stays after its last report (then the overview drops it). */
+export const QUEUE_LOST_JOBS_TTL_SECONDS = 7 * 24 * 3600;
+/**
+ * The "queue lost jobs" canary (transactional outbox spec §8.3): the `run-orphan-check` found
+ * queued runs whose job is neither in BullMQ nor owed by the outbox, which the outbox makes
+ * impossible unless Redis lost data (its durability broke). Each report adds to a count in Redis
+ * that the admin overview shows as an attention item until a week after the last report.
+ */
+let QueueLostJobs = class QueueLostJobs {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    /** Adds `n` lost jobs to the canary (no-op for 0). */
+    async report(n) {
+        if (n <= 0)
+            return;
+        await this.redis
+            .multi()
+            .hincrby(QUEUE_LOST_JOBS_KEY, "count", n)
+            .hset(QUEUE_LOST_JOBS_KEY, "lastAt", new Date().toISOString())
+            .expire(QUEUE_LOST_JOBS_KEY, QUEUE_LOST_JOBS_TTL_SECONDS)
+            .exec();
+    }
+    /** The canary, or null when no job was lost in the last week. */
+    async summary() {
+        const h = await this.redis.hgetall(QUEUE_LOST_JOBS_KEY);
+        const count = Number(h.count ?? 0);
+        if (!(count > 0) || h.lastAt === undefined)
+            return null;
+        return { count, lastAt: h.lastAt };
+    }
+};
+QueueLostJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS))
+], QueueLostJobs);
+export { QueueLostJobs };

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

@@ -1,6 +1,7 @@
-import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { RunAbort } from "./abort.js";
+import { type ResumeOutcome, RunResume } from "./run-jobs.js";
 import { RunQueue } from "./run-queue.js";
 import { Waits } from "./waits.js";
 /**
@@ -11,23 +12,64 @@ export declare class RunControl {
     private readonly queue;
     private readonly waits;
     private readonly abort;
-    private readonly events;
+    /** The resume of a waiting run in a decision's transaction (a reply's skips). */
+    private readonly resumes;
+    /** Owes a deleted root's tree stop in the delete's transaction. */
+    private readonly outbox;
     private readonly log;
-    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned" | "wakeHeldTree">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
+    constructor(queue: Pick<RunQueue, "ensureRun" | "oweEnsureRun" | "abortIfOrphaned" | "abortQueued" | "wakeHeldTree" | "oweHeldTreeIn">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, 
+    /** The resume of a waiting run in a decision's transaction (a reply's skips). */
+    resumes: Pick<RunResume, "resumeIn">, 
+    /** Owes a deleted root's tree stop in the delete's transaction. */
+    outbox: Pick<OutboxService, "add">, log: Pick<KernelLogger, "error">);
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId: string): Promise<string | null>;
+    /**
+     * The direct `ensureRun` right after a commit that owes the ensure-run backstop (a message, a
+     * queue change): a failure (Redis unreachable) is logged and never thrown, since the committed
+     * write is not undone and the backstop starts the run later (transactional outbox spec §6).
+     */
+    ensureRunAfterCommit(conversationId: string): Promise<void>;
+    /**
+     * Owes the ensure-run backstop in the caller's transaction (transactional outbox spec §6): `seq`
+     * is the event it wrote (or the conversation's newest), `orgId` the conversation's.
+     */
+    oweEnsureRun(conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
     /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
     wakeHeldTree(rootId: string): Promise<void>;
+    /**
+     * Owes, in the transaction that may release a root's hold (an unpause, a "send now"), the
+     * ensure-run backstop of every sub-agent the hold kept waiting ({@link RunQueue.oweHeldTreeIn});
+     * the caller's {@link wakeHeldTree} after the commit is the direct call.
+     */
+    oweHeldTreeIn(rootId: string): Promise<void>;
+    /**
+     * In the caller's transaction, after it locked the decided rows (lock order: conversations,
+     * decided rows, runs): resumes the waiting run `runId` when it waits on nothing else
+     * ({@link RunResume.resumeIn}).
+     */
+    resumeIn(runId: string, waitId: string): Promise<ResumeOutcome>;
+    /**
+     * Owes, in a root's delete transaction, the stop of its whole sub-agent tree (`stop-tree`,
+     * transactional outbox spec §6); the caller's {@link stopTree} after the commit is the direct
+     * call.
+     */
+    oweStopDeletedTree(conversationId: string, byAccountId: string | null, orgId: string): Promise<boolean>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
      * stops its children (sub-agents spec §12).
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * Ends a run still `queued` in PG ({@link RunQueue.abortQueued}; the caller wrote the stop marker
+     * first): true when it did. A stopped sub-agent then reports to its parent at once.
+     */
+    abortQueued(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
-     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
-     * changed: `run.wait-stopped` lets the channel outbound update them.
+     * 运行已不是 waiting（例如刚被续跑）→ false. The stop's transaction owes the IM delivery that
+     * updates its approval / question cards (its appends, transactional outbox spec §8.1).
      */
     abortWaiting(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
     /**

package/dist/runtime/run-control.js

@@ -8,10 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable } from "@nestjs/common";
-import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { RunAbort } from "./abort.js";
+import { RunResume } from "./run-jobs.js";
 import { RunQueue } from "./run-queue.js";
+import { oweStopDeletedTree } from "./subagents/tree-jobs.js";
 import { Waits } from "./waits.js";
 /**
  * Starting and stopping runs from outside the run worker: the conversations API (a message, a
@@ -21,23 +23,76 @@ let RunControl = class RunControl {
     queue;
     waits;
     abort;
-    events;
+    resumes;
+    outbox;
     log;
-    constructor(queue, waits, abort, events, log) {
+    constructor(queue, waits, abort, 
+    /** The resume of a waiting run in a decision's transaction (a reply's skips). */
+    resumes, 
+    /** Owes a deleted root's tree stop in the delete's transaction. */
+    outbox, log) {
         this.queue = queue;
         this.waits = waits;
         this.abort = abort;
-        this.events = events;
+        this.resumes = resumes;
+        this.outbox = outbox;
         this.log = log;
     }
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId) {
         return this.queue.ensureRun(conversationId);
     }
+    /**
+     * The direct `ensureRun` right after a commit that owes the ensure-run backstop (a message, a
+     * queue change): a failure (Redis unreachable) is logged and never thrown, since the committed
+     * write is not undone and the backstop starts the run later (transactional outbox spec §6).
+     */
+    async ensureRunAfterCommit(conversationId) {
+        try {
+            await this.queue.ensureRun(conversationId);
+        }
+        catch (err) {
+            this.log.error("cannot start the conversation's run now; the ensure-run backstop will", {
+                conversationId,
+                err,
+            });
+        }
+    }
+    /**
+     * Owes the ensure-run backstop in the caller's transaction (transactional outbox spec §6): `seq`
+     * is the event it wrote (or the conversation's newest), `orgId` the conversation's.
+     */
+    oweEnsureRun(conversationId, seq, orgId) {
+        return this.queue.oweEnsureRun(conversationId, seq, orgId);
+    }
     /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
     wakeHeldTree(rootId) {
         return this.queue.wakeHeldTree(rootId);
     }
+    /**
+     * Owes, in the transaction that may release a root's hold (an unpause, a "send now"), the
+     * ensure-run backstop of every sub-agent the hold kept waiting ({@link RunQueue.oweHeldTreeIn});
+     * the caller's {@link wakeHeldTree} after the commit is the direct call.
+     */
+    oweHeldTreeIn(rootId) {
+        return this.queue.oweHeldTreeIn(rootId);
+    }
+    /**
+     * In the caller's transaction, after it locked the decided rows (lock order: conversations,
+     * decided rows, runs): resumes the waiting run `runId` when it waits on nothing else
+     * ({@link RunResume.resumeIn}).
+     */
+    resumeIn(runId, waitId) {
+        return this.resumes.resumeIn(runId, waitId);
+    }
+    /**
+     * Owes, in a root's delete transaction, the stop of its whole sub-agent tree (`stop-tree`,
+     * transactional outbox spec §6); the caller's {@link stopTree} after the commit is the direct
+     * call.
+     */
+    oweStopDeletedTree(conversationId, byAccountId, orgId) {
+        return oweStopDeletedTree(this.outbox, conversationId, byAccountId, orgId);
+    }
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
@@ -56,15 +111,26 @@ let RunControl = class RunControl {
         return r;
     }
     /**
-     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
-     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
-     * changed: `run.wait-stopped` lets the channel outbound update them.
+     * Ends a run still `queued` in PG ({@link RunQueue.abortQueued}; the caller wrote the stop marker
+     * first): true when it did. A stopped sub-agent then reports to its parent at once.
      */
-    async abortWaiting(conversationId, runId, byAccountId) {
-        const r = await this.waits.abortWaiting(conversationId, runId, byAccountId);
-        await this.events.emit("run.wait-stopped", { conversationId, runId });
+    async abortQueued(conversationId, runId, byAccountId) {
+        const r = await this.queue.abortQueued(conversationId, runId, byAccountId);
+        if (r) {
+            await this.waits
+                .childFinished(runId)
+                .catch((err) => this.log.error("cannot report finished sub-agent run to its parent", { runId, err }));
+        }
         return r;
     }
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false. The stop's transaction owes the IM delivery that
+     * updates its approval / question cards (its appends, transactional outbox spec §8.1).
+     */
+    abortWaiting(conversationId, runId, byAccountId) {
+        return this.waits.abortWaiting(conversationId, runId, byAccountId);
+    }
     /**
      * Stops a sub-agent with its descendants, or with `includeSelf: false` only the sub-agent
      * conversations below `conversationId` (agent map spec §6; {@link Waits.stopTree}). Returns
@@ -83,7 +149,8 @@ RunControl = __decorate([
     __param(0, Inject(RunQueue)),
     __param(1, Inject(Waits)),
     __param(2, Inject(RunAbort)),
-    __param(3, Inject(KernelEvents)),
-    __param(4, Inject(KERNEL_LOGGER))
+    __param(3, Inject(RunResume)),
+    __param(4, Inject(OutboxService)),
+    __param(5, Inject(KERNEL_LOGGER))
 ], RunControl);
 export { RunControl };

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

@@ -1,10 +1,11 @@
 import { type AppendEvent, EventLog } from "../conversations/event-log.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 { ScheduledTaskRunTracker } from "../schedules/run-tracker.js";
-/** 运行的终态。 */
-export type TerminalStatus = "completed" | "failed" | "aborted";
-export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+import { ApprovalsService } from "../tools/approvals.service.js";
+import { QuestionsService } from "../tools/questions.service.js";
+import { type TerminalStatus } from "./run-jobs.js";
 export interface FinishRunArgs {
     conversationId: string;
     runId: string;
@@ -18,15 +19,10 @@ export interface FinishRunArgs {
      * 超时（max_duration）传 false：loop 没吸收的消息没有被回复，必须留给下一轮（R34）。
      */
     floorToTrigger?: boolean;
-    /**
-     * Runs in the transaction once the run is known not to be terminal, before the terminal event:
-     * a parent's open `Agent` calls get their results here (sub-agents spec §12, review m1).
-     */
-    beforeTerminal?: () => Promise<void>;
 }
 /**
- * Writes runs' terminal states (one instance; the run worker, the run queue's orphan repairs, the
- * waits and the eval replays finish runs through it).
+ * Writes runs' terminal states (one instance; the run worker, the run queue's orphan abort, the
+ * `run-orphan-check`, the waits and the eval replays finish runs through it).
  */
 export declare class RunFinish {
     private readonly kdb;
@@ -34,20 +30,51 @@ export declare class RunFinish {
     readonly txHost: TransactionHost;
     /** A scheduled task's run follows its kernel run's end in the same transaction (spec §6). */
     private readonly taskRuns;
+    /** The run's end owes the conversation's ensure-run backstop (transactional outbox spec §6). */
+    private readonly outbox;
+    /** A finished run's pending approvals are cancelled in its terminal transaction. */
+    private readonly approvals;
+    /** ... and its pending input requests. */
+    private readonly questions;
     constructor(kdb: KernelDb, eventLog: EventLog, txHost: TransactionHost, 
     /** A scheduled task's run follows its kernel run's end in the same transaction (spec §6). */
-    taskRuns: Pick<ScheduledTaskRunTracker, "onRunFinished">);
+    taskRuns: Pick<ScheduledTaskRunTracker, "onRunFinished">, 
+    /** The run's end owes the conversation's ensure-run backstop (transactional outbox spec §6). */
+    outbox: Pick<OutboxService, "add">, 
+    /** A finished run's pending approvals are cancelled in its terminal transaction. */
+    approvals: Pick<ApprovalsService, "cancelPendingIn">, 
+    /** ... and its pending input requests. */
+    questions: Pick<QuestionsService, "cancelPendingIn">);
     /**
      * 在调用方的事务内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
+     * It also owes the conversation's ensure-run backstop under the terminal event's seq.
+     *
+     * A finished run waits on nothing: its pending approvals and input requests (one asked just
+     * before the run failed, while it was still `running`) are cancelled before its terminal event
+     * (`approval_decided` / `question_answered` with `cancelled`). Lock order, as every path that
+     * writes them: the conversation row, the run's approval and input request rows, the run row.
+     *
+     * Sub-agents (transactional outbox spec §6): before the terminal event the run's open fork
+     * invocation gets its report (`pairStoppedForks`; an `Agent` call has its result from its
+     * dispatch), so no terminal path leaves an open call. After it, the stops and the delivery the
+     * run's end causes are owed here (runtime/subagents/tree-jobs.ts), the caller still doing them
+     * right after its commit: `stop-tree` when an active fork child remains or a sub-agent run a
+     * person stopped has sub-agents below it, `deliver-to-parent` for a sub-agent's run. The
+     * delivery is a job, not written here: this transaction holds the child's conversation and run
+     * rows, and the parent's conversation row comes first in the dispatch's lock order (parent
+     * conversation, parent run, budget run, child conversation).
      * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
      *
      * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
      * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
      * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
-     * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
+     * Lock order as `RunQueue.ensureRun` and the decisions take it: the conversation row, the run's
+     * approval and input request rows, the run row; they never deadlock with each other.
      * 调用方在提交后对非 null 的返回值调用 {@link notifyFinished}。
      */
     finishIn(a: FinishRunArgs): Promise<number | null>;
+    /** {@link finishIn}'s owed stops and delivery of a run's sub-agent tree. */
+    private oweTreeWork;
     /** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishIn}。 */
     finish(a: FinishRunArgs): Promise<number | null>;
     private finishOwn;

package/dist/runtime/run-finish.js

@@ -14,47 +14,78 @@ import { pauseQueueIn } from "../conversations/queue.js";
 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 { ScheduledTaskRunTracker } from "../schedules/run-tracker.js";
-export const TERMINAL_STATUSES = new Set([
-    "completed",
-    "failed",
-    "aborted",
-]);
+import { ApprovalsService } from "../tools/approvals.service.js";
+import { QuestionsService } from "../tools/questions.service.js";
+import { ACTIVE_RUN_STATUSES, lockWaitRowsIn, oweEnsureRun, TERMINAL_STATUSES, } from "./run-jobs.js";
+import { pairStoppedForks } from "./subagents/skill-fork.js";
+import { oweDeliverToParent, oweStopChildren } from "./subagents/tree-jobs.js";
 /**
- * Writes runs' terminal states (one instance; the run worker, the run queue's orphan repairs, the
- * waits and the eval replays finish runs through it).
+ * Writes runs' terminal states (one instance; the run worker, the run queue's orphan abort, the
+ * `run-orphan-check`, the waits and the eval replays finish runs through it).
  */
 let RunFinish = class RunFinish {
     kdb;
     eventLog;
     txHost;
     taskRuns;
+    outbox;
+    approvals;
+    questions;
     constructor(kdb, eventLog, txHost, 
     /** A scheduled task's run follows its kernel run's end in the same transaction (spec §6). */
-    taskRuns) {
+    taskRuns, 
+    /** The run's end owes the conversation's ensure-run backstop (transactional outbox spec §6). */
+    outbox, 
+    /** A finished run's pending approvals are cancelled in its terminal transaction. */
+    approvals, 
+    /** ... and its pending input requests. */
+    questions) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.txHost = txHost;
         this.taskRuns = taskRuns;
+        this.outbox = outbox;
+        this.approvals = approvals;
+        this.questions = questions;
     }
     /**
      * 在调用方的事务内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
+     * It also owes the conversation's ensure-run backstop under the terminal event's seq.
+     *
+     * A finished run waits on nothing: its pending approvals and input requests (one asked just
+     * before the run failed, while it was still `running`) are cancelled before its terminal event
+     * (`approval_decided` / `question_answered` with `cancelled`). Lock order, as every path that
+     * writes them: the conversation row, the run's approval and input request rows, the run row.
+     *
+     * Sub-agents (transactional outbox spec §6): before the terminal event the run's open fork
+     * invocation gets its report (`pairStoppedForks`; an `Agent` call has its result from its
+     * dispatch), so no terminal path leaves an open call. After it, the stops and the delivery the
+     * run's end causes are owed here (runtime/subagents/tree-jobs.ts), the caller still doing them
+     * right after its commit: `stop-tree` when an active fork child remains or a sub-agent run a
+     * person stopped has sub-agents below it, `deliver-to-parent` for a sub-agent's run. The
+     * delivery is a job, not written here: this transaction holds the child's conversation and run
+     * rows, and the parent's conversation row comes first in the dispatch's lock order (parent
+     * conversation, parent run, budget run, child conversation).
      * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
      *
      * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
      * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
      * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
-     * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
+     * Lock order as `RunQueue.ensureRun` and the decisions take it: the conversation row, the run's
+     * approval and input request rows, the run row; they never deadlock with each other.
      * 调用方在提交后对非 null 的返回值调用 {@link notifyFinished}。
      */
     async finishIn(a) {
         const t = this.kdb.db;
-        await t
+        const conv = await t
             .selectFrom("conversations")
-            .select("id")
+            .select(["kind", "org_id"])
             .where("id", "=", a.conversationId)
             .forUpdate()
             .executeTakeFirst();
+        const pending = await lockWaitRowsIn(t, a.runId);
         const run = await t
             .selectFrom("runs")
             .select("status")
@@ -63,7 +94,11 @@ let RunFinish = class RunFinish {
             .executeTakeFirst();
         if (!run || TERMINAL_STATUSES.has(run.status))
             return null;
-        await a.beforeTerminal?.();
+        if (pending.approvals)
+            await this.approvals.cancelPendingIn(a.runId);
+        if (pending.questions)
+            await this.questions.cancelPendingIn(a.runId);
+        await pairStoppedForks(t, this.eventLog, a.runId);
         const [ev] = await this.eventLog.appendIn(a.conversationId, [
             { ...a.event, runId: a.runId, idemKey: `${a.event.type}:${a.runId}` },
         ]);
@@ -85,7 +120,42 @@ let RunFinish = class RunFinish {
         // a failed or stopped run pauses the queued messages until the person resumes (spec §5.7)
         if (a.status !== "completed")
             await pauseQueueIn(t, a.conversationId);
-        return ev.seq;
+        const seq = ev.seq;
+        // what arrived during the run starts the next one after the commit (the run worker's post-job
+        // ensureRun); owed here too, for when that never happens (an eval's hidden conversation never
+        // starts runs)
+        if (conv && (conv.kind === "chat" || conv.kind === "subagent")) {
+            await oweEnsureRun(this.outbox, a.conversationId, seq, conv.org_id);
+        }
+        if (conv)
+            await this.oweTreeWork(a, conv.kind, conv.org_id);
+        return seq;
+    }
+    /** {@link finishIn}'s owed stops and delivery of a run's sub-agent tree. */
+    async oweTreeWork(a, kind, orgId) {
+        const t = this.kdb.db;
+        if (kind === "subagent")
+            await oweDeliverToParent(this.outbox, a.runId, orgId);
+        const forkChild = await t
+            .selectFrom("subagent_dispatches as sd")
+            .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
+            .select("sd.child_run_id")
+            .where("sd.parent_run_id", "=", a.runId)
+            .where("sd.for_skill", "=", true)
+            .where("cr.status", "in", ACTIVE_RUN_STATUSES)
+            .limit(1)
+            .executeTakeFirst();
+        const stoppedWithChildren = kind === "subagent" &&
+            personStopped(a.event) &&
+            (await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("parent_conversation_id", "=", a.conversationId)
+                .where("kind", "=", "subagent")
+                .limit(1)
+                .executeTakeFirst()) !== undefined;
+        if (forkChild || stoppedWithChildren)
+            await oweStopChildren(this.outbox, a.runId, orgId);
     }
     /** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishIn}。 */
     async finish(a) {
@@ -109,9 +179,22 @@ RunFinish = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(EventLog)),
     __param(2, Inject(TransactionHost)),
-    __param(3, Inject(ScheduledTaskRunTracker))
+    __param(3, Inject(ScheduledTaskRunTracker)),
+    __param(4, Inject(OutboxService)),
+    __param(5, Inject(ApprovalsService)),
+    __param(6, Inject(QuestionsService))
 ], RunFinish);
 export { RunFinish };
+/**
+ * A `run_aborted` a person caused (an account and no `detail`): a sub-agent run stopped that way
+ * stops its descendants (`Waits.stopDescendantsOfStopped`, agent map spec §6).
+ */
+function personStopped(event) {
+    if (event.type !== "run_aborted")
+        return false;
+    const p = event.payload;
+    return typeof p?.byAccountId === "string" && p.detail === undefined;
+}
 /** The message of a `run_failed` event's error, for the task run (undefined otherwise). */
 function failureMessage(event) {
     if (event.type !== "run_failed")