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

package/dist/admin/outbox-dead.service.d.ts

@@ -50,8 +50,9 @@ export declare class OutboxDeadService {
      * the fast path after the commit; the relay delivers it otherwise. When the same (queue, job id)
      * is owed by a pending row already, the dead row is deleted instead (`already_owed`). A pending
      * row added between the check and the update fails the update on the unique index: the retry
-     * then runs once more and takes the `already_owed` branch. `outbox.not_found` (404) when no dead
-     * row has the id.
+     * then runs once more and takes the `already_owed` branch; a second conflict on that run (the
+     * job owed, delivered and owed again meanwhile) is `conflict` (409), the dead row left as it was.
+     * `outbox.not_found` (404) when no dead row has the id.
      */
     retry(id: string, actor: WriteActor, detail?: Record<string, unknown>): Promise<{
         outcome: OutboxRetryOutcome;
@@ -61,6 +62,9 @@ export declare class OutboxDeadService {
     discard(id: string, actor: WriteActor, detail?: Record<string, unknown>): Promise<void>;
     /** The dead row `id`, locked for the transaction; `outbox.not_found` when it is not dead. */
     private lockDead;
-    /** A platform-level audit event (no org: the outbox is the deployment's), naming the job. */
+    /**
+     * A platform-level audit event (no org: the outbox is the deployment's), naming the job. The
+     * caller's detail (`via`, `operation`) comes first, so it cannot override the row's fields.
+     */
     private audit;
 }

package/dist/admin/outbox-dead.service.js

@@ -89,8 +89,9 @@ let OutboxDeadService = class OutboxDeadService {
      * the fast path after the commit; the relay delivers it otherwise. When the same (queue, job id)
      * is owed by a pending row already, the dead row is deleted instead (`already_owed`). A pending
      * row added between the check and the update fails the update on the unique index: the retry
-     * then runs once more and takes the `already_owed` branch. `outbox.not_found` (404) when no dead
-     * row has the id.
+     * then runs once more and takes the `already_owed` branch; a second conflict on that run (the
+     * job owed, delivered and owed again meanwhile) is `conflict` (409), the dead row left as it was.
+     * `outbox.not_found` (404) when no dead row has the id.
      */
     async retry(id, actor, detail = {}) {
         try {
@@ -99,7 +100,14 @@ let OutboxDeadService = class OutboxDeadService {
         catch (e) {
             if (!isPendingConflict(e))
                 throw e;
-            return this.retryOnce(id, actor, detail);
+        }
+        try {
+            return await this.retryOnce(id, actor, detail);
+        }
+        catch (e) {
+            if (!isPendingConflict(e))
+                throw e;
+            throw new ApiError("conflict", `The job of dead outbox row ${id} was owed again while it was retried; list the dead rows with GET /api/v1/admin/outbox/dead and retry or discard it again`);
         }
     }
     async retryOnce(id, actor, detail) {
@@ -125,7 +133,7 @@ let OutboxDeadService = class OutboxDeadService {
             outcome = "retried";
             afterCommit(() => this.fastPath([id]));
         }
-        await this.audit("outbox.retried", id, row, actor, { outcome, ...detail });
+        await this.audit("outbox.retried", id, row, actor, { ...detail, outcome });
         return { outcome };
     }
     /** Deletes a dead row: its job is never delivered. `outbox.not_found` (404) when none. */
@@ -147,7 +155,10 @@ let OutboxDeadService = class OutboxDeadService {
             throw notFound(id);
         return row;
     }
-    /** A platform-level audit event (no org: the outbox is the deployment's), naming the job. */
+    /**
+     * A platform-level audit event (no org: the outbox is the deployment's), naming the job. The
+     * caller's detail (`via`, `operation`) comes first, so it cannot override the row's fields.
+     */
     audit(action, id, row, actor, detail) {
         return audit(this.db.db, {
             actorAccountId: actor.accountId,
@@ -155,11 +166,11 @@ let OutboxDeadService = class OutboxDeadService {
             action,
             target: id,
             detail: {
+                ...detail,
                 queue: row.queue,
                 jobName: row.job_name,
                 jobId: row.job_id,
                 ...(row.org_id !== null && { orgId: row.org_id }),
-                ...detail,
             },
         });
     }

package/dist/admin/overview.service.d.ts

@@ -107,11 +107,11 @@ export declare function extensionReason(e: Pick<AdminExtensionView, "status" | "
 /** The problem of a provider in the platform view, or null (`org_configured` is not one). */
 export declare function providerProblem(p: ProviderStatus): AttentionProviderProblem | null;
 /**
- * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
- * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
- * lists, the dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing one is reported in
- * `unavailable`. Reads are not audited (decision D5) and not cached further (every source is PG
- * or already Redis-cached).
+ * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the sources
+ * the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached lists, the
+ * dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing
+ * one is reported in `unavailable`. Reads are not audited (decision D5) and not cached further
+ * (every source is PG or already Redis-cached).
  */
 export declare class AdminOverviewService {
     private readonly extensions;
@@ -136,7 +136,7 @@ export declare class AdminOverviewService {
     /**
      * The extensions needing a look, but not one pending approval whose plugin waits in the platform
      * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A
-     * config-declared extension has no catalog item and stays. Without the catalog nothing is left out.
+     * config-declared extension has no catalog item and stays. Without the catalog none is left out.
      */
     private extensionRows;
     /** Every live catalog item, page by page (the catalog lists by name). */

package/dist/admin/overview.service.js

@@ -53,11 +53,11 @@ export function providerProblem(p) {
     return p.models.some((m) => m.kind === "chat" && m.disabled !== true) ? null : "no_chat_model";
 }
 /**
- * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
- * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
- * lists, the dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing one is reported in
- * `unavailable`. Reads are not audited (decision D5) and not cached further (every source is PG
- * or already Redis-cached).
+ * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the sources
+ * the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached lists, the
+ * dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing
+ * one is reported in `unavailable`. Reads are not audited (decision D5) and not cached further
+ * (every source is PG or already Redis-cached).
  */
 let AdminOverviewService = class AdminOverviewService {
     extensions;
@@ -164,13 +164,13 @@ let AdminOverviewService = class AdminOverviewService {
     /**
      * The extensions needing a look, but not one pending approval whose plugin waits in the platform
      * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A
-     * config-declared extension has no catalog item and stays. Without the catalog nothing is left out.
+     * config-declared extension has no catalog item and stays. Without the catalog none is left out.
      */
     async extensionRows(items) {
         const [views, catalog] = await Promise.all([this.extensions.list(), items.catch(() => [])]);
         const inInbox = new Set(catalog.filter((i) => i.pending).map((i) => i.name));
         return views.flatMap((v) => {
-            // every status of extensionNeedsAction has a reason, and so has enabled with an invalid config
+            // every status of extensionNeedsAction has a reason, as has enabled with an invalid config
             const reason = extensionReason(v);
             if (reason === null)
                 return [];

package/dist/background/wake-rules.d.ts

@@ -54,6 +54,11 @@ export type WakeDecision = {
  * - the wake setting is on (the org's override, else `deploymentOn`);
  * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
  *   the whole tree, agent map spec §5.3);
+ * - for a `subagent_delivery` to the root: the root's tree is not stopped (`tree_stopped_at`, set by
+ *   a person's stop of the root and cleared by the root's next run; agent map spec §6, changed in
+ *   acceptance 2026-11-13): no sub-agent's finish or report, whenever its child finished, wakes a
+ *   root a person stopped, the delivery waits for the next run. A sub-agent of a stopped tree is
+ *   never woken here (`RunQueue.childWakeIn` refuses it first);
  * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
  *   the root);
  * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).

package/dist/background/wake-rules.js

@@ -38,6 +38,11 @@ const WAKE_EVENT_TYPES = ["background_task_finished", "subagent_delivery"];
  * - the wake setting is on (the org's override, else `deploymentOn`);
  * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
  *   the whole tree, agent map spec §5.3);
+ * - for a `subagent_delivery` to the root: the root's tree is not stopped (`tree_stopped_at`, set by
+ *   a person's stop of the root and cleared by the root's next run; agent map spec §6, changed in
+ *   acceptance 2026-11-13): no sub-agent's finish or report, whenever its child finished, wakes a
+ *   root a person stopped, the delivery waits for the next run. A sub-agent of a stopped tree is
+ *   never woken here (`RunQueue.childWakeIn` refuses it first);
  * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
  *   the root);
  * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).
@@ -68,21 +73,27 @@ export async function wakeDecisionIn(t, conv, consumed, deploymentOn, canSend) {
         .orderBy("e.seq", "desc")
         .limit(CANDIDATES)
         .execute();
-    const candidates = [...finishes, ...deliveries]
-        .sort((a, b) => Number(b.seq) - Number(a.seq))
-        .slice(0, CANDIDATES);
-    if (candidates.length === 0)
+    if (finishes.length === 0 && deliveries.length === 0)
         return null;
     const org = (await readOrgSettings(t, conv.orgId)).wakeOnBackgroundTask;
     if (!effectiveWakeOnBackgroundTask(deploymentOn, org))
         return null;
+    // read under the root's row lock when `conv` is the root (`RunQueue.ensureRunIn` holds it), so a
+    // person's stop of the tree (which writes `tree_stopped_at` on that row) is seen by every wake
+    // decided after its commit
     const root = await t
         .selectFrom("conversations")
-        .select(["queue_paused", "deleted_at"])
+        .select(["queue_paused", "deleted_at", "tree_stopped_at"])
         .where("id", "=", conv.rootId)
         .executeTakeFirst();
     if (!root || root.queue_paused || root.deleted_at !== null)
         return null;
+    const treeStopped = root.tree_stopped_at !== null;
+    const candidates = [...finishes, ...(treeStopped ? [] : deliveries)]
+        .sort((a, b) => Number(b.seq) - Number(a.seq))
+        .slice(0, CANDIDATES);
+    if (candidates.length === 0)
+        return null;
     let boundary;
     for (const c of candidates) {
         if (await canSend(c.account)) {

package/dist/catalog/marketplaces.service.d.ts

@@ -188,7 +188,7 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.19";
+    readonly sdk: "0.1.0-rc.20";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

package/dist/channels/channels.module.d.ts

@@ -9,14 +9,15 @@ import { ChannelOutbound } from "./outbound.js";
  * Channels on every role: the org's channel connections, inbound (dedupe and enqueue; the inbound
  * jobs), the outbound delivery, the producer of the channel queue `cap-kernel-channels`, the
  * anonymous guests. The roles' parts are the role modules': the queue's consumer
- * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the long-connection
- * supervisor and the webhook inbound the gateway role's (`GatewayModule`).
+ * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the
+ * long-connection supervisor and the webhook inbound the gateway role's (`GatewayModule`).
  */
 export declare class ChannelsModule {
 }
 /**
  * The consumer of `cap-kernel-channels`: deliveries (`DELIVER_JOB`, owed through the outbox or
- * hinted) and inbound jobs (`INBOUND_JOB`), both handled by {@link ChannelOutbound}.
+ * hinted), a connection's catch-up (`RESUME_JOB`, owed) and inbound jobs (`INBOUND_JOB`), all
+ * handled by {@link ChannelOutbound}.
  */
 export declare class ChannelsProcessor extends WorkerHost<Worker<ChannelJobData>> {
     private readonly outbound;
@@ -32,11 +33,11 @@ export declare class ChannelsProcessor extends WorkerHost<Worker<ChannelJobData>
  */
 export declare function channelsProcessorOptions(config: Pick<KernelConfig, "runtime" | "channels">): ProcessorWorkerOptions;
 /**
- * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's job
- * lock and stalled detection, the delivery backoff). Imported only by the worker role
- * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by itself:
- * the worker role (`WorkerRole`) starts it after the extension load; `ChannelOutbound.close` closes it
- * on stop.
+ * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's
+ * job lock and stalled detection, the delivery backoff). Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by
+ * itself: the worker role (`WorkerRole`) starts it after the extension load;
+ * `ChannelOutbound.close` closes it on stop.
  */
 export declare class ChannelWorkersModule {
     static forRoot(config: KernelConfig): DynamicModule;

package/dist/channels/channels.module.js

@@ -26,7 +26,7 @@ import { SchedulesModule } from "../schedules/schedules.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
-import { CHANNEL_QUEUE_NAME, ChannelJobs, DELIVER_JOB, INBOUND_JOB, } from "./jobs.js";
+import { CHANNEL_QUEUE_NAME, ChannelJobs, DELIVER_JOB, INBOUND_JOB, RESUME_JOB, } from "./jobs.js";
 import { ChannelOutbound, deliverBackoff } from "./outbound.js";
 import { AnonymousGuestLock, AnonymousGuests } from "./threads.js";
 /** The channel queue's registration (its producer here; the admin health reads its counts). */
@@ -35,8 +35,8 @@ const CHANNEL_QUEUE_MODULE = QueueModule.registerQueue(CHANNEL_QUEUE_NAME);
  * Channels on every role: the org's channel connections, inbound (dedupe and enqueue; the inbound
  * jobs), the outbound delivery, the producer of the channel queue `cap-kernel-channels`, the
  * anonymous guests. The roles' parts are the role modules': the queue's consumer
- * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the long-connection
- * supervisor and the webhook inbound the gateway role's (`GatewayModule`).
+ * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the
+ * long-connection supervisor and the webhook inbound the gateway role's (`GatewayModule`).
  */
 let ChannelsModule = class ChannelsModule {
 };
@@ -77,7 +77,8 @@ ChannelsModule = __decorate([
 export { ChannelsModule };
 /**
  * The consumer of `cap-kernel-channels`: deliveries (`DELIVER_JOB`, owed through the outbox or
- * hinted) and inbound jobs (`INBOUND_JOB`), both handled by {@link ChannelOutbound}.
+ * hinted), a connection's catch-up (`RESUME_JOB`, owed) and inbound jobs (`INBOUND_JOB`), all
+ * handled by {@link ChannelOutbound}.
  */
 let ChannelsProcessor = class ChannelsProcessor extends WorkerHost {
     outbound;
@@ -86,7 +87,7 @@ let ChannelsProcessor = class ChannelsProcessor extends WorkerHost {
         this.outbound = outbound;
     }
     process(job, token) {
-        if (job.name !== DELIVER_JOB && job.name !== INBOUND_JOB) {
+        if (job.name !== DELIVER_JOB && job.name !== INBOUND_JOB && job.name !== RESUME_JOB) {
             return Promise.reject(new UnrecoverableError(`unknown channel job "${job.name}"`));
         }
         return runJob(CHANNEL_QUEUE_NAME, job, () => this.outbound.process(job, token));
@@ -124,11 +125,11 @@ export function channelsProcessorOptions(config) {
     };
 }
 /**
- * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's job
- * lock and stalled detection, the delivery backoff). Imported only by the worker role
- * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by itself:
- * the worker role (`WorkerRole`) starts it after the extension load; `ChannelOutbound.close` closes it
- * on stop.
+ * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's
+ * job lock and stalled detection, the delivery backoff). Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by
+ * itself: the worker role (`WorkerRole`) starts it after the extension load;
+ * `ChannelOutbound.close` closes it on stop.
  */
 let ChannelWorkersModule = ChannelWorkersModule_1 = class ChannelWorkersModule {
     static forRoot(config) {

package/dist/channels/connections.service.d.ts

@@ -123,7 +123,7 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     private readonly registry;
     private readonly bus;
     private readonly redis;
-    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
+    /** A connection that can deliver again owes its conversations' catch-up (`oweResume`). */
     private readonly jobs;
     /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
     private readonly config;
@@ -138,8 +138,8 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     constructor(db: KernelDb, 
     /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
     orgLock: Pick<OrgLock, "lockAndAuthorize">, keyring: Keyring, registry: Pick<ExtensionRegistry, "list">, bus: ExtensionContext["bus"], redis: Pick<Redis, "del">, 
-    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
-    jobs: Pick<ChannelJobs, "resumeConnection">, 
+    /** A connection that can deliver again owes its conversations' catch-up (`oweResume`). */
+    jobs: Pick<ChannelJobs, "oweResume">, 
     /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
     config: Pick<KernelConfigService, "get">, events: Pick<KernelEvents, "on">, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */

package/dist/channels/connections.service.js

@@ -154,7 +154,7 @@ let ChannelConnections = class ChannelConnections {
     constructor(db, 
     /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
     orgLock, keyring, registry, bus, redis, 
-    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
+    /** A connection that can deliver again owes its conversations' catch-up (`oweResume`). */
     jobs, 
     /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
     config, events, 
@@ -546,11 +546,6 @@ let ChannelConnections = class ChannelConnections {
         }
         // A mode switch also reconnects: the holder drops the long connection when going to webhook (F9)
         await this.changed(id, rotated !== undefined || patch.status !== undefined || modeChanged);
-        if ((rotated || patch.status === "active") && row.status === "active") {
-            await this.jobs
-                .resumeConnection(id)
-                .catch((err) => this.log.warn("cannot resume channel deliveries", { err }));
-        }
         return { channel: await this.viewOf(row), verifySkipped };
     }
     /** The rows of {@link update}, in their own transaction (the caller publishes after the commit). */
@@ -592,6 +587,11 @@ let ChannelConnections = class ChannelConnections {
             .executeTakeFirst();
         if (!updated)
             throw notFound();
+        // can deliver again (re-enabled, or new credentials while active): the conversations that fell
+        // behind meanwhile are caught up by a job owed here (transactional outbox spec §3.1)
+        if ((rotated || patch.status === "active") && updated.status === "active") {
+            await this.jobs.oweResume(id, orgId, updated.updated_at);
+        }
         await audit(this.db.db, {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),

package/dist/channels/deliver-job.d.ts

@@ -4,15 +4,22 @@ import type { OutboxService } from "../infra/outbox/outbox.service.js";
  * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
  * domain. `jobs.ts` (the producer) re-exports these names.
  */
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+/** The channel queue (outbound deliveries and inbound jobs; no `:`), consumed only by workers. */
 export declare const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
+/** The delivery job's name. */
 export declare const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+/** The delivery job id (no `:`): one job per conversation and log position. */
 export declare const deliverJobId: (conversationId: string, seq: number) => string;
 export interface DeliverJobData {
     conversationId: string;
 }
+/** The catch-up job of a connection that can deliver again (re-enabled, credentials rotated). */
+export declare const RESUME_JOB = "channel-resume";
+/** Its job id: one per connection and update (`updated_at` in ms; no `:`). */
+export declare const resumeJobId: (connectionId: string, at: Date) => string;
+export interface ResumeJobData {
+    connectionId: string;
+}
 /**
  * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
  * the caller knows the conversation has a channel target. Shares the job id of

package/dist/channels/deliver-job.js

@@ -3,12 +3,16 @@
  * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
  * domain. `jobs.ts` (the producer) re-exports these names.
  */
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+/** The channel queue (outbound deliveries and inbound jobs; no `:`), consumed only by workers. */
 export const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
+/** The delivery job's name. */
 export const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+/** The delivery job id (no `:`): one job per conversation and log position. */
 export const deliverJobId = (conversationId, seq) => `deliver-${conversationId}-${seq}`;
+/** The catch-up job of a connection that can deliver again (re-enabled, credentials rotated). */
+export const RESUME_JOB = "channel-resume";
+/** Its job id: one per connection and update (`updated_at` in ms; no `:`). */
+export const resumeJobId = (connectionId, at) => `channel-resume-${connectionId}-${at.getTime()}`;
 /**
  * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
  * the caller knows the conversation has a channel target. Shares the job id of

package/dist/channels/jobs.d.ts

@@ -5,8 +5,8 @@ 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 { OutboxService } from "../infra/outbox/outbox.service.js";
-import { type DeliverJobData } from "./deliver-job.js";
-export { CHANNEL_QUEUE_NAME, DELIVER_JOB, type DeliverJobData, deliverJobId, oweDelivery, } from "./deliver-job.js";
+import { type DeliverJobData, type ResumeJobData } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, type DeliverJobData, deliverJobId, oweDelivery, RESUME_JOB, type ResumeJobData, resumeJobId, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -24,7 +24,7 @@ export interface InboundJobData {
     connectionId: string;
     event: InboundEvent;
 }
-export type ChannelJobData = DeliverJobData | InboundJobData;
+export type ChannelJobData = DeliverJobData | InboundJobData | ResumeJobData;
 /** 入站任务名。 */
 export declare const INBOUND_JOB = "inbound";
 /**
@@ -86,7 +86,14 @@ export declare class ChannelJobs implements OnApplicationShutdown {
      */
     enqueueInbound(connectionId: string, event: InboundEvent, jobId: string): Promise<void>;
     /**
-     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
+     * Owes the catch-up of a connection that can deliver again in the caller's transaction (the
+     * update that re-enabled it or rotated its credentials while active): the deliveries that ran
+     * while it could not deliver have ended, and nothing else finds the conversations lagging the log.
+     * `at` is the connection row's new `updated_at`.
+     */
+    oweResume(connectionId: string, orgId: string, at: Date): Promise<boolean>;
+    /**
+     * The {@link RESUME_JOB} job: 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
      * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
      */
     resumeConnection(connectionId: string): Promise<void>;

package/dist/channels/jobs.js

@@ -17,8 +17,8 @@ import { KernelEvents } from "../infra/events/kernel-events.js";
 import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { OUTBOX_JOBS } from "../infra/outbox/registry.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
-import { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
-export { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
+import { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, RESUME_JOB, resumeJobId, } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, RESUME_JOB, resumeJobId, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -160,7 +160,22 @@ let ChannelJobs = class ChannelJobs {
         });
     }
     /**
-     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
+     * Owes the catch-up of a connection that can deliver again in the caller's transaction (the
+     * update that re-enabled it or rotated its credentials while active): the deliveries that ran
+     * while it could not deliver have ended, and nothing else finds the conversations lagging the log.
+     * `at` is the connection row's new `updated_at`.
+     */
+    oweResume(connectionId, orgId, at) {
+        return this.outbox.add({
+            queue: CHANNEL_QUEUE_NAME,
+            name: RESUME_JOB,
+            jobId: resumeJobId(connectionId, at),
+            data: { connectionId },
+            orgId,
+        });
+    }
+    /**
+     * The {@link RESUME_JOB} job: 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
      * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
      */
     async resumeConnection(connectionId) {

package/dist/channels/outbound.d.ts

@@ -97,7 +97,7 @@ export declare class ChannelOutbound {
     /** The conversation lock provider; delivery takes it under its own key prefix. */
     lock: Pick<ConversationLock, "scoped">, connections: Pick<ChannelConnections, "outbound">, approvals: Pick<ApprovalsService, "describe">, questions: Pick<QuestionsService, "forCall">, registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">, 
     /** 入站任务的处理（worker 上执行 `ChannelInbound.handle`）；失败抛错由 BullMQ 重试。 */
-    inbound: Pick<ChannelInbound, "handle">, jobs: Pick<ChannelJobs, "enqueue">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "error" | "warn" | "info">, txHost: TransactionHost, 
+    inbound: Pick<ChannelInbound, "handle">, jobs: Pick<ChannelJobs, "enqueue" | "resumeConnection">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "error" | "warn" | "info">, txHost: TransactionHost, 
     /** Pauses the task of a scheduled run whose chat is gone (scheduled tasks spec §8). */
     schedules: Pick<ScheduledTasksService, "pauseFor">);
     /**
@@ -112,7 +112,10 @@ export declare class ChannelOutbound {
     /** Stops: the jobs in flight are handed back at their next checkpoint, the worker closes. */
     close(): Promise<void>;
     private requeue;
-    /** One job of the channel queue (the `@Processor` calls it): a delivery or an inbound event. */
+    /**
+     * One job of the channel queue (the `@Processor` calls it): a delivery, an inbound event or a
+     * connection's catch-up.
+     */
     process(job: Job<ChannelJobData>, token: string | undefined): Promise<void>;
     /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */
     private pluginPending;

package/dist/channels/outbound.js

@@ -28,7 +28,7 @@ import { ToolRegistry } from "../tools/registry.js";
 import { approvalCard, cardMessage, connectUrl, conversationUrl, questionCard, webBase, } from "./cards.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
-import { ChannelJobs, INBOUND_JOB, idempotencyKey, } from "./jobs.js";
+import { ChannelJobs, INBOUND_JOB, idempotencyKey, RESUME_JOB, } from "./jobs.js";
 import { phrase } from "./phrases.js";
 import { insertThread } from "./threads.js";
 // The queue, job names, ids and priorities live with the producer (jobs.ts)
@@ -233,12 +233,19 @@ let ChannelOutbound = class ChannelOutbound {
         await job.moveToDelayed(Date.now() + delayMs, token);
         throw new DelayedError();
     }
-    /** One job of the channel queue (the `@Processor` calls it): a delivery or an inbound event. */
+    /**
+     * One job of the channel queue (the `@Processor` calls it): a delivery, an inbound event or a
+     * connection's catch-up.
+     */
     async process(job, token) {
         if (this.stopping.signal.aborted)
             return this.requeue(job, token, 0);
         if (job.name === INBOUND_JOB)
             return this.processInbound(job, token);
+        // a connection's catch-up: a failed add fails the job, which BullMQ retries
+        if (job.name === RESUME_JOB) {
+            return this.jobs.resumeConnection(job.data.connectionId);
+        }
         return this.deliver(job, token);
     }
     /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */

package/dist/conversations/conversations.controller.d.ts

@@ -312,8 +312,10 @@ export declare class ConversationsController {
     }>;
     /**
      * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
-     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
-     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * `run.not_active`. On a root conversation every active sub-agent of its tree stops with its
+     * run, and nothing they deliver starts the root again until its next run (agent map spec §6,
+     * changed in acceptance 2026-11-13); `runId` is the stopped run (the latest when only sub-agents
+     * ran). On a sub-agent's conversation (the root's owner, at any depth) the
      * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
      * which may already be finished when only its descendants were working (agent map spec §6).
      */

package/dist/conversations/conversations.controller.js

@@ -456,8 +456,10 @@ let ConversationsController = class ConversationsController {
     }
     /**
      * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
-     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
-     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * `run.not_active`. On a root conversation every active sub-agent of its tree stops with its
+     * run, and nothing they deliver starts the root again until its next run (agent map spec §6,
+     * changed in acceptance 2026-11-13); `runId` is the stopped run (the latest when only sub-agents
+     * ran). On a sub-agent's conversation (the root's owner, at any depth) the
      * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
      * which may already be finished when only its descendants were working (agent map spec §6).
      */

package/dist/conversations/conversations.service.d.ts

@@ -537,10 +537,43 @@ export declare class ConversationsService {
      * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
      * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
      *
-     * A root conversation's stop stops only its own run: its background sub-agents keep working
-     * (agent map spec §6). A sub-agent's conversation (its owner, from the agent map) stops that
-     * sub-agent with every descendant (`RunControl.stopTree`); `run.not_active` when nothing in that
-     * subtree runs, else the sub-agent's latest run id.
+     * A root conversation's stop stops everything below it too (agent map spec §6, changed in
+     * acceptance 2026-11-13: after a person stops, the conversation stays stopped). In order:
+     * 1. `tree_stopped_at` is set on the root under its row lock: by the stopped run's terminal
+     *    transaction (a waiting, queued or orphaned run), before the stop is asked for (a run a
+     *    worker holds, which is active until then), or on its own (nothing of the root ran). From
+     *    then on no sub-agent delivery wakes the root (`wakeDecisionIn`) and no
+     *    sub-agent of the tree starts a run by a wake or a parent's message (`RunQueue.childWakeIn`),
+     *    until the root next starts a run (a person's message, the queue, a background Bash task's
+     *    finish), which clears it. A child that finishes just before or after the stop, `completed`
+     *    or `aborted`, thus never wakes the root; its delivery stays in the log and reaches the
+     *    model with the next run;
+     * 2. (with 1) the root's own active run stops as before ({@link abortRootRun});
+     * 3. every active sub-agent run of the tree stops (`RunControl.stopTree`, as the agent map's stop
+     *    and the deletion do), with the background tasks of every sub-agent. A sub-agent the root's
+     *    run dispatched after that read is stopped when the root run ends
+     *    (`Waits.stopDescendantsOfStopped`).
+     * The root's own background Bash tasks keep running: they are the conversation's tasks, stopped
+     * with `TaskStop` or the task list. `run.not_active` when neither the root nor its tree had an
+     * active run (the stop still holds the tree's wakes); else the root's run id (its latest when only
+     * sub-agents ran).
+     *
+     * A sub-agent's conversation (its owner, from the agent map) stops that sub-agent with every
+     * descendant (`RunControl.stopTree`); `run.not_active` when nothing in that subtree runs, else
+     * the sub-agent's latest run id. Its `aborted` finish never wakes its parent.
      */
     abort(orgId: string, conversationId: string, accountId: string): Promise<string>;
+    /**
+     * Marks a person's stop of the root's tree (`tree_stopped_at`, see {@link abort}); committed
+     * before any stop, so every wake decided after it (under the root's row lock) sees it.
+     */
+    private holdTree;
+    /**
+     * Stops a root conversation's own active run (queued / running / waiting) and returns its id;
+     * null when none is active. Its sub-agents are the caller's. The tree's hold
+     * (`tree_stopped_at`) is written by the stopped run's terminal transaction (`RunFinish.finishIn`
+     * for a run a person stopped), in the lock order every stop and decision takes (conversation,
+     * decided row, run); a run a worker holds is marked before its stop is asked for as well.
+     */
+    private abortRootRun;
 }