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

package/dist/runtime/model-call.d.ts

@@ -1,4 +1,4 @@
-import { type ContentBlock, type Logger, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type ConversationSource, type Logger, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import type { AppendEvent, EventLog } from "../conversations/event-log.js";
 import { type ConversationEvent } from "../conversations/events.js";
@@ -104,6 +104,11 @@ export interface ModelStepInput {
     /** Hook payload scope: the run's agent, its trigger account and the conversation kind. */
     agentId?: string;
     accountId?: string;
+    /**
+     * The conversation's source (memory plugin spec §6.2): extension tools limited by
+     * `spec.sources` are listed by it.
+     */
+    source: ConversationSource;
     /** Hooks fire for `chat` and `subagent` (never for eval replays). */
     conversationKind?: ConversationKindForHooks;
     /** A sub-agent's run: where it was dispatched from (hook payloads carry it as `parent`). */

package/dist/runtime/model-call.js

@@ -159,6 +159,7 @@ wrapUpReason) {
             forkChild: input.parent?.forSkill === true,
             sandboxConversationId: input.parent?.rootConversationId ?? input.conversationId,
             replay: input.conversationKind === "eval",
+            source: input.source,
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {

package/dist/runtime/plugin-context.service.d.ts

@@ -0,0 +1,75 @@
+import { type ConversationSource } from "@capybara-hq/plugin-sdk";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionPointDefaults } from "../extensions/point-defaults.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import type { OrgRole } from "../orgs/roles.js";
+/** What a run start tells {@link PluginContextService.record}. */
+export interface PluginContextInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    agentId: string;
+    /** The run's agent definition name. */
+    agentName: string;
+    /** The conversation's owner (`conversations.account_id`) and display name. */
+    ownerAccountId: string;
+    ownerName: string;
+    /** The account whose message started the run. */
+    triggerAccountId: string;
+    source: ConversationSource;
+    /** The trigger account's role in the org. */
+    role: OrgRole;
+    /** The conversation's kind: only a chat run asks the providers. */
+    kind: "chat" | "eval" | "subagent";
+    /**
+     * The keys of the run's resolved tool set, by plugin (resolved with `forAgent` once, and only
+     * when some provider is asked).
+     */
+    toolKeysByPlugin: () => Promise<Map<string, string[]>>;
+    /** Aborts every provider call (with its own time limit). */
+    signal: AbortSignal;
+}
+/**
+ * Run start's plugin context (memory plugin spec §6.1): asks every `context@1` provider enabled in
+ * the org (valid config) for its text, in parallel and outside any transaction, each under the
+ * run's signal and {@link CONTEXT_LIMITS}.timeoutMs; then appends a `plugin_context` event for each
+ * plugin whose text differs from the latest one it recorded in the conversation. Fail open: a
+ * provider that throws, times out or returns too much is skipped for this run (its earlier text
+ * stays in effect) and logged. A provider loaded here that recorded text but no longer serves the
+ * org (switched off, its stored org config or its effective config invalid) gets an empty event,
+ * so its text stops following summaries; a plugin not loaded on this replica is left alone
+ * (another replica may still load it during a rollout, and blanking it here would make its text
+ * flap), and so is one whose status could not be read (a transient read error must not flip the
+ * model's context). Chat runs only: an
+ * eval replay reads the recorded events, and a sub-agent gets no plugin context (spec §5.4).
+ */
+export declare class PluginContextService {
+    private readonly db;
+    private readonly eventLog;
+    readonly txHost: TransactionHost;
+    private readonly points;
+    private readonly registry;
+    private readonly log;
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify">, txHost: TransactionHost, points: Pick<ExtensionPointDefaults, "providersFor">, registry: Pick<ExtensionRegistry, "list">, log: KernelLogger);
+    /**
+     * Asks the providers and records what changed (see the class); notifies after the commit. False:
+     * the run had ended under the locks (a stop landed while the providers were asked), so nothing
+     * was appended and the run must not go on (as `RunContextService.record`).
+     */
+    record(input: PluginContextInput): Promise<boolean>;
+    /** One provider's call, bounded by the run's signal and the time limit. */
+    private ask;
+    /**
+     * One transaction under the conversation row lock (as `RunContextService`): compares each
+     * answer's hash with the plugin's latest `plugin_context` and appends the ones that differ (a
+     * plugin with no earlier event and no text writes nothing), plus an empty event for each plugin
+     * in `off` whose latest text is not empty. Idem key per run and plugin, so a retried run
+     * start finds its events or nothing changed. Returns the last seq written; `ended` when the run
+     * is terminal under the locks (the providers are asked outside the transaction, so a stop may
+     * have ended it meanwhile: nothing is appended after its end).
+     */
+    private append;
+}

package/dist/runtime/plugin-context.service.js

@@ -0,0 +1,220 @@
+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 { createHash } from "node:crypto";
+import { CONTEXT_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionPointDefaults } from "../extensions/point-defaults.js";
+import { ExtensionRegistry } from "../extensions/registry.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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { latestPluginContexts, pluginContextIdemKey } from "./context/plugin-context.js";
+import { runEndedIn } from "./run-status.js";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/**
+ * Run start's plugin context (memory plugin spec §6.1): asks every `context@1` provider enabled in
+ * the org (valid config) for its text, in parallel and outside any transaction, each under the
+ * run's signal and {@link CONTEXT_LIMITS}.timeoutMs; then appends a `plugin_context` event for each
+ * plugin whose text differs from the latest one it recorded in the conversation. Fail open: a
+ * provider that throws, times out or returns too much is skipped for this run (its earlier text
+ * stays in effect) and logged. A provider loaded here that recorded text but no longer serves the
+ * org (switched off, its stored org config or its effective config invalid) gets an empty event,
+ * so its text stops following summaries; a plugin not loaded on this replica is left alone
+ * (another replica may still load it during a rollout, and blanking it here would make its text
+ * flap), and so is one whose status could not be read (a transient read error must not flip the
+ * model's context). Chat runs only: an
+ * eval replay reads the recorded events, and a sub-agent gets no plugin context (spec §5.4).
+ */
+let PluginContextService = class PluginContextService {
+    db;
+    eventLog;
+    txHost;
+    points;
+    registry;
+    log;
+    constructor(db, eventLog, txHost, points, registry, log) {
+        this.db = db;
+        this.eventLog = eventLog;
+        this.txHost = txHost;
+        this.points = points;
+        this.registry = registry;
+        this.log = log;
+    }
+    /**
+     * Asks the providers and records what changed (see the class); notifies after the commit. False:
+     * the run had ended under the locks (a stop landed while the providers were asked), so nothing
+     * was appended and the run must not go on (as `RunContextService.record`).
+     */
+    async record(input) {
+        if (input.kind !== "chat")
+            return true;
+        let found;
+        try {
+            found = await this.points.providersFor(input.orgId, "context");
+        }
+        catch (err) {
+            // fail open: without the org's providers nothing is asked and nothing is switched off
+            this.log.warn("context providers could not be listed; plugin context left as recorded", {
+                orgId: input.orgId,
+                conversationId: input.conversationId,
+                runId: input.runId,
+                err,
+            });
+            return true;
+        }
+        const { providers } = found;
+        const tools = providers.length > 0 ? await input.toolKeysByPlugin() : new Map();
+        const answers = await Promise.all(providers.map(async (p) => {
+            const answer = await this.ask(p, input, tools.get(p.extension) ?? []);
+            if (!answer.ok) {
+                this.log.warn("context provider skipped for this run", {
+                    orgId: input.orgId,
+                    conversationId: input.conversationId,
+                    runId: input.runId,
+                    plugin: p.extension,
+                    reason: answer.reason,
+                });
+            }
+            return [p.extension, answer];
+        }));
+        const texts = new Map();
+        for (const [plugin, answer] of answers)
+            if (answer.ok)
+                texts.set(plugin, answer.text);
+        const serving = new Set(providers.map((p) => p.extension));
+        const off = new Set(this.registry
+            .list("context")
+            .map((e) => e.plugin)
+            // a provider whose status could not be read (a transient error) keeps its recorded text
+            .filter((plugin) => !serving.has(plugin) && !found.failed.has(plugin)));
+        // nothing answered and nothing to switch off: no transaction, no row lock
+        if (texts.size === 0 && off.size === 0)
+            return true;
+        const seq = await this.append(input, texts, off);
+        if (seq === "ended")
+            return false;
+        if (seq !== null)
+            await this.eventLog.notify(input.conversationId, seq);
+        return true;
+    }
+    /** One provider's call, bounded by the run's signal and the time limit. */
+    async ask(p, input, tools) {
+        const signal = AbortSignal.any([input.signal, AbortSignal.timeout(CONTEXT_LIMITS.timeoutMs)]);
+        let result;
+        try {
+            result = await untilAborted(Promise.resolve().then(() => p.impl.provide({
+                orgId: input.orgId,
+                accountId: input.triggerAccountId,
+                agentId: input.agentId,
+                agentName: input.agentName,
+                conversationId: input.conversationId,
+                runId: input.runId,
+                source: input.source,
+                role: input.role,
+                ownerAccountId: input.ownerAccountId,
+                ownerName: input.ownerName,
+                tools,
+                config: p.config,
+                signal,
+            })), signal);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                return { ok: false, reason: input.signal.aborted ? "run aborted" : "timed out" };
+            }
+            return { ok: false, reason: `threw: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (result === null)
+            return { ok: true, text: "" };
+        const text = result?.text;
+        if (typeof text !== "string")
+            return { ok: false, reason: "returned no text" };
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes > CONTEXT_LIMITS.maxBytes) {
+            return { ok: false, reason: `text of ${bytes} bytes is over ${CONTEXT_LIMITS.maxBytes}` };
+        }
+        return { ok: true, text };
+    }
+    /**
+     * One transaction under the conversation row lock (as `RunContextService`): compares each
+     * answer's hash with the plugin's latest `plugin_context` and appends the ones that differ (a
+     * plugin with no earlier event and no text writes nothing), plus an empty event for each plugin
+     * in `off` whose latest text is not empty. Idem key per run and plugin, so a retried run
+     * start finds its events or nothing changed. Returns the last seq written; `ended` when the run
+     * is terminal under the locks (the providers are asked outside the transaction, so a stop may
+     * have ended it meanwhile: nothing is appended after its end).
+     */
+    async append(input, texts, off) {
+        const t = this.db.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", input.conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (await runEndedIn(t, input.runId))
+            return "ended";
+        const rows = await t
+            .selectFrom("conversation_events")
+            .select(["seq", "payload"])
+            .where("conversation_id", "=", input.conversationId)
+            .where("type", "=", "plugin_context")
+            .orderBy("seq", "asc")
+            .execute();
+        const latest = latestPluginContexts(rows.map((r) => ({ type: "plugin_context", seq: Number(r.seq), payload: r.payload })), Number.POSITIVE_INFINITY);
+        const next = new Map(texts);
+        for (const [plugin, prev] of latest) {
+            if (off.has(plugin) && prev.text !== "")
+                next.set(plugin, "");
+        }
+        const changed = [...next]
+            .filter(([plugin, text]) => {
+            const prev = latest.get(plugin);
+            return prev === undefined ? text !== "" : prev.hash !== sha256(text);
+        })
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        if (changed.length === 0)
+            return null;
+        const written = await this.eventLog.appendIn(input.conversationId, changed.map(([plugin, text]) => ({
+            type: "plugin_context",
+            runId: input.runId,
+            idemKey: pluginContextIdemKey(input.runId, plugin),
+            payload: { plugin, text, hash: sha256(text) },
+        })));
+        return Math.max(...written.map((e) => e.seq));
+    }
+};
+__decorate([
+    Transactional()
+], PluginContextService.prototype, "append", null);
+PluginContextService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(TransactionHost)),
+    __param(3, Inject(ExtensionPointDefaults)),
+    __param(4, Inject(ExtensionRegistry)),
+    __param(5, Inject(KERNEL_LOGGER))
+], PluginContextService);
+export { PluginContextService };
+/** `p`, or a rejection once `signal` aborts (a provider that ignores its signal never holds a run). */
+function untilAborted(p, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}

package/dist/runtime/run-context.service.d.ts

@@ -41,12 +41,16 @@ export declare class RunContextService {
     private readonly now;
     constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify">, txHost: TransactionHost, now?: () => number);
     private clock;
-    /** Records the run's context (see the class) and notifies after the commit. */
-    record(input: RunContextInput): Promise<void>;
+    /**
+     * Records the run's context (see the class) and notifies after the commit. False: the run had
+     * ended (a stop got there first), so nothing was appended and the run must not go on.
+     */
+    record(input: RunContextInput): Promise<boolean>;
     /**
      * One transaction under the conversation row lock (as `lockLatestCatalog`): fold, read the
      * current values, append when something differs, with the idem key `run_context:<runId>` (a
-     * retried run start finds its event, or finds nothing changed). Returns the seq written.
+     * retried run start finds its event, or finds nothing changed). Returns the seq written;
+     * `ended` when the run is terminal under the locks (nothing is appended after its end).
      */
     private append;
     /** A root run: agent, org, and the date, zone and language of the run's person (§3.4). */

package/dist/runtime/run-context.service.js

@@ -17,6 +17,7 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
 import { isTimeZone } from "../time-zone.js";
 import { currentRunContext, dateIn, runContextChange, sanitizeSenderName, snapshotDescription, } from "./context/run-context.js";
+import { runEndedIn } from "./run-status.js";
 /**
  * Optional provider: the clock run start reads the date from and the `CurrentTime` builtin reads
  * the time from (default `Date.now`; tests).
@@ -46,16 +47,23 @@ let RunContextService = class RunContextService {
     clock() {
         return new Date(this.now());
     }
-    /** Records the run's context (see the class) and notifies after the commit. */
+    /**
+     * Records the run's context (see the class) and notifies after the commit. False: the run had
+     * ended (a stop got there first), so nothing was appended and the run must not go on.
+     */
     async record(input) {
         const seq = await this.append(input);
+        if (seq === "ended")
+            return false;
         if (seq !== null)
             await this.eventLog.notify(input.conversationId, seq);
+        return true;
     }
     /**
      * One transaction under the conversation row lock (as `lockLatestCatalog`): fold, read the
      * current values, append when something differs, with the idem key `run_context:<runId>` (a
-     * retried run start finds its event, or finds nothing changed). Returns the seq written.
+     * retried run start finds its event, or finds nothing changed). Returns the seq written;
+     * `ended` when the run is terminal under the locks (nothing is appended after its end).
      */
     async append(input) {
         const t = this.db.db;
@@ -65,6 +73,8 @@ let RunContextService = class RunContextService {
             .where("id", "=", input.conversationId)
             .forUpdate()
             .executeTakeFirst();
+        if (await runEndedIn(t, input.runId))
+            return "ended";
         const prev = await foldOf(t, input.conversationId);
         const next = input.subagent === undefined
             ? await this.rootContext(t, input)

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

@@ -17,7 +17,7 @@ export declare class RunControl {
     /** Owes a deleted root's tree stop in the delete's transaction. */
     private readonly outbox;
     private readonly log;
-    constructor(queue: Pick<RunQueue, "ensureRun" | "oweEnsureRun" | "abortIfOrphaned" | "wakeHeldTree" | "oweHeldTreeIn">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, 
+    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. */
@@ -61,6 +61,11 @@ export declare class RunControl {
      * 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. The stop's transaction owes the IM delivery that

package/dist/runtime/run-control.js

@@ -110,6 +110,19 @@ let RunControl = class RunControl {
         }
         return r;
     }
+    /**
+     * 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 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

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

@@ -58,8 +58,8 @@ export declare class RunFinish {
      * 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
+     * right after its commit: `stop-tree` when an active fork child remains or a run a person
+     * stopped (a root's or a sub-agent's) 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).

package/dist/runtime/run-finish.js

@@ -63,8 +63,8 @@ let RunFinish = class RunFinish {
      * 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
+     * right after its commit: `stop-tree` when an active fork child remains or a run a person
+     * stopped (a root's or a sub-agent's) 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).
@@ -102,9 +102,14 @@ let RunFinish = class RunFinish {
         const [ev] = await this.eventLog.appendIn(a.conversationId, [
             { ...a.event, runId: a.runId, idemKey: `${a.event.type}:${a.runId}` },
         ]);
+        // a root run a person stopped holds the root's tree (agent map spec §6, acceptance
+        // 2026-11-13): marked with its terminal state, under the same row lock, so no wake decided
+        // after this commit starts the root from a sub-agent's delivery
+        const holdTree = conv?.kind === "chat" && personStopped(a.event);
         await t
             .updateTable("conversations")
             .set({
+            ...(holdTree && { tree_stopped_at: sql `now()` }),
             consumed_seq: a.floorToTrigger === false
                 ? sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint)`
                 : sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint, (SELECT r.trigger_seq FROM capybara.runs r WHERE r.id = ${a.runId}))`,
@@ -145,8 +150,8 @@ let RunFinish = class RunFinish {
             .where("cr.status", "in", ACTIVE_RUN_STATUSES)
             .limit(1)
             .executeTakeFirst();
-        const stoppedWithChildren = kind === "subagent" &&
-            personStopped(a.event) &&
+        // a root's too (agent map spec §6, changed in acceptance 2026-11-13)
+        const stoppedWithChildren = personStopped(a.event) &&
             (await t
                 .selectFrom("conversations")
                 .select("id")
@@ -186,8 +191,8 @@ RunFinish = __decorate([
 ], 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).
+ * A `run_aborted` a person caused (an account and no `detail`): a run stopped that way stops its
+ * descendants (`Waits.stopDescendantsOfStopped`, agent map spec §6; a root's, those of its windows).
  */
 function personStopped(event) {
     if (event.type !== "run_aborted")

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

@@ -15,10 +15,7 @@ export declare const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
 export declare const runQueueNameFor: (kind: ConversationKind) => typeof RUN_QUEUE_NAME | typeof SUBAGENT_RUN_QUEUE_NAME;
 /** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
 export declare const ACTIVE_RUN_STATUSES: readonly ["queued", "running", "waiting"];
-/** 运行的终态。 */
-export type TerminalStatus = "completed" | "failed" | "aborted";
-/** The terminal run statuses (here, not in `run-finish.ts`, which the sub-agent modules import). */
-export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+export { TERMINAL_STATUSES, type TerminalStatus } from "./run-status.js";
 /**
  * Locks a run's approval and input request rows (`FOR UPDATE`, in id order) in the caller's
  * transaction, after its conversation row and before its run row: the one lock order of every path
@@ -89,7 +86,27 @@ export declare class RunJobs {
     owe(data: RunJobData, jobId: string, kind: ConversationKind, orgId: string): Promise<boolean>;
     /** {@link oweEnsureRun} in the caller's transaction. */
     oweEnsureRun(conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
+    /**
+     * Owes the delayed `bg-wake` job at the end of the conversation's wake window in the caller's
+     * transaction (the `ensureRun` that decided `later`): one job per conversation and window end
+     * ({@link bgWakeJobId}), so finishes inside one window share it; `retry` > 0 is a job that fired
+     * before its window ended. The relay adds it with the remaining delay (a row due later skips the
+     * fast path); `runAt` carries {@link WAKE_JOB_MARGIN_MS}, since the window is read on the
+     * database's clock and the delay runs on this process's and Redis's. Every `ensureRun` inside the
+     * window (each append that calls it) owes it again: a no-op while the row is pending, and once it
+     * was delivered a new row whose add BullMQ dedupes by the job id while the delayed job exists.
+     */
+    oweBgWake(conversationId: string, w: {
+        windowEnd: number;
+        delayMs: number;
+    }, retry: number, orgId: string): Promise<boolean>;
 }
+/**
+ * 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`).
+ */
+export declare const WAKE_JOB_MARGIN_MS = 1000;
 /**
  * What {@link RunResume.resumeIn} found: `queued`, the run was waiting on nothing else and now is
  * queued with its resume job owed; `still-running`, the run has not reached `waiting` yet (its

package/dist/runtime/run-jobs.js

@@ -10,6 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
+import { BG_WAKE_JOB, bgWakeJobId } from "../background/wake-rules.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";
@@ -29,12 +30,8 @@ export const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
 export const runQueueNameFor = (kind) => kind === "subagent" ? SUBAGENT_RUN_QUEUE_NAME : RUN_QUEUE_NAME;
 /** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
 export const ACTIVE_RUN_STATUSES = ["queued", "running", "waiting"];
-/** The terminal run statuses (here, not in `run-finish.ts`, which the sub-agent modules import). */
-export const TERMINAL_STATUSES = new Set([
-    "completed",
-    "failed",
-    "aborted",
-]);
+// The terminal run statuses (here, not in `run-finish.ts`, which the sub-agent modules import)
+export { TERMINAL_STATUSES } from "./run-status.js";
 /**
  * Locks a run's approval and input request rows (`FOR UPDATE`, in id order) in the caller's
  * transaction, after its conversation row and before its run row: the one lock order of every path
@@ -144,6 +141,26 @@ let RunJobs = class RunJobs {
     oweEnsureRun(conversationId, seq, orgId) {
         return oweEnsureRun(this.outbox, conversationId, seq, orgId);
     }
+    /**
+     * Owes the delayed `bg-wake` job at the end of the conversation's wake window in the caller's
+     * transaction (the `ensureRun` that decided `later`): one job per conversation and window end
+     * ({@link bgWakeJobId}), so finishes inside one window share it; `retry` > 0 is a job that fired
+     * before its window ended. The relay adds it with the remaining delay (a row due later skips the
+     * fast path); `runAt` carries {@link WAKE_JOB_MARGIN_MS}, since the window is read on the
+     * database's clock and the delay runs on this process's and Redis's. Every `ensureRun` inside the
+     * window (each append that calls it) owes it again: a no-op while the row is pending, and once it
+     * was delivered a new row whose add BullMQ dedupes by the job id while the delayed job exists.
+     */
+    oweBgWake(conversationId, w, retry, orgId) {
+        return this.outbox.add({
+            queue: MAINTENANCE_QUEUE_NAME,
+            name: BG_WAKE_JOB,
+            jobId: bgWakeJobId(conversationId, w.windowEnd, retry),
+            data: { conversationId, ...(retry > 0 && { retry }) },
+            runAt: new Date(Date.now() + w.delayMs + WAKE_JOB_MARGIN_MS),
+            orgId,
+        });
+    }
 };
 RunJobs = __decorate([
     Injectable(),
@@ -153,6 +170,12 @@ RunJobs = __decorate([
     __param(3, Inject(OutboxService))
 ], RunJobs);
 export { RunJobs };
+/**
+ * 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`).
+ */
+export const WAKE_JOB_MARGIN_MS = 1000;
 /**
  * The resume of a waiting run (transactional outbox spec §6 "Resumes and timeouts", "Decisions
  * resume in their own transaction"), in the caller's transaction. A decision (approvals, questions,

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

@@ -13,7 +13,7 @@ import { RunFinish } from "./run-finish.js";
 import { RunJobs } from "./run-jobs.js";
 import { RunQueue } from "./run-queue.js";
 import { Waits } from "./waits.js";
-/** The check's `@LockedInterval` job name (its run lock key is the default `cron:run-orphan-check`). */
+/** The check's `@LockedInterval` job name (its run lock key: `cron:run-orphan-check`). */
 export declare const RUN_ORPHAN_CHECK_JOB = "run-orphan-check";
 /** The check's period: a fixed constant, not a config field. */
 export declare const RUN_ORPHAN_CHECK_PERIOD_MS = 60000;
@@ -55,7 +55,10 @@ export interface OrphanCandidate {
 /**
  * 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 declare function orphanCandidates(db: KernelSchemaDb, statuses: readonly ("queued" | "running")[], minAgeMs: number, limit: number, after?: Pick<OrphanCandidate, "since" | "runId">): Promise<OrphanCandidate[]>;
 /**
@@ -65,12 +68,12 @@ export declare function orphanCandidates(db: KernelSchemaDb, statuses: readonly
  */
 export declare function jobInOutbox(db: KernelSchemaDb, queue: string, jobId: string): Promise<boolean>;
 /**
- * The `queued` runs (in their state for over `minAgeMs`) whose job is neither in the outbox
- * (owed, or dead) nor in BullMQ (`jobExists`), and that are still queued after both looks: the run
- * queue lost their jobs. The outbox is read before BullMQ (a row is deleted only after its job was added) and the
- * run again after both (a job that finished took its run out of `queued` first), so a run in
- * flight is never reported. The `run-orphan-check` uses it; so does the dual-replica test harness,
- * which asserts at its teardown that the kernel left none (`minAgeMs` 0).
+ * The `queued` runs (in their state for over `minAgeMs`) whose job is neither in the outbox (owed,
+ * or dead) nor in BullMQ (`jobExists`), and that are still queued after both looks: the run queue
+ * lost their jobs. The outbox is read before BullMQ (a row is deleted only after its job was added)
+ * and the run again after both (a job that finished took its run out of `queued` first), so a run
+ * in flight is never reported. The `run-orphan-check` uses it; so does the dual-replica test
+ * harness, which asserts at its teardown that the kernel left none (`minAgeMs` 0).
  */
 export declare function queuedRunsWithoutJob(db: KernelSchemaDb, jobExists: (queue: string, jobId: string) => Promise<boolean>, opts: {
     minAgeMs: number;
@@ -85,9 +88,9 @@ export declare function queuedRunsWithoutJob(db: KernelSchemaDb, jobExists: (que
  *   `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.