@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/runtime/run-worker.js

@@ -1,24 +1,52 @@
-import { hostname } from "node:os";
-import { DelayedError, Worker } from "bullmq";
+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, Optional } from "@nestjs/common";
+import { DelayedError } from "bullmq";
 import { sql } from "kysely";
-import { normalizeStoredDefinition } from "../agents/definition.js";
+import { EventLog } from "../conversations/event-log.js";
+import { isAbsorbable, } from "../conversations/events.js";
 import { effectiveDefinition, NO_SELECTION, readSelection, sameModel, sameSelection, } from "../conversations/selection.js";
+import { TitleQueue } from "../conversations/titles.js";
 import { ApiError } from "../errors.js";
-import { pinnedFailureText, recordSkillsCatalog } from "../skills/catalog.js";
+import { SettingsService } from "../identity/settings.js";
+import { waitWithin } from "../infra/close-within.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 { Transactional } from "../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
+import { pinnedFailureText, SkillsCatalogService } from "../skills/catalog.js";
+import { normalizeStoredDefinitionIn } from "../tools/legacy-data.js";
+import { ToolPipeline } from "../tools/pipeline.js";
+import { RunAbort } from "./abort.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
+import { ConversationLock } from "./conversation-lock.js";
 import { RunError } from "./model-call.js";
-import { ProviderListError } from "./providers.js";
-import { ORG_QUOTA_LEASE_MS, orgRunLimit } from "./quota.js";
-import { finishRun, TERMINAL_STATUSES } from "./run-finish.js";
-import { bullConnection, RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME, } from "./run-queue.js";
-import { dispatchOfChildRun } from "./subagents/child.js";
+import { ProviderListError, ProviderRegistry } from "./providers.js";
+import { ORG_QUOTA_LEASE_MS, orgRunLimit, RUN_QUOTA } from "./quota.js";
+import { RunContextService } from "./run-context.service.js";
+import { RunDrafts, streamSink } from "./run-drafts.js";
+import { RunFinish, TERMINAL_STATUSES } from "./run-finish.js";
+import { RunQueue } from "./run-queue.js";
+import { AgentLoops, RunSteps } from "./run-steps.js";
+import { dispatchOfChildRun, rootConversationOf } from "./subagents/child.js";
 import { childRunDefinition } from "./subagents/definition.js";
 import { forkBoundary } from "./subagents/skill-fork.js";
+import { Waits } from "./waits.js";
 /** 会话锁被占用时任务延后的时间。 */
 const LOCK_BUSY_DELAY_MS = 1000;
 /** 组织配额已满时任务延后的时间。 */
 const QUOTA_FULL_DELAY_MS = 2000;
 /** BullMQ stalled 检测允许的最大次数（超过则任务失败）。 */
-const MAX_STALLED_COUNT = 3;
+export const MAX_STALLED_COUNT = 3;
 /** 停机时等待任务结束后处理（ensureRun 等）的最短时间。 */
 const FOLLOW_UP_MIN_WAIT_MS = 250;
 /** 读插话的分页大小。 */
@@ -28,88 +56,176 @@ const READ_PAGE = 500;
  * 后续处理，由 close() 跟踪并限时；全部失败也不会让会话永远卡住——打开 SSE / 读事件时会再次 ensureRun。
  */
 const ENSURE_RETRY_DELAYS_MS = [200, 1000, 3000];
-const noopSink = () => { };
+/** Optional provider: the run worker's {@link RunHooks} (tests). */
+export const RUN_HOOKS = Symbol("RUN_HOOKS");
 /** 任务回到队列：延后 delayMs 再处理（不计入 attempts）。 */
 async function requeue(job, token, delayMs) {
     await job.moveToDelayed(Date.now() + delayMs, token);
     throw new DelayedError();
 }
 /**
- * 运行 worker（只在含 `worker` 角色的进程启动）：领取 `cap-kernel-runs` 的任务，取会话锁与组织配额，
- * 调用 AgentLoop，按结果写终态事件并推进 `consumed_seq`；结束后再调用一次 `ensureRun` 处理
- * 运行期间到达但没被吸收的消息（Review Focus 2）。
+ * 运行 worker（只在含 `worker` 角色的进程消费）：领取 `cap-kernel-runs` 与 `cap-kernel-subagent-runs` 的任务
+ * （两个 `@Processor`，见 run-processors.ts），取会话锁与组织配额，调用 AgentLoop，按结果写终态事件并推进
+ * `consumed_seq`；结束后再调用一次 `ensureRun` 处理运行期间到达但没被吸收的消息（Review Focus 2）。
  */
-export class RunWorker {
-    d;
-    /** One BullMQ worker per run queue: conversation runs and sub-agent runs (spec §7.4). */
+let RunWorker = class RunWorker {
+    kdb;
+    eventLog;
+    lock;
+    quota;
+    abort;
+    queue;
+    settings;
+    config;
+    log;
+    bus;
+    checkpoints;
+    waits;
+    events;
+    titles;
+    models;
+    skillsCatalog;
+    runContext;
+    pipeline;
+    finisher;
+    txHost;
+    drafts;
+    hooks;
+    /** The two run queues' BullMQ workers (spec §7.4), once {@link start}ed on the worker role. */
     workers = [];
-    /** 传给 Worker 的连接：BullMQ 不关闭调用方传入的连接，close() 时自己关。 */
-    conn;
     active = new Map();
     /** 进行中的「任务结束后」处理（完成后的 ensureRun、失败标记）：停机时等它们做完再关闭队列。 */
     followUps = new Set();
     closing = false;
     /** close() 开始时触发：ensureRun 重试不再等待退避间隔。 */
     closingSignal = new AbortController();
-    constructor(d) {
-        this.d = d;
+    loop;
+    constructor(kdb, eventLog, lock, quota, abort, queue, settings, loops, steps, config, log, bus, 
+    /** 运行到达终态后删除该运行（thread_id = runId）的 checkpoint thread（只用于续跑，结束后无用）。 */
+    checkpoints, 
+    /** loop 返回 `suspended` 后把运行置为 waiting（释放会话锁与配额之后）; the child lifecycle. */
+    waits, 
+    /** `run.started` (the channel outbound enqueues the conversation's IM delivery). */
+    events, 
+    /** A completed run enqueues the conversation's title job. */
+    titles, 
+    /** Resolves a switched-to model at run start (fallback when it is gone; UI refresh B). */
+    models, 
+    /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
+    skillsCatalog, 
+    /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
+    runContext, 
+    /**
+     * In the terminal transaction of every run: writes its open `Agent` call results
+     * (`stopOpenAgentCalls`; a no-op without dispatches); `fire` runs their observe hooks after the
+     * commit (sub-agents spec §12, review m1: a failed or stalled parent too).
+     */
+    pipeline, finisher, txHost, 
+    /** The steps' live drafts this process writes for the runs it executes. */
+    drafts, hooks) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.lock = lock;
+        this.quota = quota;
+        this.abort = abort;
+        this.queue = queue;
+        this.settings = settings;
+        this.config = config;
+        this.log = log;
+        this.bus = bus;
+        this.checkpoints = checkpoints;
+        this.waits = waits;
+        this.events = events;
+        this.titles = titles;
+        this.models = models;
+        this.skillsCatalog = skillsCatalog;
+        this.runContext = runContext;
+        this.pipeline = pipeline;
+        this.finisher = finisher;
+        this.txHost = txHost;
+        this.drafts = drafts;
+        this.hooks = hooks;
+        this.loop = loops.create(steps.deps);
+    }
+    get db() {
+        return this.kdb.db;
     }
-    start() {
-        if (this.workers.length > 0)
+    /**
+     * Starts consuming (worker role only): `workers` are the `@Processor` workers of both run queues
+     * (built with `runtime.workerConcurrency`, `jobLockMs`, `stalledIntervalMs`; never autorun).
+     */
+    start(workers) {
+        if (this.workers.length > 0 || this.closing)
             return;
-        const runtime = this.d.config().runtime;
-        this.conn = bullConnection(this.d.redisUrl, this.d.log);
-        for (const queue of [RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME]) {
-            const worker = new Worker(queue, (job, token) => this.process(job, token), {
-                // the worker name is recorded on the job (BullMQ processedBy): which replica ran it
-                name: `${hostname()}-${process.pid}`,
-                connection: this.conn,
-                concurrency: runtime.workerConcurrency,
-                lockDuration: runtime.jobLockMs,
-                stalledInterval: runtime.stalledIntervalMs,
-                maxStalledCount: MAX_STALLED_COUNT,
-            });
-            // ensureRun after a run goes after its job completed and left the queue: when the latest
-            // unconsumed message is this run's own trigger (e.g. a run ended by its deadline without
-            // absorbing it, R34), the new job has this job's id and would be dropped as a duplicate
-            // while this one is still active. Relies on BullMQ moving the job to completed (deleted by
-            // removeOnComplete) before emitting "completed" (pinned by the R34 test).
-            worker.on("completed", (job, result) => {
-                if (result !== "ensure")
-                    return;
-                const { conversationId, runId } = job.data;
-                this.track(this.ensureAfterRun(conversationId, runId));
-            });
-            worker.on("error", (err) => this.d.log.error("run worker error", { err, queue }));
-            worker.on("failed", (job, err) => {
-                this.d.log.error("run job failed", { jobId: job?.id, runId: job?.data.runId, err });
-                if (job) {
-                    this.track(this.onJobFailed(job.data, err).catch((e) => this.d.log.error("cannot mark failed run job", { runId: job.data.runId, err: e })));
-                }
-            });
-            this.workers.push(worker);
+        this.workers = workers;
+        for (const w of workers) {
+            void w.run().catch((err) => this.onError(err, w.name));
         }
     }
-    /** Stops the active children of a finished run (see {@link RunWorkerDeps.stopChildren}). */
-    async stopChildren(runId) {
-        if (!this.d.stopChildren)
+    /** A worker's `error` event. */
+    onError(err, queue) {
+        this.log.error("run worker error", { err, queue });
+    }
+    /**
+     * A job completed (the worker's `completed` event). ensureRun after a run goes after its job
+     * completed and left the queue: when the latest unconsumed message is this run's own trigger
+     * (e.g. a run ended by its deadline without absorbing it, R34), the new job has this job's id
+     * and would be dropped as a duplicate while this one is still active. Relies on BullMQ moving
+     * the job to completed (deleted by removeOnComplete) before emitting "completed" (pinned by the
+     * R34 test).
+     */
+    onCompleted(job, result) {
+        if (result !== "ensure")
             return;
+        const { conversationId, runId } = job.data;
+        this.track(this.ensureAfterRun(conversationId, runId));
+    }
+    /** A job failed (the worker's `failed` event). */
+    onFailed(job, err) {
+        this.log.error("run job failed", { jobId: job?.id, runId: job?.data.runId, err });
+        if (job) {
+            this.track(this.onJobFailed(job.data, err).catch((e) => this.log.error("cannot mark failed run job", { runId: job.data.runId, err: e })));
+        }
+    }
+    /**
+     * The run's stream sink: deltas on the conversation's topic (any replica's subscribers get them)
+     * and the steps' live drafts in Redis ({@link streamSink}, spec 2026-11-07 §3.2).
+     */
+    sinkFor(conversationId) {
+        return streamSink(conversationId, { bus: this.bus, drafts: this.drafts, log: this.log });
+    }
+    /**
+     * After any terminal commit of a run that is not a sub-agent's (sub-agents spec §12): stops its
+     * active fork invocation child on its behalf (no account); background `Agent` children keep
+     * running (agent map spec §5.4). The wait sweep is the backstop.
+     */
+    async stopChildren(runId) {
         try {
-            await this.d.stopChildren(runId);
+            await this.waits.stopChildren(runId, null);
         }
         catch (err) {
-            this.d.log.error("cannot stop the sub-agents of a finished run", { runId, err });
+            this.log.error("cannot stop the sub-agents of a finished run", { runId, err });
         }
     }
-    /** Reports a finished sub-agent run to its parent (see {@link RunWorkerDeps.onChildFinished}). */
+    /**
+     * After a sub-agent run's terminal state committed (sub-agents spec §7.3): reports it to the
+     * parent. Called with any run id whose conversation may be a child; runs that were not
+     * dispatched are ignored. Errors are logged (the wait sweep repairs a missed call).
+     */
     async childFinished(runId) {
-        if (!this.d.onChildFinished)
-            return;
         try {
-            await this.d.onChildFinished(runId);
+            await this.waits.childFinished(runId);
+        }
+        catch (err) {
+            this.log.error("cannot report finished sub-agent run to its parent", { runId, err });
+        }
+        // a sub-agent a person stopped stops its descendants too, also one it dispatched after the
+        // tree stop read the tree (agent map spec §6); any other end leaves them running
+        try {
+            await this.waits.stopDescendantsOfStopped(runId);
         }
         catch (err) {
-            this.d.log.error("cannot report finished sub-agent run to its parent", { runId, err });
+            this.log.error("cannot stop the descendants of a stopped sub-agent", { runId, err });
         }
     }
     /**
@@ -119,14 +235,14 @@ export class RunWorker {
     async ensureAfterRun(conversationId, runId) {
         for (let attempt = 0;; attempt++) {
             try {
-                await this.d.hooks?.beforeEnsureRun?.(conversationId, attempt);
-                await this.d.queue.ensureRun(conversationId);
+                await this.hooks?.beforeEnsureRun?.(conversationId, attempt);
+                await this.queue.ensureRun(conversationId);
                 return;
             }
             catch (err) {
                 const delay = ENSURE_RETRY_DELAYS_MS[attempt];
                 if (delay === undefined) {
-                    this.d.log.error("ensureRun after run failed; giving up", {
+                    this.log.error("ensureRun after run failed; giving up", {
                         conversationId,
                         runId,
                         attempts: attempt + 1,
@@ -134,7 +250,7 @@ export class RunWorker {
                     });
                     return;
                 }
-                this.d.log.warn("ensureRun after run failed; retrying", {
+                this.log.warn("ensureRun after run failed; retrying", {
                     conversationId,
                     runId,
                     attempt,
@@ -173,15 +289,15 @@ export class RunWorker {
     async onJobFailed(data, err) {
         const { runId, conversationId } = data;
         const stalled = /stalled/i.test(err.message);
-        await this.d.lock.releaseFor(conversationId, runId);
+        await this.lock.releaseFor(conversationId, runId);
         // 运行已进入 waiting（暂停后任务才失败）：它有自己的续跑路径（人工决定 / 超时任务），不标记失败。
-        const cur = await this.d.db
+        const cur = await this.db
             .selectFrom("runs")
             .select("status")
             .where("id", "=", runId)
             .executeTakeFirst();
         if (cur?.status === "waiting") {
-            this.d.log.warn("run job failed after the run was suspended; leaving it waiting", { runId });
+            this.log.warn("run job failed after the run was suspended; leaving it waiting", { runId });
             return;
         }
         await this.finish(conversationId, runId, "failed", null, {
@@ -214,25 +330,18 @@ export class RunWorker {
         this.workers = [];
         this.closing = true;
         this.closingSignal.abort();
-        await Promise.all(workers.map((w) => w.pause(true).catch((err) => this.d.log.warn("run worker pause failed", { err }))));
+        await Promise.all(workers.map((w) => w.pause(true).catch((err) => this.log.warn("run worker pause failed", { err }))));
         for (const a of this.active.values())
             a.shutdown.abort();
         const all = Promise.all([...this.active.values()].map((a) => a.done));
-        let timer;
-        const finished = await Promise.race([
-            all.then(() => true),
-            new Promise((resolve) => {
-                timer = setTimeout(() => resolve(false), Math.max(0, budgetMs));
-                timer.unref();
-            }),
-        ]);
-        clearTimeout(timer);
+        const finished = await waitWithin(all, budgetMs);
         if (!finished) {
             for (const [runId, a] of this.active) {
                 a.abandoned = true;
                 a.lease.abandon();
+                a.quota?.abandon();
                 a.stopTimers();
-                this.d.log.warn("run did not reach a step boundary before shutdown; leaving it to another worker", {
+                this.log.warn("run did not reach a step boundary before shutdown; leaving it to another worker", {
                     runId,
                 });
             }
@@ -241,26 +350,15 @@ export class RunWorker {
         // 关闭期间完成 / 失败的任务登记的后续处理（ensureRun 等）要在调用方关闭运行队列之前做完，
         // 否则投递半途被打断，待处理的消息无人处理。以剩余预算为限（至少留一点时间）。
         if (this.followUps.size > 0) {
-            let t;
-            await Promise.race([
-                Promise.allSettled([...this.followUps]),
-                new Promise((resolve) => {
-                    t = setTimeout(resolve, Math.max(FOLLOW_UP_MIN_WAIT_MS, deadline - Date.now()));
-                    t.unref();
-                }),
-            ]);
-            clearTimeout(t);
+            await waitWithin(Promise.allSettled([...this.followUps]), Math.max(FOLLOW_UP_MIN_WAIT_MS, deadline - Date.now()));
         }
-        const conn = this.conn;
-        this.conn = undefined;
-        if (conn)
-            await conn.quit().catch(() => conn.disconnect());
     }
+    /** One run job (the `@Processor`s of both run queues call it). */
     async process(job, token) {
         const { runId, conversationId } = job.data;
         if (this.closing)
             return requeue(job, token, 0);
-        const run = await this.d.db
+        const run = await this.db
             .selectFrom("runs")
             .select([
             "id",
@@ -270,6 +368,7 @@ export class RunWorker {
             "trigger_seq",
             "started_at",
             "waited_ms",
+            "budget_run_id",
         ])
             .where("id", "=", runId)
             .executeTakeFirst();
@@ -285,22 +384,22 @@ export class RunWorker {
         // 运行在等人处理（例如暂停后本任务被 stalled 机制重新投递）：不执行，续跑由处理 / 超时发起的新任务负责。
         if (run.status === "waiting")
             return;
-        const conv = await this.d.db
+        const conv = await this.db
             .selectFrom("conversations")
-            .select(["org_id", "agent_id", "kind"])
+            .select(["org_id", "agent_id", "kind", "subagent_depth"])
             .where("id", "=", conversationId)
             .executeTakeFirst();
         if (!conv)
             return;
         // 会话锁 TTL 与任务锁一致：持有者崩溃后，任务被判定 stalled 时会话锁也差不多同时过期。
-        const lease = await this.d.lock.acquire(conversationId, runId, this.d.hooks?.lockTtlMs ?? this.d.config().runtime.jobLockMs);
+        const lease = await this.lock.acquire(conversationId, runId, this.hooks?.lockTtlMs ?? this.config.get().runtime.jobLockMs);
         if (!lease)
             return requeue(job, token, LOCK_BUSY_DELAY_MS);
         // A sub-agent stopped while still queued (its parent's stop or wait timeout) ends here, before
         // taking an org run slot: under a full quota it would otherwise wait for a slot only to be
         // aborted, and its parent would stay waiting meanwhile (final review m7)
         if (conv.kind === "subagent" && run.status === "queued") {
-            const stop = await this.d.abort.requested(runId);
+            const stop = await this.abort.requested(runId);
             if (stop !== null) {
                 try {
                     await this.finish(conversationId, runId, "aborted", null, {
@@ -315,7 +414,7 @@ export class RunWorker {
                 finally {
                     await lease
                         .release()
-                        .catch((err) => this.d.log.warn("conversation lock release failed", { runId, err }));
+                        .catch((err) => this.log.warn("conversation lock release failed", { runId, err }));
                 }
                 await this.dropCheckpoints(runId);
                 await this.childFinished(runId);
@@ -345,30 +444,28 @@ export class RunWorker {
         let entered = false;
         let delayMs = null;
         try {
-            const limit = await orgRunLimit(this.d.settings, this.d.config, conv.org_id);
-            entered = await this.d.quota.tryEnter(conv.org_id, runId, limit, ORG_QUOTA_LEASE_MS);
+            const limit = await orgRunLimit(this.settings, this.config, conv.org_id);
+            const slot = await this.quota.enter(conv.org_id, runId, limit, ORG_QUOTA_LEASE_MS);
+            if (slot !== undefined)
+                state.quota = slot;
+            entered = slot !== undefined;
             if (!entered) {
                 delayMs = QUOTA_FULL_DELAY_MS;
             }
             else {
                 // 运行开始执行（含续跑、stalled 后接手）：通知旁路（渠道出站投递据此把输出投到 IM），失败不影响运行
-                try {
-                    this.d.onRunStart?.(conversationId);
-                }
-                catch (err) {
-                    this.d.log.warn("onRunStart hook failed", { conversationId, err });
-                }
+                void this.events.emit("run.started", { conversationId, runId });
                 const r = await this.execute(run, { id: conversationId, ...conv }, state).catch(async (err) => {
                     if (state.abandoned)
                         return "abandoned";
                     if (state.leaseLost)
                         return "interrupted";
                     // 编排自身出错（如写事件失败）：尽力把运行标记为失败，避免会话卡在 running。
-                    this.d.log.error("run orchestration failed", { conversationId, runId, err });
+                    this.log.error("run orchestration failed", { conversationId, runId, err });
                     await this.finish(conversationId, runId, "failed", null, {
                         type: "run_failed",
                         payload: { error: { code: "run.internal", message: "The run failed unexpectedly" } },
-                    }).catch((e) => this.d.log.error("cannot mark run as failed", { runId, err: e }));
+                    }).catch((e) => this.log.error("cannot mark run as failed", { runId, err: e }));
                     return "broken";
                 });
                 if (r === "interrupted")
@@ -378,16 +475,14 @@ export class RunWorker {
         finally {
             state.stopTimers();
             if (!state.abandoned) {
-                if (entered) {
-                    await this.d.quota
-                        .leave(conv.org_id, runId)
-                        .catch((err) => this.d.log.warn("org quota leave failed", { runId, err }));
-                }
+                // releasing the slot stops its renewal and leaves (a failure is logged by the lock service)
+                if (entered)
+                    await state.quota?.release();
                 // 锁已丢失时不释放（已不属于本运行；RELEASE 虽比对 runId，这里也不再触碰）。
                 if (!state.leaseLost) {
                     await lease
                         .release()
-                        .catch((err) => this.d.log.warn("conversation lock release failed", { runId, err }));
+                        .catch((err) => this.log.warn("conversation lock release failed", { runId, err }));
                 }
             }
             this.active.delete(runId);
@@ -400,7 +495,7 @@ export class RunWorker {
         // 暂停：会话锁与配额已释放，checkpoint 保留；置 waiting 并投递超时任务。任务就此完成，不 ensureRun
         // （等待期间的新消息在续跑后作为插话吸收）。
         if (state.suspended) {
-            await this.d.waits.suspend(runId, conversationId, state.suspended.waitingFor, state.suspended.abort);
+            await this.waits.suspend(runId, conversationId, state.suspended.waitingFor, state.suspended.abort);
             return;
         }
         // 运行已到达终态（broken 时已尽力标记失败）：checkpoint 只用于续跑，删除。
@@ -414,51 +509,72 @@ export class RunWorker {
     async execute(run, conv, state) {
         const runId = run.id;
         const conversationId = conv.id;
-        const runtime = this.d.config().runtime;
+        const runtime = this.config.get().runtime;
         let agent;
         // a chat run's saved agent version, under the conversation's model switch (UI refresh B); a
         // sub-agent has none: it never takes a selection
         let saved;
         let maxSteps = runtime.maxSteps;
         let parent;
+        /** A sub-agent's name in its run context: the roster name, or the forked skill's. */
+        let childName;
         if (conv.kind === "subagent") {
             // a sub-agent runs its effective definition frozen at dispatch, never agent_versions
             // (spec §6.3), and works for the parent call that dispatched this run
-            const started = await this.d.eventLog.findByIdem(conversationId, "subagent_started");
+            const started = await this.eventLog.findByIdem(conversationId, "subagent_started");
             if (started?.type !== "subagent_started") {
                 throw new Error(`sub-agent conversation ${conversationId} has no subagent_started`);
             }
             // a follow-up runs with its task message's narrowing (final review I1): the frozen tools
             // and org skills the current version still allows, recorded at its dispatch
-            const trigger = (await this.d.eventLog.readAfter(conversationId, Number(run.trigger_seq) - 1, 1))[0];
-            agent = childRunDefinition(normalizeStoredDefinition(started.payload.definition), trigger?.type === "user_message" && trigger.seq === Number(run.trigger_seq)
+            const trigger = (await this.eventLog.readAfter(conversationId, Number(run.trigger_seq) - 1, 1))[0];
+            agent = childRunDefinition(await normalizeStoredDefinitionIn(this.db, conv.org_id, started.payload.definition), trigger?.type === "user_message" && trigger.seq === Number(run.trigger_seq)
                 ? trigger.payload.dispatch?.narrowed
                 : undefined);
             maxSteps = Math.min(started.payload.maxSteps, runtime.maxSteps);
-            const row = await dispatchOfChildRun(this.d.db, runId);
+            childName = started.payload.template.invokedSkill?.name ?? started.payload.agentType;
+            const row = await dispatchOfChildRun(this.db, runId);
             const otherAgent = started.payload.template.source === "agent";
+            const parentConversationId = row?.parentConversationId ?? started.payload.parent.conversationId;
+            // a sub-agent conversation is at depth 1 at least: one written before depths were recorded
+            // (default 0) was a child of a root
+            const depth = Math.max(conv.subagent_depth, 1) - 1;
+            const rootConversationId = depth === 0
+                ? parentConversationId
+                : await rootConversationOf(this.db, parentConversationId);
+            // the tree's budget window of THIS run (agent map spec §6): its own `budget_run_id`, set when
+            // it was created (a dispatch, or a wake run from the root's current window), else its
+            // dispatch's; never derived from the parent run, which for a wake run is the first dispatch's
+            const budgetRunId = run.budget_run_id ?? row?.budgetRunId;
             parent = row
                 ? {
                     conversationId: row.parentConversationId,
                     runId: row.parentRunId,
                     callId: row.parentCallId,
+                    depth,
+                    rootConversationId,
                     otherAgent,
+                    ...(budgetRunId !== undefined && { budgetRunId }),
+                    ...(row.forSkill === true && { forSkill: true }),
                 }
                 : {
                     conversationId: started.payload.parent.conversationId,
                     runId: started.payload.parent.runId,
                     callId: started.payload.parent.callId,
+                    depth,
+                    rootConversationId,
                     otherAgent,
+                    ...(budgetRunId !== undefined && { budgetRunId }),
                 };
         }
         else {
-            const version = await this.d.db
+            const version = await this.db
                 .selectFrom("agent_versions")
                 .select("definition")
                 .where("agent_id", "=", conv.agent_id)
                 .where("version", "=", run.agent_version)
                 .executeTakeFirstOrThrow();
-            saved = normalizeStoredDefinition(version.definition);
+            saved = await normalizeStoredDefinitionIn(this.db, conv.org_id, version.definition);
             agent = saved;
         }
         let startedAt = run.started_at;
@@ -466,66 +582,40 @@ export class RunWorker {
         // run's `run_started`, read under the conversation lock when the run starts, so a replay
         // (`selectionAt`) sees exactly what the run used.
         // A sub-agent (no `saved`) runs its frozen definition as is.
-        const existingStart = await this.d.eventLog.findByIdem(conversationId, `run_started:${runId}`);
+        const existingStart = await this.eventLog.findByIdem(conversationId, `run_started:${runId}`);
         if (existingStart && saved !== undefined) {
-            agent = effectiveDefinition(saved, await readSelection(this.d.db, conversationId, existingStart.seq));
+            agent = effectiveDefinition(saved, await readSelection(this.db, conversationId, existingStart.seq));
         }
         if (run.status === "queued" || startedAt === null) {
             if (!existingStart) {
                 if (saved !== undefined)
-                    await this.fallBackIfUnavailable(conversationId, runId, saved);
-                const toSeq = await this.d.db.transaction().execute(async (t) => {
-                    await t
-                        .selectFrom("conversations")
-                        .select("id")
-                        .where("id", "=", conversationId)
-                        .forUpdate()
-                        .execute();
-                    if (saved !== undefined) {
-                        agent = effectiveDefinition(saved, await readSelection(t, conversationId));
-                    }
-                    const [ev] = await this.d.eventLog.append(conversationId, [
-                        {
-                            type: "run_started",
-                            runId,
-                            idemKey: `run_started:${runId}`,
-                            payload: {
-                                agentVersion: run.agent_version,
-                                model: agent.model,
-                                triggerAccountId: run.trigger_account_id,
-                            },
-                        },
-                    ], t);
-                    return ev?.seq;
-                });
+                    await this.fallBackIfUnavailable(conv.org_id, conversationId, runId, saved);
+                const started = await this.appendRunStarted(conversationId, run, agent, saved);
+                agent = started.agent;
+                const toSeq = started.toSeq;
                 if (toSeq !== undefined)
-                    await this.d.eventLog.notify(conversationId, toSeq);
+                    await this.eventLog.notify(conversationId, toSeq);
             }
             // 技能目录快照（Ruling M17）：在置为 running 之前写，崩溃重试时仍走这里（幂等键去重）
             try {
-                await recordSkillsCatalog({
-                    db: this.d.db,
-                    eventLog: this.d.eventLog,
-                    log: this.d.log,
-                    ...(this.d.storage !== undefined && { storage: this.d.storage }),
-                }, {
+                await this.skillsCatalog.record({
                     orgId: conv.org_id,
                     agentId: conv.agent_id,
                     conversationId,
                     runId,
                     agent,
-                });
+                }, { log: this.log });
             }
             catch (e) {
                 // Pinned skill bodies could not be read (Decision 9), or the pinned skills kept changing
                 // while they were read (`conflict`): fail before any model request. A transient failure
                 // or a conflict is fixed by sending again; a permanent one names the skill for the owner
-                // (`recordSkillsCatalog` already logged it at error). Other errors take the generic path.
+                // (`SkillsCatalogService.record` already logged it at error). Other errors take the generic path.
                 if (!(e instanceof ApiError) ||
                     (e.code !== "storage.unavailable" && e.code !== "conflict")) {
                     throw e;
                 }
-                this.d.log.warn("skills catalog not recorded at run start", {
+                this.log.warn("skills catalog not recorded at run start", {
                     conversationId,
                     runId,
                     code: e.code,
@@ -538,7 +628,23 @@ export class RunWorker {
                 });
                 return "finished";
             }
-            const updated = await this.d.db
+            // run context (spec §5): after the catalog, before the run is running, so before any
+            // compaction and model call; a retried run start finds its event or no change
+            await this.runContext.record({
+                orgId: conv.org_id,
+                conversationId,
+                runId,
+                triggerSeq: Number(run.trigger_seq),
+                agent,
+                ...(parent !== undefined && {
+                    subagent: {
+                        parentConversationId: parent.conversationId,
+                        parentRunId: parent.runId,
+                        name: childName ?? agent.name,
+                    },
+                }),
+            });
+            const updated = await this.db
                 .updateTable("runs")
                 .set({ status: "running", started_at: sql `COALESCE(started_at, now())` })
                 .where("id", "=", runId)
@@ -556,44 +662,34 @@ export class RunWorker {
             deadlineHit = true;
             ac.abort();
         }, Math.max(0, deadline - Date.now()));
-        const quotaTimer = setInterval(() => {
-            this.d.quota
-                .renew(conv.org_id, runId, ORG_QUOTA_LEASE_MS)
-                .then((ok) => {
-                if (!ok)
-                    this.d.log.warn("org quota lease lost", { runId, orgId: conv.org_id });
-            })
-                .catch((err) => this.d.log.warn("org quota renew failed", { runId, err }));
-        }, ORG_QUOTA_LEASE_MS / 3);
-        quotaTimer.unref();
         state.stopTimers = () => {
             clearTimeout(deadlineTimer);
-            clearInterval(quotaTimer);
         };
         let unwatch;
         try {
-            unwatch = await this.d.abort.watch(runId, (by, detail) => {
+            unwatch = await this.abort.watch(runId, (by, detail) => {
                 abortedBy = by;
                 abortDetail = detail;
                 ac.abort();
             });
             // 取得会话锁之后再读 consumed_seq（锁内不会有别的运行推进它）。
-            const { consumed_seq } = await this.d.db
+            const { consumed_seq } = await this.db
                 .selectFrom("conversations")
                 .select("consumed_seq")
                 .where("id", "=", conversationId)
                 .executeTakeFirstOrThrow();
             const startConsumed = Number(consumed_seq);
             let absorbed = startConsumed;
-            const pendingUserMessages = async (afterSeq) => {
+            const pendingAbsorbable = async (afterSeq) => {
                 // loop 声明已吸收到 afterSeq（续跑时来自 checkpoint，可能包含之前进程吸收的消息）。
                 absorbed = Math.max(absorbed, afterSeq);
                 const out = [];
                 let after = Math.max(afterSeq, startConsumed);
                 for (;;) {
-                    const page = await this.d.eventLog.readAfter(conversationId, after, READ_PAGE);
+                    const page = await this.eventLog.readAfter(conversationId, after, READ_PAGE);
+                    // messages and finished background tasks (spec 2026-11-05-background-bash-design §2.4)
                     for (const e of page)
-                        if (e.type === "user_message")
+                        if (isAbsorbable(e))
                             out.push(e);
                     const last = page.at(-1);
                     if (page.length < READ_PAGE || !last)
@@ -609,7 +705,7 @@ export class RunWorker {
             };
             let outcome;
             try {
-                outcome = await this.d.loop.run({
+                outcome = await this.loop.run({
                     orgId: conv.org_id,
                     conversationId,
                     runId,
@@ -619,8 +715,8 @@ export class RunWorker {
                     agentVersion: run.agent_version,
                     signal: ac.signal,
                     shutdown: state.shutdown.signal,
-                    sink: this.d.sinkFor?.(conversationId) ?? noopSink,
-                    pendingUserMessages,
+                    sink: this.sinkFor(conversationId),
+                    pendingAbsorbable,
                     limits: { maxSteps, deadline },
                     // a sub-agent's conversation fires hooks like a chat, with `parent` set (spec §11)
                     conversationKind: conv.kind === "eval" ? "eval" : conv.kind === "subagent" ? "subagent" : "chat",
@@ -634,7 +730,7 @@ export class RunWorker {
                     return "interrupted";
                 const err = e instanceof RunError ? e : new RunError("run.internal", "The run failed unexpectedly");
                 if (!(e instanceof RunError)) {
-                    this.d.log.error("agent loop threw", { conversationId, runId, err: e });
+                    this.log.error("agent loop threw", { conversationId, runId, err: e });
                 }
                 // 失败也推进 consumed_seq 到已吸收的位置：否则结束时的 ensureRun 会对同一条消息无限重试；
                 // 用户看到 run_failed 后可以重发。
@@ -644,6 +740,10 @@ export class RunWorker {
                 });
                 return "finished";
             }
+            finally {
+                // the execution here ended: what this process held of the run's drafts goes
+                this.drafts.release(runId);
+            }
             if (state.abandoned)
                 return "abandoned";
             // 锁在运行中丢失：无论 loop 返回什么都不写终态，任务回到队列由持锁者续跑。
@@ -701,32 +801,26 @@ export class RunWorker {
         }
         finally {
             state.stopTimers();
-            await unwatch?.().catch((err) => this.d.log.warn("abort unwatch failed", { runId, err }));
+            await unwatch?.().catch((err) => this.log.warn("abort unwatch failed", { runId, err }));
         }
     }
     completed(conversationId) {
-        try {
-            this.d.onRunCompleted?.(conversationId);
-        }
-        catch (err) {
-            this.d.log.warn("onRunCompleted hook failed", { conversationId, err });
-        }
+        // a completed run enqueues the conversation's title job (never throws)
+        void this.titles.maybeEnqueue(conversationId);
     }
     /**
      * When the conversation was switched to a model that no longer resolves (provider disabled,
      * model removed), writes `model_switched { model: null, effort: null, reason: "unavailable" }`
      * for this run (idempotent) and clears the cached selection: the run and the next ones use the
      * agent's model. A provider that only failed to list its models is not "gone" (the run's ladder
-     * handles it).
+     * handles it). Resolved for the conversation's org (its effective provider config).
      */
-    async fallBackIfUnavailable(conversationId, runId, agent) {
-        if (!this.d.models)
-            return;
-        const sel = await readSelection(this.d.db, conversationId);
+    async fallBackIfUnavailable(orgId, conversationId, runId, agent) {
+        const sel = await readSelection(this.db, conversationId);
         if (sel.model === null || sameModel(sel.model, agent.model))
             return;
         try {
-            await this.d.models.resolve(sel.model);
+            await this.models.resolve(orgId, sel.model);
             return;
         }
         catch (e) {
@@ -735,71 +829,153 @@ export class RunWorker {
             if (!(e instanceof ApiError && e.code === "agent.model_unavailable"))
                 throw e;
         }
-        this.d.log.warn("switched-to model unavailable; falling back to the agent's model", {
+        this.log.warn("switched-to model unavailable; falling back to the agent's model", {
             conversationId,
             runId,
             model: sel.model,
         });
-        const ev = await this.d.db.transaction().execute(async (t) => {
-            // re-check under the row lock: a person who switched again since the read above wins
-            await t
-                .selectFrom("conversations")
-                .select("id")
-                .where("id", "=", conversationId)
-                .forUpdate()
-                .executeTakeFirst();
-            if (!sameSelection(await readSelection(t, conversationId), sel))
-                return null;
-            const [written] = await this.d.eventLog.append(conversationId, [
-                {
-                    type: "model_switched",
-                    runId,
-                    idemKey: `model_fallback:${runId}`,
-                    payload: { model: null, effort: null, byAccountId: null, reason: "unavailable" },
-                },
-            ], t);
-            await t
-                .updateTable("conversations")
-                .set({ selection: JSON.stringify(NO_SELECTION) })
-                .where("id", "=", conversationId)
-                .execute();
-            return written ?? null;
-        });
+        const ev = await this.fallBackIn(conversationId, runId, sel);
         if (ev === null)
             return;
-        await this.d.eventLog.notify(conversationId, ev.seq);
-        await this.d.eventLog.publishChanged(conversationId, "selection");
+        await this.eventLog.notify(conversationId, ev.seq);
+        await this.eventLog.publishChanged(conversationId, "selection");
+    }
+    /**
+     * `run_started` under the conversation row lock, with the model / effort switch in effect then
+     * (a chat run's `saved` version under the conversation's selection): what the run uses.
+     */
+    async appendRunStarted(conversationId, run, 
+    /** The definition so far (a sub-agent's frozen one is final). */
+    current, saved) {
+        const t = this.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .execute();
+        const agent = saved !== undefined
+            ? effectiveDefinition(saved, await readSelection(t, conversationId))
+            : current;
+        // a wake run's boundary is a finished background task (background Bash §3) or a sub-agent's
+        // delivery (agent map spec §5.3), not a message
+        const boundary = await t
+            .selectFrom("conversation_events")
+            .select("type")
+            .where("conversation_id", "=", conversationId)
+            .where("seq", "=", run.trigger_seq)
+            .executeTakeFirst();
+        const [ev] = await this.eventLog.appendIn(conversationId, [
+            {
+                type: "run_started",
+                runId: run.id,
+                idemKey: `run_started:${run.id}`,
+                payload: {
+                    agentVersion: run.agent_version,
+                    model: agent.model,
+                    triggerAccountId: run.trigger_account_id,
+                    ...(boundary?.type === "background_task_finished" && {
+                        trigger: "background_task",
+                        triggerSeq: Number(run.trigger_seq),
+                    }),
+                    ...(boundary?.type === "subagent_delivery" && {
+                        trigger: "subagent",
+                        triggerSeq: Number(run.trigger_seq),
+                    }),
+                },
+            },
+        ]);
+        return { toSeq: ev?.seq, agent };
+    }
+    /** {@link fallBackIfUnavailable}'s write: null when the person switched again meanwhile. */
+    async fallBackIn(conversationId, runId, sel) {
+        const t = this.db;
+        // re-check under the row lock: a person who switched again since the read above wins
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!sameSelection(await readSelection(t, conversationId), sel))
+            return null;
+        const [written] = await this.eventLog.appendIn(conversationId, [
+            {
+                type: "model_switched",
+                runId,
+                idemKey: `model_fallback:${runId}`,
+                payload: { model: null, effort: null, byAccountId: null, reason: "unavailable" },
+            },
+        ]);
+        await t
+            .updateTable("conversations")
+            .set({ selection: JSON.stringify(NO_SELECTION) })
+            .where("id", "=", conversationId)
+            .execute();
+        return written ?? null;
     }
     /** 删除已结束运行的 checkpoint thread（失败只记日志）。 */
     async dropCheckpoints(runId) {
-        await this.d.checkpoints
-            ?.deleteThread(runId)
-            .catch((err) => this.d.log.warn("checkpoint delete failed", { runId, err }));
+        await this.checkpoints
+            .deleteThread(runId)
+            .catch((err) => this.log.warn("checkpoint delete failed", { runId, err }));
     }
     /**
      * 写终态（见 `finishRun`：运行仍未结束才写，同一事务内推进 `consumed_seq` 并更新 `runs.status`），
      * 提交后发布会话通知，然后调用测试钩子。返回终态事件 seq；运行已是终态 → null。
      */
     async finish(conversationId, runId, status, consumed, event, hook = true, floorToTrigger = true) {
-        const stopOpen = this.d.stopOpenCalls;
         let fire = () => { };
-        const toSeq = await finishRun(this.d.db, this.d.eventLog, {
+        const toSeq = await this.finisher.finish({
             conversationId,
             runId,
             status,
             consumed,
             event,
             floorToTrigger,
-            ...(stopOpen !== undefined && {
-                beforeTerminal: async (t) => {
-                    fire = (await stopOpen(t, runId)).fire;
-                },
-            }),
+            beforeTerminal: async () => {
+                fire = (await this.pipeline.stopOpenAgentCalls(runId)).fire;
+            },
         });
         if (toSeq !== null)
             fire();
         if (hook)
-            await this.d.hooks?.beforeRelease?.(runId, conversationId);
+            await this.hooks?.beforeRelease?.(runId, conversationId);
         return toSeq;
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], RunWorker.prototype, "appendRunStarted", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], RunWorker.prototype, "fallBackIn", null);
+RunWorker = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(ConversationLock)),
+    __param(3, Inject(RUN_QUOTA)),
+    __param(4, Inject(RunAbort)),
+    __param(5, Inject(RunQueue)),
+    __param(6, Inject(SettingsService)),
+    __param(7, Inject(AgentLoops)),
+    __param(8, Inject(RunSteps)),
+    __param(9, Inject(KernelConfigService)),
+    __param(10, Inject(KERNEL_LOGGER)),
+    __param(11, Inject(KERNEL_BUS)),
+    __param(12, Inject(KyselyCheckpointSaver)),
+    __param(13, Inject(Waits)),
+    __param(14, Inject(KernelEvents)),
+    __param(15, Inject(TitleQueue)),
+    __param(16, Inject(ProviderRegistry)),
+    __param(17, Inject(SkillsCatalogService)),
+    __param(18, Inject(RunContextService)),
+    __param(19, Inject(ToolPipeline)),
+    __param(20, Inject(RunFinish)),
+    __param(21, Inject(TransactionHost)),
+    __param(22, Inject(RunDrafts)),
+    __param(23, Optional()),
+    __param(23, Inject(RUN_HOOKS))
+], RunWorker);
+export { RunWorker };