@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.26

package/dist/runtime/run-orphan-check.job.js

@@ -25,7 +25,7 @@ import { notifyFinished, RunFinish } from "./run-finish.js";
 import { RunJobs, runJobId, runQueueNameFor } 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`). */
+/** The check's `@LockedInterval` job name (its run lock key: `cron:run-orphan-check`). */
 export const RUN_ORPHAN_CHECK_JOB = "run-orphan-check";
 /** The check's period: a fixed constant, not a config field. */
 export const RUN_ORPHAN_CHECK_PERIOD_MS = 60_000;
@@ -49,12 +49,16 @@ const SINCE = sql `GREATEST(COALESCE(r.queued_at, r.created_at), COALESCE(r.star
 /**
  * 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).
+ * conversation drives its runs itself). A deleted org's runs are never candidates, running ones
+ * included: its deletion purged its owed jobs on purpose, so their absence is no lost job and
+ * nothing is re-added, and the org's data is invisible from then on, so a running orphan is left
+ * as it is rather than failed.
  */
 export async function orphanCandidates(db, statuses, minAgeMs, limit, after) {
     let q = db
         .selectFrom("runs as r")
         .innerJoin("conversations as c", "c.id", "r.conversation_id")
+        .innerJoin("orgs as o", "o.id", "c.org_id")
         .select([
         "r.id",
         "r.conversation_id",
@@ -67,6 +71,7 @@ export async function orphanCandidates(db, statuses, minAgeMs, limit, after) {
     ])
         .where("r.status", "in", statuses)
         .where("c.kind", "in", ["chat", "subagent"])
+        .where("o.deleted_at", "is", null)
         .where(SINCE, "<", sql `now() - ${minAgeMs}::integer * interval '1 millisecond'`);
     if (after !== undefined) {
         q = q.where(sql `(${SINCE}, r.id) > (${after.since}::timestamptz, ${after.runId})`);
@@ -110,12 +115,12 @@ async function* candidatePages(db, statuses, minAgeMs) {
     }
 }
 /**
- * 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).
+ * 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 async function queuedRunsWithoutJob(db, jobExists, opts) {
     const out = [];
@@ -146,9 +151,9 @@ export async function queuedRunsWithoutJob(db, jobExists, opts) {
  *   `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.
+ * - `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.

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

@@ -1,5 +1,4 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { Queue } from "bullmq";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -32,14 +31,10 @@ export declare class RunQueue {
     private readonly log;
     readonly txHost: TransactionHost;
     private readonly config;
-    /** The producer side of the delayed `bg-wake` job (`MaintenanceProcessor` consumes it). */
-    private readonly maintenance;
     private readonly ensureFails;
     constructor(kdb: KernelDb, eventLog: EventLog, lock: Pick<ConversationLock, "holder">, jobs: RunJobs, finisher: Pick<RunFinish, "finishIn">, 
     /** An orphan aborted directly loses its checkpoint thread (thread_id = runId). */
-    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost, config: KernelConfigService, 
-    /** The producer side of the delayed `bg-wake` job (`MaintenanceProcessor` consumes it). */
-    maintenance: Pick<Queue, "add">, ensureFails?: () => boolean);
+    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost, config: KernelConfigService, ensureFails?: () => boolean);
     private get db();
     /**
      * 有未消费的用户消息（最新 user_message 的 seq > `consumed_seq`）、会话锁无人持有、
@@ -51,7 +46,7 @@ export declare class RunQueue {
      * once it is sent; with no head either, a wake-eligible finished background task or sub-agent
      * delivery (background Bash spec §3, agent map spec §5.3, {@link wakeDecisionIn}): the run is
      * then attributed to the event's trigger account and joins the tree's budget window, and an
-     * event inside the wake window schedules the delayed `bg-wake` job instead. A sub-agent's
+     * event inside the wake window owes the delayed `bg-wake` job instead. A sub-agent's
      * conversation is only woken this way ({@link childWakeIn}).
      *
      * An active run (queued, running or waiting) is left alone: a run nobody runs any more is the
@@ -77,8 +72,9 @@ export declare class RunQueue {
     private jobIdFor;
     /**
      * Owes the new run's job in {@link ensureRunIn}'s transaction, before its run row is written.
-     * False (logged): the same job id is still owed, so the caller writes no run (a second run of
-     * one trigger; the conversation's unique active run makes this a should-not-happen).
+     * False (logged): the same job id is still owed, so the caller writes no run. A later run of the
+     * same trigger has its own `<runJobId>-<n>` ({@link jobIdFor}), so this is a should-not-happen
+     * (the conversation has one active run at a time).
      */
     private oweJob;
     /**
@@ -89,15 +85,17 @@ export declare class RunQueue {
      * racing the run's end starts a new run, never lost); and it is woken by its own background
      * task's finish or a delivery from its own sub-agent, under the same rules as a chat
      * conversation. Neither happens once its last run was stopped (`aborted`): a stopped sub-agent is
-     * started again only by its parent. Both read the queue and the trigger account's access on the root
-     * of its tree; a message needs no wake setting and has no wake window. The run counts against
-     * the root's budget window and runs on the sub-agent queue under `runJobId(child, boundary
-     * seq)`. An active run is never started past (one nobody runs is the `run-orphan-check`'s).
+     * started again only by its parent; nor while a person's stop of the root holds the tree
+     * (`conversations.tree_stopped_at`, cleared by the root's next run). Both read the queue and the
+     * trigger account's access on the root of its tree; a message needs no wake setting and has no
+     * wake window. The run counts against the root's budget window and runs on the sub-agent queue
+     * under `runJobId(child, boundary seq)`. An active run is never started past (one nobody runs is
+     * the `run-orphan-check`'s).
      */
     private childWakeIn;
     /**
-     * The newest unconsumed message of an idle sub-agent (a `SendMessage` its last run did not absorb)
-     * as a run boundary, or null: none; the root's queue is paused or the root deleted (the
+     * The newest unconsumed message of an idle sub-agent (a `SendMessage` its last run did not
+     * absorb) as a run boundary, or null: none; the root's queue is paused or the root deleted (the
      * message waits for the unpause, {@link wakeHeldTree}); or its author can no longer send to the
      * root (it waits for a later run). The caller already refused a stopped sub-agent (last run
      * `aborted`): a message that reached it while running and then stopped is parked, and the next
@@ -126,13 +124,6 @@ export declare class RunQueue {
      * with their org and newest seq. Reads only (no row locks).
      */
     private heldTree;
-    /**
-     * Schedules the delayed `bg-wake` job at the end of the conversation's wake window (after the
-     * commit): one job per conversation and window end, so finishes inside one window share it. It
-     * calls {@link ensureRun}, which wakes the conversation if a finish is still unconsumed. A failed
-     * enqueue is logged: the next message, run end or page opening re-derives the wake.
-     */
-    private scheduleWake;
     /**
      * Owes the ensure-run backstop of `conversationId` in the caller's transaction
      * ({@link oweEnsureRun}): `seq` is the event the transaction wrote, `orgId` the conversation's.
@@ -141,13 +132,27 @@ export declare class RunQueue {
     /**
      * Stops an orphaned run directly (`POST .../abort`, a tree stop): a `running` run whose
      * conversation lock is free and whose BullMQ job is gone hears no stop broadcast, so its
-     * `run_aborted` is written here (status aborted, `consumed_seq` at least to its trigger): true. Not
-     * an orphan (someone runs it; a queued run's job is owed, or lost and re-added by the
+     * `run_aborted` is written here (status aborted, `consumed_seq` at least to its trigger): true.
+     * Not an orphan (someone runs it; a queued run's job is owed, or lost and re-added by the
      * `run-orphan-check`, whose worker then sees the stop marker) or already finished: false, and the
      * caller broadcasts the stop.
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
     private abortOrphanIn;
+    /**
+     * Ends a `queued` run in PG before any worker started it (an offboarded member's run, ruling
+     * R27): with the conversation lock free, under the conversation row lock, a run still `queued` is
+     * finished `aborted` with `run_aborted` (`consumed_seq` at least to its trigger), so a job that
+     * runs later finds it finished and starts nothing. True when it did; false when a worker holds
+     * the conversation or is in the middle of the run's first start (`run_started` written,
+     * `started_at` not yet set; it hears the stop), or the run is no longer queued. A run resumed
+     * from `waiting` to `queued` is ended like a new one. The caller writes the stop marker first, so
+     * a worker that takes the conversation meanwhile still stops; a worker that read the run before
+     * this commit re-checks it under the row locks before its `run_started` and never moves it back
+     * to `running`.
+     */
+    abortQueued(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    private abortQueuedIn;
     /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
     private activeRun;
     /**

package/dist/runtime/run-queue.js

@@ -8,11 +8,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
 import { visibleTo } from "../agents/agent-lookup.js";
-import { BG_WAKE_JOB, bgWakeJobId, wakeDecisionIn, } from "../background/wake-rules.js";
+import { wakeDecisionIn } from "../background/wake-rules.js";
 import { EventLog } from "../conversations/event-log.js";
 import { dispatchQueuedIn, pauseQueueWith } from "../conversations/queue.js";
 import { conversationTree } from "../conversations/tree.js";
@@ -25,7 +24,6 @@ import { linkStartedRunIn } from "../schedules/run-tracker.js";
 import { scheduledTaskRunAt } from "../schedules/unattended.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
-import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { notifyFinished, RunFinish } from "./run-finish.js";
 import { ACTIVE_RUN_STATUSES, RunJobs, runJobId, runQueueNameFor } from "./run-jobs.js";
 import { rootConversationOf } from "./subagents/child.js";
@@ -37,12 +35,6 @@ export { ACTIVE_RUN_STATUSES, ENSURE_RUN_BACKSTOP_MS, ENSURE_RUN_JOB, ensureRunJ
  * kernel never provides it.
  */
 export const ENSURE_RUN_FAILS = Symbol("ENSURE_RUN_FAILS");
-/**
- * Margin added to the delayed wake job: its window is read on the database's clock, the delay runs
- * on this process's and Redis's, so the job does not usually fire just before the window ends (one
- * that does reschedules itself under its next retry id, `bgWakeJobId`).
- */
-const WAKE_JOB_MARGIN_MS = 1000;
 /**
  * 运行队列（生产方）：`ensureRun` 在会话有未消费的用户消息、且没有进行中的运行时插入 `runs` 行并投递任务。
  * 「是否已有运行」以 PG 为准（会话行锁内检查 `runs` 中的 queued / running），并参考会话锁的持有者；
@@ -58,13 +50,10 @@ let RunQueue = class RunQueue {
     log;
     txHost;
     config;
-    maintenance;
     ensureFails;
     constructor(kdb, eventLog, lock, jobs, finisher, 
     /** An orphan aborted directly loses its checkpoint thread (thread_id = runId). */
-    checkpoints, log, txHost, config, 
-    /** The producer side of the delayed `bg-wake` job (`MaintenanceProcessor` consumes it). */
-    maintenance, ensureFails = () => false) {
+    checkpoints, log, txHost, config, ensureFails = () => false) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.lock = lock;
@@ -74,7 +63,6 @@ let RunQueue = class RunQueue {
         this.log = log;
         this.txHost = txHost;
         this.config = config;
-        this.maintenance = maintenance;
         this.ensureFails = ensureFails;
     }
     get db() {
@@ -90,7 +78,7 @@ let RunQueue = class RunQueue {
      * once it is sent; with no head either, a wake-eligible finished background task or sub-agent
      * delivery (background Bash spec §3, agent map spec §5.3, {@link wakeDecisionIn}): the run is
      * then attributed to the event's trigger account and joins the tree's budget window, and an
-     * event inside the wake window schedules the delayed `bg-wake` job instead. A sub-agent's
+     * event inside the wake window owes the delayed `bg-wake` job instead. A sub-agent's
      * conversation is only woken this way ({@link childWakeIn}).
      *
      * An active run (queued, running or waiting) is left alone: a run nobody runs any more is the
@@ -111,12 +99,9 @@ let RunQueue = class RunQueue {
             dispatchedSwitch: false,
             dispatchedUnarchived: false,
             pausedNow: false,
-            wakeLater: null,
+            wakeRetry: opts.wakeRetry ?? 0,
         };
         const created = await this.ensureRunIn(conversationId, st);
-        if (st.wakeLater !== null) {
-            await this.scheduleWake(conversationId, st.wakeLater, opts.wakeRetry ?? 0);
-        }
         const { dispatchedSeq, dispatchedSwitch, dispatchedUnarchived, pausedNow } = st;
         // a pause is published too (batch 5 review I1): the page shows the reason without a reload
         if (pausedNow)
@@ -144,6 +129,7 @@ let RunQueue = class RunQueue {
             "queue_paused",
             "account_id",
             "deleted_at",
+            "tree_stopped_at",
         ])
             .where("id", "=", conversationId)
             .forUpdate()
@@ -227,8 +213,11 @@ let RunQueue = class RunQueue {
                 // Nothing queued either: a finished background task may wake the idle conversation
                 // (background Bash spec §3; a person's message or the queue always goes first)
                 const wake = await wakeDecisionIn(t, { id: conversationId, orgId: conv.org_id, rootId: conversationId }, Number(conv.consumed_seq), this.config.get().runtime.wakeOnBackgroundTask, (accountId) => authorCanSend(t, conversationId, accountId));
-                if (wake?.kind === "later")
-                    st.wakeLater = wake;
+                // inside the wake window: the delayed `bg-wake` job is owed here, so the wake survives a
+                // process that dies after the commit (transactional outbox spec §3.1)
+                if (wake?.kind === "later") {
+                    await this.jobs.oweBgWake(conversationId, wake, st.wakeRetry, conv.org_id);
+                }
                 if (wake?.kind !== "wake")
                     return null;
                 last = { seq: String(wake.seq), accountId: wake.triggerAccountId };
@@ -284,6 +273,15 @@ let RunQueue = class RunQueue {
         // the task run its message started follows this run from now on (spec §6)
         if (taskRunId !== null)
             await linkStartedRunIn(t, taskRunId, runId, conversationId);
+        // the root runs again: a person's stop of its tree no longer holds the tree's wakes
+        // (agent map spec §6); read with the row lock above, so the hot path issues no statement
+        if (conv.tree_stopped_at !== null) {
+            await t
+                .updateTable("conversations")
+                .set({ tree_stopped_at: null })
+                .where("id", "=", conversationId)
+                .execute();
+        }
         return runId;
     }
     /**
@@ -308,8 +306,9 @@ let RunQueue = class RunQueue {
     }
     /**
      * Owes the new run's job in {@link ensureRunIn}'s transaction, before its run row is written.
-     * False (logged): the same job id is still owed, so the caller writes no run (a second run of
-     * one trigger; the conversation's unique active run makes this a should-not-happen).
+     * False (logged): the same job id is still owed, so the caller writes no run. A later run of the
+     * same trigger has its own `<runJobId>-<n>` ({@link jobIdFor}), so this is a should-not-happen
+     * (the conversation has one active run at a time).
      */
     async oweJob(conversationId, runId, jobId, kind, orgId) {
         if (await this.jobs.owe({ runId, conversationId }, jobId, kind, orgId))
@@ -328,10 +327,12 @@ let RunQueue = class RunQueue {
      * racing the run's end starts a new run, never lost); and it is woken by its own background
      * task's finish or a delivery from its own sub-agent, under the same rules as a chat
      * conversation. Neither happens once its last run was stopped (`aborted`): a stopped sub-agent is
-     * started again only by its parent. Both read the queue and the trigger account's access on the root
-     * of its tree; a message needs no wake setting and has no wake window. The run counts against
-     * the root's budget window and runs on the sub-agent queue under `runJobId(child, boundary
-     * seq)`. An active run is never started past (one nobody runs is the `run-orphan-check`'s).
+     * started again only by its parent; nor while a person's stop of the root holds the tree
+     * (`conversations.tree_stopped_at`, cleared by the root's next run). Both read the queue and the
+     * trigger account's access on the root of its tree; a message needs no wake setting and has no
+     * wake window. The run counts against the root's budget window and runs on the sub-agent queue
+     * under `runJobId(child, boundary seq)`. An active run is never started past (one nobody runs is
+     * the `run-orphan-check`'s).
      */
     async childWakeIn(conversationId, conv, st) {
         const t = this.db;
@@ -353,10 +354,16 @@ let RunQueue = class RunQueue {
         if (last?.status === "aborted")
             return null;
         const rootId = await rootConversationOf(t, conversationId);
+        // a tree a person stopped at its root (agent map spec §6, changed in acceptance 2026-11-13)
+        // starts no sub-agent run here until the root runs again: an idle sub-agent the stop found
+        // with nothing running (or one whose report raced the stop) is not woken by a late finish
+        if (await treeStopped(t, rootId))
+            return null;
         const wake = (await this.pendingMessageIn(conversationId, Number(conv.consumed_seq), rootId)) ??
             (await wakeDecisionIn(t, { id: conversationId, orgId: conv.org_id, rootId }, Number(conv.consumed_seq), this.config.get().runtime.wakeOnBackgroundTask, (accountId) => authorCanSend(t, rootId, accountId)));
-        if (wake?.kind === "later")
-            st.wakeLater = wake;
+        if (wake?.kind === "later") {
+            await this.jobs.oweBgWake(conversationId, wake, st.wakeRetry, conv.org_id);
+        }
         if (wake?.kind !== "wake")
             return null;
         const jobId = await this.jobIdFor(conversationId, wake.seq);
@@ -397,8 +404,8 @@ let RunQueue = class RunQueue {
         return runId;
     }
     /**
-     * The newest unconsumed message of an idle sub-agent (a `SendMessage` its last run did not absorb)
-     * as a run boundary, or null: none; the root's queue is paused or the root deleted (the
+     * The newest unconsumed message of an idle sub-agent (a `SendMessage` its last run did not
+     * absorb) as a run boundary, or null: none; the root's queue is paused or the root deleted (the
      * message waits for the unpause, {@link wakeHeldTree}); or its author can no longer send to the
      * root (it waits for a later run). The caller already refused a stopped sub-agent (last run
      * `aborted`): a message that reached it while running and then stopped is parked, and the next
@@ -496,27 +503,6 @@ let RunQueue = class RunQueue {
             .where("r.status", "in", ACTIVE_RUN_STATUSES))))
             .execute();
     }
-    /**
-     * Schedules the delayed `bg-wake` job at the end of the conversation's wake window (after the
-     * commit): one job per conversation and window end, so finishes inside one window share it. It
-     * calls {@link ensureRun}, which wakes the conversation if a finish is still unconsumed. A failed
-     * enqueue is logged: the next message, run end or page opening re-derives the wake.
-     */
-    async scheduleWake(conversationId, w, retry) {
-        const data = { conversationId, ...(retry > 0 && { retry }) };
-        try {
-            await this.maintenance.add(BG_WAKE_JOB, data, {
-                // a job that fired early reschedules under a new id (its own is still taken)
-                jobId: bgWakeJobId(conversationId, w.windowEnd, retry),
-                delay: w.delayMs + WAKE_JOB_MARGIN_MS,
-                removeOnComplete: true,
-                removeOnFail: true,
-            });
-        }
-        catch (err) {
-            this.log.error("cannot schedule the background task wake", { conversationId, err });
-        }
-    }
     /**
      * Owes the ensure-run backstop of `conversationId` in the caller's transaction
      * ({@link oweEnsureRun}): `seq` is the event the transaction wrote, `orgId` the conversation's.
@@ -527,8 +513,8 @@ let RunQueue = class RunQueue {
     /**
      * Stops an orphaned run directly (`POST .../abort`, a tree stop): a `running` run whose
      * conversation lock is free and whose BullMQ job is gone hears no stop broadcast, so its
-     * `run_aborted` is written here (status aborted, `consumed_seq` at least to its trigger): true. Not
-     * an orphan (someone runs it; a queued run's job is owed, or lost and re-added by the
+     * `run_aborted` is written here (status aborted, `consumed_seq` at least to its trigger): true.
+     * Not an orphan (someone runs it; a queued run's job is owed, or lost and re-added by the
      * `run-orphan-check`, whose worker then sees the stop marker) or already finished: false, and the
      * caller broadcasts the stop.
      */
@@ -567,6 +553,67 @@ let RunQueue = class RunQueue {
             },
         });
     }
+    /**
+     * Ends a `queued` run in PG before any worker started it (an offboarded member's run, ruling
+     * R27): with the conversation lock free, under the conversation row lock, a run still `queued` is
+     * finished `aborted` with `run_aborted` (`consumed_seq` at least to its trigger), so a job that
+     * runs later finds it finished and starts nothing. True when it did; false when a worker holds
+     * the conversation or is in the middle of the run's first start (`run_started` written,
+     * `started_at` not yet set; it hears the stop), or the run is no longer queued. A run resumed
+     * from `waiting` to `queued` is ended like a new one. The caller writes the stop marker first, so
+     * a worker that takes the conversation meanwhile still stops; a worker that read the run before
+     * this commit re-checks it under the row locks before its `run_started` and never moves it back
+     * to `running`.
+     */
+    async abortQueued(conversationId, runId, byAccountId) {
+        if ((await this.lock.holder(conversationId)) !== null)
+            return false;
+        const toSeq = await this.abortQueuedIn(conversationId, runId, byAccountId);
+        if (toSeq === null)
+            return false;
+        await notifyFinished(this.eventLog, conversationId, toSeq, "aborted");
+        await this.dropCheckpoints(runId);
+        return true;
+    }
+    async abortQueuedIn(conversationId, runId, byAccountId) {
+        const t = this.db;
+        const conv = await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const active = await this.activeRun(t, conversationId);
+        if (!conv || !active || active.id !== runId || active.status !== "queued")
+            return null;
+        // a worker is in the middle of the run's FIRST start (its `run_started` written, `started_at`
+        // not set yet; it holds the conversation since): the stop marker ends it. A run resumed from
+        // `waiting` back to `queued` has both from its first start and is ended here like a new one:
+        // its worker skips `run_started` (it exists) and its conditional `running` update finds the run
+        // finished
+        const first = await t
+            .selectFrom("runs")
+            .select("started_at")
+            .where("id", "=", runId)
+            .executeTakeFirst();
+        if (first?.started_at === null) {
+            const started = await t
+                .selectFrom("conversation_events")
+                .select("seq")
+                .where("conversation_id", "=", conversationId)
+                .where("idem_key", "=", `run_started:${runId}`)
+                .executeTakeFirst();
+            if (started)
+                return null;
+        }
+        return this.finisher.finishIn({
+            conversationId,
+            runId,
+            status: "aborted",
+            consumed: null,
+            event: { type: "run_aborted", payload: { byAccountId, reason: "user" } },
+        });
+    }
     /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
     activeRun(t, conversationId) {
         return t
@@ -604,6 +651,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], RunQueue.prototype, "abortOrphanIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], RunQueue.prototype, "abortQueuedIn", null);
 RunQueue = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
@@ -615,9 +665,8 @@ RunQueue = __decorate([
     __param(6, Inject(KERNEL_LOGGER)),
     __param(7, Inject(TransactionHost)),
     __param(8, Inject(KernelConfigService)),
-    __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
-    __param(10, Optional()),
-    __param(10, Inject(ENSURE_RUN_FAILS))
+    __param(9, Optional()),
+    __param(9, Inject(ENSURE_RUN_FAILS))
 ], RunQueue);
 export { RunQueue };
 /** The conversation's owner is active and can still see its agent (`isAccessible`'s rule). */
@@ -642,3 +691,15 @@ async function authorCanSend(t, conversationId, accountId) {
         .executeTakeFirst();
     return row !== undefined;
 }
+/**
+ * Whether a person's stop of the root conversation holds its tree (`tree_stopped_at`, agent map
+ * spec §6): set by the stop, cleared when the root next starts a run.
+ */
+async function treeStopped(t, rootId) {
+    const root = await t
+        .selectFrom("conversations")
+        .select("tree_stopped_at")
+        .where("id", "=", rootId)
+        .executeTakeFirst();
+    return root?.tree_stopped_at != null;
+}

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

@@ -0,0 +1,12 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/** 运行的终态。 */
+export type TerminalStatus = "completed" | "failed" | "aborted";
+/** The terminal run statuses (a leaf module: the event writers of a run start import it too). */
+export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+/**
+ * Whether run `runId` has ended, read in the caller's transaction with its row locked: call it
+ * after the conversation row lock (lock order conversation, then run, as `RunFinish.finishIn`), so
+ * no stop can end the run between this read and the transaction's appends. A missing run is not
+ * ended (a caller may record for a run id without a row).
+ */
+export declare function runEndedIn(db: KernelSchemaDb, runId: string): Promise<boolean>;

package/dist/runtime/run-status.js

@@ -0,0 +1,21 @@
+/** The terminal run statuses (a leaf module: the event writers of a run start import it too). */
+export const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "aborted",
+]);
+/**
+ * Whether run `runId` has ended, read in the caller's transaction with its row locked: call it
+ * after the conversation row lock (lock order conversation, then run, as `RunFinish.finishIn`), so
+ * no stop can end the run between this read and the transaction's appends. A missing run is not
+ * ended (a caller may record for a run id without a row).
+ */
+export async function runEndedIn(db, runId) {
+    const row = await db
+        .selectFrom("runs")
+        .select("status")
+        .where("id", "=", runId)
+        .forUpdate()
+        .executeTakeFirst();
+    return row !== undefined && TERMINAL_STATUSES.has(row.status);
+}

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

@@ -8,9 +8,11 @@ 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 { SkillsCatalogService } from "../skills/catalog.js";
+import { ToolRegistry } from "../tools/registry.js";
 import { RunAbort } from "./abort.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
+import { PluginContextService } from "./plugin-context.service.js";
 import { ProviderRegistry } from "./providers.js";
 import { type OrgQuota } from "./quota.js";
 import { RunContextService } from "./run-context.service.js";
@@ -32,6 +34,12 @@ export interface RunHooks {
     lockTtlMs?: number;
     /** 任务结束后的每次 ensureRun 尝试之前调用（attempt 从 0 起）；抛错即模拟该次尝试失败。 */
     beforeEnsureRun?(conversationId: string, attempt: number): Promise<void>;
+    /** Called after a run job read the run's status, before it takes the conversation lock. */
+    afterRunRead?(runId: string, conversationId: string): Promise<void>;
+    /** Called with the conversation lock held, before a queued run's `run_started` is written. */
+    beforeRunStarted?(runId: string, conversationId: string): Promise<void>;
+    /** Called with the conversation lock held, before a queued run's status becomes `running`. */
+    beforeRunning?(runId: string, conversationId: string): Promise<void>;
 }
 /** 处理函数的返回值：`ensure` 表示任务完成后再调用一次 ensureRun。 */
 export type ProcessResult = "ensure" | undefined;
@@ -65,6 +73,10 @@ export declare class RunWorker {
     private readonly skillsCatalog;
     /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
     private readonly runContext;
+    /** Run start's plugin context (memory plugin spec §6.1): the `context@1` providers' text. */
+    private readonly pluginContext;
+    /** The run's resolved tools, for the plugin context's `tools` (chat runs with providers). */
+    private readonly tools;
     private readonly finisher;
     readonly txHost: TransactionHost;
     /** The steps' live drafts this process writes for the runs it executes. */
@@ -93,7 +105,11 @@ export declare class RunWorker {
     /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
     skillsCatalog: Pick<SkillsCatalogService, "record">, 
     /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
-    runContext: Pick<RunContextService, "record">, finisher: Pick<RunFinish, "finish">, txHost: TransactionHost, 
+    runContext: Pick<RunContextService, "record">, 
+    /** Run start's plugin context (memory plugin spec §6.1): the `context@1` providers' text. */
+    pluginContext: Pick<PluginContextService, "record">, 
+    /** The run's resolved tools, for the plugin context's `tools` (chat runs with providers). */
+    tools: Pick<ToolRegistry, "forAgent">, finisher: Pick<RunFinish, "finish">, txHost: TransactionHost, 
     /** The steps' live drafts this process writes for the runs it executes. */
     drafts: RunDrafts, hooks?: RunHooks | undefined);
     private get db();
@@ -123,8 +139,10 @@ export declare class RunWorker {
     /**
      * 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 terminal transaction owed the same stop (`stop-tree`), the
-     * backstop when this call never happens.
+     * running (agent map spec §5.4), unless a person stopped the run: then the sub-agents of its
+     * windows stop too, also one it dispatched after the stop read the tree (agent map spec §6,
+     * changed in acceptance 2026-11-13). The terminal transaction owed the same stops
+     * (`stop-tree`), the backstop when this call never happens.
      */
     private stopChildren;
     /**
@@ -159,6 +177,11 @@ export declare class RunWorker {
     process(job: Job<RunJobData>, token: string | undefined): Promise<ProcessResult>;
     private execute;
     private completed;
+    /**
+     * The run's extension tool keys by plugin, resolved as a chat run's first step lists them
+     * (disabled tools, org switches, the conversation's source): a provider's `tools`.
+     */
+    private pluginToolKeys;
     /**
      * 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" }`
@@ -167,6 +190,12 @@ export declare class RunWorker {
      * handles it). Resolved for the conversation's org (its effective provider config).
      */
     private fallBackIfUnavailable;
+    /**
+     * Whether the run is gone or terminal, read in the caller's transaction under the locks
+     * (conversation, then run, as `RunFinish.finishIn`): the job read its status before taking the
+     * conversation lock, and a stop may have ended it since.
+     */
+    private endedUnderLocks;
     /**
      * `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.