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

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/catalog-content.d.ts

@@ -77,6 +77,11 @@ export interface OrgCatalogTemplate {
      * install wizard does not ask for it (an org admin sets it up when switching it on).
      */
     defaultOff: boolean;
+    /**
+     * The template is on in this org right now (a default-off one an admin switched on): the install
+     * asks for its input too, since the install is what creates its connector.
+     */
+    on: boolean;
     /**
      * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
      * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).
@@ -118,7 +123,7 @@ export interface OrgCatalogDetail {
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"]): OrgCatalogTemplate;
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"], on?: boolean): OrgCatalogTemplate;
 /** An item's icon (the latest version's plugin icon). */
 export interface CatalogIcon {
     data: Uint8Array;

package/dist/catalog/catalog-content.js

@@ -16,7 +16,7 @@ import { satisfiesRange } from "./versions.js";
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export function orgTemplateView(id, file, guide = null) {
+export function orgTemplateView(id, file, guide = null, on = true) {
     const t = file.template;
     return {
         id,
@@ -30,6 +30,7 @@ export function orgTemplateView(id, file, guide = null) {
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
         defaultOff: file.defaultEnabled === false,
+        on,
         guide,
     };
 }

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/catalog/org-catalog.service.js

@@ -273,6 +273,9 @@ let OrgCatalogService = class OrgCatalogService {
             throw itemNotFound();
         const m = v.manifest;
         const templates = await readCatalogTemplates(this.storage, v);
+        // Which templates are on in this org now: the install asks for the input of those, a
+        // default-off one an admin switched on included
+        const on = await connectorTemplatesOn(this.db, orgId, itemId, templates.map((t) => t.id));
         // where each template's page finds its setup guide (spec 2026-11-09-setup-guides-v2 §9.3)
         const guideOf = (templateId) => {
             const g = templateGuideOf(m, templateId);
@@ -290,7 +293,7 @@ let OrgCatalogService = class OrgCatalogService {
             item,
             hasIcon: m.icon !== undefined,
             extension: m.extension ? m.name : null,
-            templates: templates.map((t) => orgTemplateView(t.id, t.file, guideOf(t.id))),
+            templates: templates.map((t) => orgTemplateView(t.id, t.file, guideOf(t.id), on.has(t.id))),
             dependencies: [
                 ...(m.dependencies ?? []).map((d) => ({ name: d.name, range: d.version })),
                 ...implied.map((d) => ({ name: d.name, range: d.range, implied: true })),
@@ -298,7 +301,7 @@ let OrgCatalogService = class OrgCatalogService {
             skills: (m.skills ?? []).map((s) => packagePath(s.path)),
             agents: (m.agents ?? []).map((a) => packagePath(a.path)),
             missingTemplates: item.installed !== null && item.state === "needs_config"
-                ? ((await this.pluginInstaller.missingConnectors(orgId, itemId))?.templates ?? []).map((t) => orgTemplateView(t.id, t.file, guideOf(t.id)))
+                ? ((await this.pluginInstaller.missingConnectors(orgId, itemId))?.templates ?? []).map((t) => orgTemplateView(t.id, t.file, guideOf(t.id), true))
                 : [],
         };
     }

package/dist/catalog/plugin-install.d.ts

@@ -540,6 +540,11 @@ export declare class PluginInstaller {
             file: ConnectorTemplateFile;
         }[];
     } | undefined>;
+    /**
+     * The org's live connector made from one of the plugin's connector templates, if any: an
+     * uninstall keeps a connector its agents use, and the plugin's next switch-on reuses it.
+     */
+    private liveTemplateConnector;
     /**
      * Creates the connectors an installed plugin is missing (ruling P2-10, `POST …/catalog/:itemId/
      * connectors`): `input.connectors` names some of {@link missingConnectors}' templates with the

package/dist/catalog/plugin-install.js

@@ -484,6 +484,10 @@ let PluginInstaller = class PluginInstaller {
                 // The kernel installs only what needs no org input (the scope sync's `needs_config` rule)
                 if (actor === null)
                     throw systemNeedsInput(manifest.name);
+                // An earlier switch-off kept this template's connector: the install takes it back, so its
+                // input is not asked for here (the connector keeps its endpoint and credentials)
+                if ((await this.liveTemplateConnector(orgId, itemId, ct.id)) !== undefined)
+                    continue;
                 connectors.set(ct.id, this.planConnector(actor, { itemId, version, name: manifest.name }, ct, input, at, approvedBy));
             }
         }
@@ -743,9 +747,24 @@ let PluginInstaller = class PluginInstaller {
             }
             step = "connectors";
             for (const ct of plan.templates) {
+                // An earlier switch-off kept this template's connector (its agents use it): the plugin
+                // takes it back instead of creating a second one, whose default slug the first holds
+                const existing = await this.liveTemplateConnector(orgId, itemId, ct.id);
+                if (existing !== undefined) {
+                    await record({
+                        kind: "connector",
+                        ref: existing,
+                        created: false,
+                        skillVersion: null,
+                        templateId: ct.id,
+                    });
+                    continue;
+                }
                 const ci = plan.connectors.get(ct.id);
+                // No input was needed (a live connector was taken back above, or the template was skipped
+                // at plan time): nothing to create
                 if (!ci)
-                    throw new ApiError("internal", `Connector template ${ct.id} was not planned`);
+                    continue;
                 if (actor === null)
                     throw systemNeedsInput(manifest.name);
                 const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
@@ -1657,6 +1676,23 @@ let PluginInstaller = class PluginInstaller {
             templates: all.filter((t) => on.has(t.id) && !made.has(t.id)),
         };
     }
+    /**
+     * The org's live connector made from one of the plugin's connector templates, if any: an
+     * uninstall keeps a connector its agents use, and the plugin's next switch-on reuses it.
+     */
+    async liveTemplateConnector(orgId, itemId, templateId) {
+        const row = await this.db
+            .selectFrom("connectors as c")
+            .innerJoin("platform_connector_templates as p", "p.id", "c.platform_template_id")
+            .select("c.id")
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .where("p.catalog_item_id", "=", itemId)
+            .where("p.template_id", "=", templateId)
+            .orderBy("c.created_at")
+            .executeTakeFirst();
+        return row?.id;
+    }
     /**
      * Creates the connectors an installed plugin is missing (ruling P2-10, `POST …/catalog/:itemId/
      * connectors`): `input.connectors` names some of {@link missingConnectors}' templates with the

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) {