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

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.
      */
@@ -569,14 +555,15 @@ 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,
+     * 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`.
+     * 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)
@@ -678,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). */
@@ -705,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

@@ -139,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;
     /**
@@ -188,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.

package/dist/runtime/run-worker.js

@@ -209,8 +209,10 @@ let RunWorker = 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.
      */
     async stopChildren(runId) {
         try {
@@ -219,6 +221,12 @@ let RunWorker = class RunWorker {
         catch (err) {
             this.log.error("cannot stop the sub-agents of a finished run", { runId, err });
         }
+        try {
+            await this.waits.stopDescendantsOfStopped(runId);
+        }
+        catch (err) {
+            this.log.error("cannot stop the sub-agents of a stopped run", { runId, err });
+        }
     }
     /**
      * After a sub-agent run's terminal state committed (sub-agents spec §7.3): reports it to the
@@ -624,17 +632,23 @@ let RunWorker = class RunWorker {
                 if (toSeq !== undefined)
                     await this.eventLog.notify(conversationId, toSeq);
             }
-            // 技能目录快照（Ruling M17）：在置为 running 之前写，崩溃重试时仍走这里（幂等键去重）
-            await this.skillsCatalog.record({
+            // Skills catalog snapshot (ruling M17): written before the run is running, and again on a
+            // crash retry (deduped by its idem key). Both records re-read the run under the conversation
+            // and run row locks in their append transactions: a stop that ended it meanwhile (a retried
+            // start reads `queued` before any lock) wins, nothing is appended after its end, and the run
+            // never starts.
+            const catalogged = await this.skillsCatalog.record({
                 orgId: conv.org_id,
                 agentId: conv.agent_id,
                 conversationId,
                 runId,
                 agent,
             }, { log: this.log });
+            if (!catalogged)
+                return "finished";
             // 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({
+            const contexted = await this.runContext.record({
                 orgId: conv.org_id,
                 conversationId,
                 runId,
@@ -648,9 +662,12 @@ let RunWorker = class RunWorker {
                     },
                 }),
             });
+            if (!contexted)
+                return "finished";
             // plugin context (memory plugin spec §6.1): after the run context, still before the run is
-            // running; the providers are asked outside any transaction, a chat run only
-            await this.pluginContext.record({
+            // running; the providers are asked outside any transaction, a chat run only, so a stop may
+            // end the run meanwhile: its append transaction re-reads the run under the locks
+            const pluginContexted = await this.pluginContext.record({
                 orgId: conv.org_id,
                 conversationId,
                 runId,
@@ -667,6 +684,8 @@ let RunWorker = class RunWorker {
                 // the run's own abort watch starts with its execution below: until then, the shutdown
                 signal: state.shutdown.signal,
             });
+            if (!pluginContexted)
+                return "finished";
             await this.hooks?.beforeRunning?.(runId, conversationId);
             // never over a terminal status: a run finished meanwhile stays finished
             const updated = await this.db
@@ -905,28 +924,34 @@ let RunWorker = class RunWorker {
         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.
+     * 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.
      */
-    async appendRunStarted(conversationId, run, 
-    /** The definition so far (a sub-agent's frozen one is final). */
-    current, saved) {
-        const t = this.db;
-        await t
+    async endedUnderLocks(conversationId, runId) {
+        await this.db
             .selectFrom("conversations")
             .select("id")
             .where("id", "=", conversationId)
             .forUpdate()
             .execute();
-        // the run's status again under the locks (conversation, then run, as `RunFinish.finishIn`):
-        // the job read it before taking the conversation lock, and a stop may have ended it since
-        const row = await t
+        const row = await this.db
             .selectFrom("runs")
             .select("status")
-            .where("id", "=", run.id)
+            .where("id", "=", runId)
             .forUpdate()
             .executeTakeFirst();
-        if (!row || TERMINAL_STATUSES.has(row.status)) {
+        return !row || TERMINAL_STATUSES.has(row.status);
+    }
+    /**
+     * `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;
+        if (await this.endedUnderLocks(conversationId, run.id)) {
             return { toSeq: undefined, agent: current, terminal: true };
         }
         const agent = saved !== undefined

package/dist/runtime/step-log.d.ts

@@ -9,10 +9,10 @@ import { UsageReportJobs } from "./usage-report-jobs.js";
 export type StepAuditEntry = Parameters<typeof audit>[1];
 /**
  * The writes of a run step that go to the event log together with another row, each in a
- * transaction of its own (the caller notifies the log after the commit): a model call with the
- * tool definitions it sent, a denial with its audit row, usage events with their owed
- * `usage.report` deliveries (transactional outbox spec §8.1), and a sub-agent's usage counted on
- * its parent run. The step functions (`model-call.ts`, `hook-calls.ts`) reach it through their deps.
+ * transaction of its own (the caller notifies the log after the commit): a model call with the tool
+ * definitions it sent, a denial with its audit row, usage events with their owed `usage.report`
+ * deliveries (transactional outbox spec §8.1), and a sub-agent's usage counted on its parent run.
+ * The step functions (`model-call.ts`, `hook-calls.ts`) reach it through their deps.
  */
 export declare class StepLog {
     private readonly kdb;
@@ -35,7 +35,8 @@ export declare class StepLog {
      * the whole tree counts on one run): `counter.budgetRunId`, the run's own window
      * (`SubagentParent.budgetRunId`), else the parent run's ({@link budgetRunOf}). A usage event
      * already in the log (an idempotent hit after a crash) adds nothing, so each call counts exactly
-     * once; the new usage events' `usage.report` deliveries are owed in the same transaction. Returns what was written (hits included) and the highest new seq (null: nothing new).
+     * once; the new usage events' `usage.report` deliveries are owed in the same transaction. Returns
+     * what was written (hits included) and the highest new seq (null: nothing new).
      */
     appendCounted(conversationId: string, counter: {
         parentRunId: string;

package/dist/runtime/step-log.js

@@ -20,10 +20,10 @@ import { budgetRunOf } from "./subagents/limits.js";
 import { UsageReportJobs, UsageReportJobsModule } from "./usage-report-jobs.js";
 /**
  * The writes of a run step that go to the event log together with another row, each in a
- * transaction of its own (the caller notifies the log after the commit): a model call with the
- * tool definitions it sent, a denial with its audit row, usage events with their owed
- * `usage.report` deliveries (transactional outbox spec §8.1), and a sub-agent's usage counted on
- * its parent run. The step functions (`model-call.ts`, `hook-calls.ts`) reach it through their deps.
+ * transaction of its own (the caller notifies the log after the commit): a model call with the tool
+ * definitions it sent, a denial with its audit row, usage events with their owed `usage.report`
+ * deliveries (transactional outbox spec §8.1), and a sub-agent's usage counted on its parent run.
+ * The step functions (`model-call.ts`, `hook-calls.ts`) reach it through their deps.
  */
 let StepLog = class StepLog {
     kdb;
@@ -53,7 +53,8 @@ let StepLog = class StepLog {
      * the whole tree counts on one run): `counter.budgetRunId`, the run's own window
      * (`SubagentParent.budgetRunId`), else the parent run's ({@link budgetRunOf}). A usage event
      * already in the log (an idempotent hit after a crash) adds nothing, so each call counts exactly
-     * once; the new usage events' `usage.report` deliveries are owed in the same transaction. Returns what was written (hits included) and the highest new seq (null: nothing new).
+     * once; the new usage events' `usage.report` deliveries are owed in the same transaction. Returns
+     * what was written (hits included) and the highest new seq (null: nothing new).
      */
     async appendCounted(conversationId, counter, events) {
         const t = this.kdb.db;

package/dist/runtime/usage-report.d.ts

@@ -58,7 +58,9 @@ export declare function narrowPending(stored: readonly string[] | undefined, fai
  *   `model_usage` row and owes job `usage-model-<rowId>` with it; the payload
  *   (`purpose: "embedding"`, `eventId` = the row id, the calling `extension`, no conversation fields)
  *   is read from the row when the job runs, and the row's `reported_at` is set once nothing is left
- *   to deliver; a job that gives up after its last attempt sets `report_failed_at`.
+ *   to deliver; a job that gives up after its last attempt sets `report_failed_at`. A row with
+ *   `reported_at IS NULL` is not necessarily pending: no job is owed when no enabled extension
+ *   subscribed to `usage.report` at the time of the call, and such a row is never reported.
  */
 export declare class UsageReporter {
     private readonly kdb;

package/dist/runtime/usage-report.js

@@ -113,7 +113,9 @@ export function narrowPending(stored, failed) {
  *   `model_usage` row and owes job `usage-model-<rowId>` with it; the payload
  *   (`purpose: "embedding"`, `eventId` = the row id, the calling `extension`, no conversation fields)
  *   is read from the row when the job runs, and the row's `reported_at` is set once nothing is left
- *   to deliver; a job that gives up after its last attempt sets `report_failed_at`.
+ *   to deliver; a job that gives up after its last attempt sets `report_failed_at`. A row with
+ *   `reported_at IS NULL` is not necessarily pending: no job is owed when no enabled extension
+ *   subscribed to `usage.report` at the time of the call, and such a row is never reported.
  */
 let UsageReporter = class UsageReporter {
     kdb;
@@ -359,7 +361,7 @@ let UsageReporter = class UsageReporter {
     /** One delivery job (the `@Processor` of {@link USAGE_REPORT_QUEUE} calls it). */
     async process(j, token) {
         const payload = await this.payloadOfJob(j.data);
-        // conversation (or org) deleted meanwhile: nothing to report
+        // conversation deleted meanwhile: nothing to report
         if (payload === null)
             return;
         const subscribers = await this.subscribers(payload.orgId);

package/dist/runtime/waits.d.ts

@@ -230,6 +230,13 @@ export declare class Waits implements OnApplicationShutdown {
      * background tasks of every covered sub-agent conversation stop, whether it was running or idle.
      * Returns the number of runs asked to stop.
      *
+     * `windowsUpTo` (a root run's id; only after that root run a person stopped ended,
+     * {@link stopDescendantsOfStopped}) narrows the stop to the runs of the budget windows opened up
+     * to that run (`runs.budget_run_id`, agent map spec §6): a run of a window a later root run
+     * opened (the person's next message, started meanwhile) is never stopped by the late call, and
+     * the background task sweep is left out (a stopped child's own end stops its tasks,
+     * {@link childFinished}).
+     *
      * Lock order: nothing is held across runs. Each run's stop is its own transaction (or none), and
      * one that writes the terminal state locks that run's conversation row, then its run row, the
      * order of `StepLog.appendCounted` (conversation row, then the root's budget run row) and of
@@ -238,14 +245,17 @@ export declare class Waits implements OnApplicationShutdown {
      */
     stopTree(conversationId: string, byAccountId: string | null, opts?: {
         includeSelf?: boolean;
+        windowsUpTo?: string;
     }): Promise<number>;
     /**
-     * After a sub-agent run's terminal commit (its worker): a run a person stopped (`run_aborted`
-     * with an account and no `detail`; only {@link stopTree} stops a sub-agent's run that way) stops
-     * the active runs below its conversation as well, so a descendant it dispatched after the tree
-     * stop read the tree still stops (dispatch needs its run `running`, so after its terminal commit
-     * the set is final). Any other end leaves its children running (agent map spec §5.4). Returns
-     * the number of runs asked to stop. A root conversation's run never stops its children here.
+     * After a run's terminal commit (its worker): a run a person stopped (`run_aborted` with an
+     * account and no `detail`; {@link stopTree} or a person's stop of the root) stops the active runs
+     * below its conversation as well, so a descendant it dispatched after the tree stop read the tree
+     * still stops (dispatch needs its run `running`, so after its terminal commit the set is final).
+     * A root's run stops only the runs of the budget windows up to it (`windowsUpTo`): the person's
+     * next message may already have started a new run with sub-agents of its own (agent map spec §6,
+     * changed in acceptance 2026-11-13). Any other end leaves its children running (§5.4). Returns
+     * the number of runs asked to stop.
      */
     stopDescendantsOfStopped(runId: string): Promise<number>;
     /**