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

package/dist/extensions/usage-subscribers.d.ts

@@ -0,0 +1,43 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
+ * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
+ * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
+ * the organization enabled (org config rows and required bootstrap plugins).
+ */
+export declare function queryUsageSubscribers(db: KernelSchemaDb, orgId?: string): Promise<Set<string>>;
+/** How long one replica trusts its answer to "does any plugin subscribe" (spec §8.1). */
+export declare const USAGE_SUBSCRIBERS_TTL_MS = 30000;
+/**
+ * Test seam (`KernelOverride`): the clock {@link UsageSubscribers} ages its cached answer with
+ * (default `Date.now`); the kernel never provides it.
+ */
+export declare const USAGE_SUBSCRIBERS_CLOCK: unique symbol;
+/**
+ * Whether the deployment has at least one `usage.report` subscriber ({@link queryUsageSubscribers}
+ * without an org), which decides whether a usage write owes a delivery (transactional outbox spec
+ * §8.1): a usage event written while no plugin subscribes is never reported, later subscribers
+ * included. The answer comes from PG, not from this replica's loaded handlers, so a replica that
+ * has no handler still owes the delivery another replica makes.
+ *
+ * Per-process memoisation of that PG read: kept {@link USAGE_SUBSCRIBERS_TTL_MS} and cleared on
+ * `PLUGINS_CHANGED` (`ExtensionLifecycle` calls {@link invalidate}), so an enabled subscriber is
+ * seen at once, or within 30 s when the bus message is lost. It holds no state another request or
+ * replica relies on.
+ */
+export declare class UsageSubscribers {
+    private readonly kdb;
+    private readonly now;
+    private cached;
+    /** Bumped by {@link invalidate}: a read that started before it does not refill the cache. */
+    private generation;
+    constructor(kdb: KernelDb, now?: () => number);
+    /** Whether any plugin subscribes (cached; the read joins the caller's transaction, if any). */
+    any(): Promise<boolean>;
+    /** Forgets the cached answer (a plugin was installed, enabled, upgraded or removed). */
+    invalidate(): void;
+}
+/** {@link UsageSubscribers}: below the extension host, so the model broker and the runtime use it. */
+export declare class UsageSubscribersModule {
+}

package/dist/extensions/usage-subscribers.js

@@ -0,0 +1,108 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Module, Optional } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { enabledExtensionsQuery } from "./enabled.js";
+/**
+ * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
+ * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
+ * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
+ * the organization enabled (org config rows and required bootstrap plugins).
+ */
+export async function queryUsageSubscribers(db, orgId) {
+    let q = db
+        .selectFrom("extension_permission_snapshots as s")
+        .select("s.plugin")
+        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? 'usage.report'`)
+        .where((eb) => eb.or([
+        eb.exists(eb
+            .selectFrom("extension_installs as i")
+            .select(sql `1`.as("one"))
+            .whereRef("i.name", "=", "s.plugin")
+            .where("i.desired_state", "=", "enabled")),
+        // config-declared plugins still declared (and not unloaded) on some replica; installs are
+        // covered by desired_state above (their replica rows linger as `unloaded` when disabled)
+        eb.exists(eb
+            .selectFrom("extension_replica_status as r")
+            .select(sql `1`.as("one"))
+            .whereRef("r.plugin", "=", "s.plugin")
+            .where("r.source", "=", "config")
+            .where("r.state", "<>", "unloaded")),
+    ]));
+    if (orgId !== undefined) {
+        q = q.where("s.plugin", "in", enabledExtensionsQuery(db, orgId));
+    }
+    return new Set((await q.execute()).map((r) => r.plugin));
+}
+/** How long one replica trusts its answer to "does any plugin subscribe" (spec §8.1). */
+export const USAGE_SUBSCRIBERS_TTL_MS = 30_000;
+/**
+ * Test seam (`KernelOverride`): the clock {@link UsageSubscribers} ages its cached answer with
+ * (default `Date.now`); the kernel never provides it.
+ */
+export const USAGE_SUBSCRIBERS_CLOCK = Symbol("USAGE_SUBSCRIBERS_CLOCK");
+/**
+ * Whether the deployment has at least one `usage.report` subscriber ({@link queryUsageSubscribers}
+ * without an org), which decides whether a usage write owes a delivery (transactional outbox spec
+ * §8.1): a usage event written while no plugin subscribes is never reported, later subscribers
+ * included. The answer comes from PG, not from this replica's loaded handlers, so a replica that
+ * has no handler still owes the delivery another replica makes.
+ *
+ * Per-process memoisation of that PG read: kept {@link USAGE_SUBSCRIBERS_TTL_MS} and cleared on
+ * `PLUGINS_CHANGED` (`ExtensionLifecycle` calls {@link invalidate}), so an enabled subscriber is
+ * seen at once, or within 30 s when the bus message is lost. It holds no state another request or
+ * replica relies on.
+ */
+let UsageSubscribers = class UsageSubscribers {
+    kdb;
+    now;
+    cached;
+    /** Bumped by {@link invalidate}: a read that started before it does not refill the cache. */
+    generation = 0;
+    constructor(kdb, now = Date.now) {
+        this.kdb = kdb;
+        this.now = now;
+    }
+    /** Whether any plugin subscribes (cached; the read joins the caller's transaction, if any). */
+    async any() {
+        const at = this.now();
+        const c = this.cached;
+        if (c !== undefined && at - c.at < USAGE_SUBSCRIBERS_TTL_MS)
+            return c.any;
+        const generation = this.generation;
+        const any = (await queryUsageSubscribers(this.kdb.db)).size > 0;
+        if (generation === this.generation)
+            this.cached = { any, at };
+        return any;
+    }
+    /** Forgets the cached answer (a plugin was installed, enabled, upgraded or removed). */
+    invalidate() {
+        this.generation++;
+        this.cached = undefined;
+    }
+};
+UsageSubscribers = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Optional()),
+    __param(1, Inject(USAGE_SUBSCRIBERS_CLOCK))
+], UsageSubscribers);
+export { UsageSubscribers };
+/** {@link UsageSubscribers}: below the extension host, so the model broker and the runtime use it. */
+let UsageSubscribersModule = class UsageSubscribersModule {
+};
+UsageSubscribersModule = __decorate([
+    Module({
+        providers: [UsageSubscribers],
+        exports: [UsageSubscribers],
+    })
+], UsageSubscribersModule);
+export { UsageSubscribersModule };

package/dist/http/api.module.js

@@ -12,6 +12,7 @@ import { AdminAgentsController } from "../admin/admin-agents.controller.js";
 import { AdminConnectorsController } from "../admin/admin-connectors.controller.js";
 import { AdminAuditController } from "../admin/audit.controller.js";
 import { AdminExtensionsController } from "../admin/extensions.controller.js";
+import { OutboxDeadController } from "../admin/outbox-dead.controller.js";
 import { AdminOverviewController } from "../admin/overview.controller.js";
 import { SetupController } from "../admin/setup.controller.js";
 import { AgentsController } from "../agents/agents.controller.js";
@@ -107,6 +108,7 @@ const CONTROLLERS = [
     AdminConnectorsController,
     AdminAuditController,
     AdminOverviewController,
+    OutboxDeadController,
     AdminExtensionsController,
     AdminCatalogController,
     AdminComponentsController,

package/dist/inbox/inbox.service.d.ts

@@ -6,34 +6,20 @@ import { ApprovalsService, type ApprovalView } from "../tools/approvals.service.
 import type { OrgNoticeDetails } from "./org-notices.js";
 /** The most open org notices one inbox read returns. */
 export declare const ORG_NOTICES_LIST_MAX = 100;
-/** The skill the platform components migration renamed (`skill_renamed`). */
-export interface SkillRenamedDetail {
-    skillId: string;
-    from: string;
-    to: string;
-    platformSkillId: string;
-    plugin: string | null;
-}
 /**
- * A notice for the org's admins (`org_notices`), shown until one of them dismisses it; `kind`
- * picks the detail field that is set:
- * - `skill_renamed` (`skillRenamed`): the platform components migration renamed an org skill whose
- *   name a platform skill on in the org has; agents keep it, by id;
- * - `item_shared`, `shared_item_updated`, `upload_confirmed`, `upload_rejected` (`detail`): the
- *   shapes of {@link OrgNoticeDetails} (plugin scope phase 3, P3-22).
+ * A notice for the org's admins (`org_notices`), shown until one of them dismisses it:
+ * `item_shared`, `shared_item_updated`, `upload_confirmed`, `upload_rejected`, `detail` in the
+ * shape of {@link OrgNoticeDetails} (plugin scope phase 3, P3-22).
  */
 export type OrgNoticeView = {
     id: string;
     createdAt: string;
-} & ({
-    kind: "skill_renamed";
-    skillRenamed: SkillRenamedDetail;
-} | {
+} & {
     [K in keyof OrgNoticeDetails]: {
         kind: K;
         detail: OrgNoticeDetails[K];
     };
-}[keyof OrgNoticeDetails]);
+}[keyof OrgNoticeDetails];
 /** 收件箱一次最多返回的事项数。 */
 export declare const INBOX_MAX_ITEMS = 100;
 /**
@@ -51,7 +37,7 @@ export declare const INBOX_MAX_ITEMS = 100;
  * - `schedule_attention`: the current user's own scheduled task that needs them (spec §8): paused
  *   for any reason but their own pause, its latest run failed, or its latest run was refused tools
  *   or connections; derived live, gone once the task is resumed or runs clean;
- * - the org notices (`skill_renamed`, `item_shared`, `shared_item_updated`, `upload_confirmed`,
+ * - the org notices (`item_shared`, `shared_item_updated`, `upload_confirmed`,
  *   `upload_rejected`; `type` = the notice's kind): for org admins, until one dismisses it
  *   (`POST inbox/notices/:id/dismiss`).
  */

package/dist/inbox/inbox.service.js

@@ -112,9 +112,6 @@ let InboxService = class InboxService {
             .execute();
         return rows.map((r) => {
             const base = { id: r.id, createdAt: r.created_at.toISOString() };
-            if (r.kind === "skill_renamed") {
-                return { ...base, kind: r.kind, skillRenamed: r.detail };
-            }
             return { ...base, kind: r.kind, detail: r.detail };
         });
     }

package/dist/inbox/org-notices.d.ts

@@ -1,7 +1,7 @@
 import { type OwnedRef, type Owner } from "../catalog/ownership.js";
 import type { KernelSchemaDb, OrgNoticeKind } from "../db/kernel-schema.js";
 export type { OrgNoticeKind };
-/** The `detail` of each notice kind except `skill_renamed` (written by the platform migration). */
+/** The `detail` of each notice kind. */
 export interface OrgNoticeDetails {
     /** An org was added to the item's list, or its scope widened (`all_orgs`). */
     /** `displayName`: a plugin's display name, which the inbox names it by (null otherwise). */

package/dist/inbox/platform-inbox.service.d.ts

@@ -8,11 +8,6 @@ import type { PlatformNoticeDetails } from "./platform-notices.js";
 export declare const PLATFORM_INBOX_MAX_ITEMS = 100;
 /** The most open scope sync failures one read takes. */
 export declare const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
-/**
- * A platform components migration run unfinished this long after its start is stuck (its worker
- * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
- */
-export declare const MIGRATION_RUN_STUCK_MS: number;
 /**
  * An open failure of the plugin scope sync: its last attempt to install the plugin in the org, to
  * uninstall it, or to install the dependencies a platform update added (`dependencies`) failed,
@@ -34,18 +29,6 @@ export interface ScopeSyncFailureView {
     message: string;
     failedAt: string;
 }
-/**
- * The latest platform components migration run (`platform_migration_runs`) when it needs a look:
- * finished with catalog items whose components could not be written (`itemsFailed`,
- * `<name>@<version>`), or `stuck` (unfinished {@link MIGRATION_RUN_STUCK_MS} after its start).
- */
-export interface MigrationRunView {
-    id: string;
-    startedAt: string;
-    finishedAt: string | null;
-    stuck: boolean;
-    itemsFailed: string[];
-}
 /**
  * One item of the super admin's inbox (by `type`). Nothing is decided in the inbox: each item is
  * acted on where it lives (the web links to it).
@@ -56,7 +39,6 @@ export interface MigrationRunView {
  * - `org_upload_pending`: an org-owned plugin whose uploaded version (with an extension) waits for
  *   the super admin in 待确认 (ruling P3-22; confirmed or rejected there), `id` = the item's;
  * - `scope_sync_failed`: an open scope sync failure, `id` = `<itemId>/<orgId>`;
- * - `platform_migration`: the latest migration run, failed items or stuck, `id` = the run's;
  * - `ownership_transferred`: a deleted org's shared item now belongs to the platform, until a
  *   super admin dismisses it (`POST admin/inbox/notices/:id/dismiss`).
  */
@@ -80,11 +62,6 @@ export type PlatformInboxItem = {
     id: string;
     createdAt: string;
     failure: ScopeSyncFailureView;
-} | {
-    type: "platform_migration";
-    id: string;
-    createdAt: string;
-    run: MigrationRunView;
 } | {
     type: "ownership_transferred";
     id: string;
@@ -92,7 +69,7 @@ export type PlatformInboxItem = {
     notice: PlatformNoticeView;
 };
 /** Every {@link PlatformInboxItem} type, in the order the admin overview lists them. */
-export declare const PLATFORM_INBOX_TYPES: readonly ["catalog_request", "permission_confirmation", "org_upload_pending", "scope_sync_failed", "platform_migration", "ownership_transferred"];
+export declare const PLATFORM_INBOX_TYPES: readonly ["catalog_request", "permission_confirmation", "org_upload_pending", "scope_sync_failed", "ownership_transferred"];
 /** How many items of each type wait: every type, zeros included. */
 export type PlatformInboxCounts = Record<PlatformInboxItem["type"], number>;
 /** An open platform notice (`platform_notices`, kind `ownership_transferred`). */
@@ -116,8 +93,8 @@ export interface PlatformInboxView {
 /**
  * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
  * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
- * confirmations), plus the scope sync's open failures and the platform components migration's
- * latest run. Stateless, read live from PG.
+ * confirmations), plus the scope sync's open failures and the platform notices. Stateless, read
+ * live from PG.
  */
 export declare class PlatformInboxService {
     private readonly requests;
@@ -148,10 +125,4 @@ export declare class PlatformInboxService {
     private countScopeSyncFailures;
     /** The open scope sync failures ({@link failureRows}), newest first. */
     private scopeSyncFailures;
-    /**
-     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
-     * finished without failed items, is still running, or there was none. An earlier run's failure
-     * is not shown: each run tries every unwritten item again.
-     */
-    private migrationRun;
 }

package/dist/inbox/platform-inbox.service.js

@@ -17,11 +17,6 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 export const PLATFORM_INBOX_MAX_ITEMS = 100;
 /** The most open scope sync failures one read takes. */
 export const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
-/**
- * A platform components migration run unfinished this long after its start is stuck (its worker
- * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
- */
-export const MIGRATION_RUN_STUCK_MS = 60 * 60_000;
 /** Plugin install statuses of a plugin that is on in the org. */
 const LIVE_INSTALL = ["installing", "installed", "upgrading"];
 /** Every {@link PlatformInboxItem} type, in the order the admin overview lists them. */
@@ -30,14 +25,13 @@ export const PLATFORM_INBOX_TYPES = [
     "permission_confirmation",
     "org_upload_pending",
     "scope_sync_failed",
-    "platform_migration",
     "ownership_transferred",
 ];
 /**
  * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
  * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
- * confirmations), plus the scope sync's open failures and the platform components migration's
- * latest run. Stateless, read live from PG.
+ * confirmations), plus the scope sync's open failures and the platform notices. Stateless, read
+ * live from PG.
  */
 let PlatformInboxService = class PlatformInboxService {
     requests;
@@ -49,13 +43,12 @@ let PlatformInboxService = class PlatformInboxService {
         this.kdb = kdb;
     }
     async list() {
-        const [requests, requestCount, pending, failures, failureCount, run, notices, noticeCount] = await Promise.all([
+        const [requests, requestCount, pending, failures, failureCount, notices, noticeCount] = await Promise.all([
             this.requests.listDeployment(),
             this.requests.countPendingDeployment(),
             this.catalog.list({ pending: true }),
             this.scopeSyncFailures(),
             this.countScopeSyncFailures(),
-            this.migrationRun(),
             this.notices(),
             this.countNotices(),
         ]);
@@ -84,16 +77,6 @@ let PlatformInboxService = class PlatformInboxService {
                 createdAt: n.createdAt,
                 notice: n,
             })),
-            ...(run === null
-                ? []
-                : [
-                    {
-                        type: "platform_migration",
-                        id: run.id,
-                        createdAt: run.finishedAt ?? run.startedAt,
-                        run,
-                    },
-                ]),
         ];
         // newest first; equal times by id (a stable order)
         all.sort((a, b) => a.createdAt !== b.createdAt
@@ -111,7 +94,6 @@ let PlatformInboxService = class PlatformInboxService {
             permission_confirmation: pending.length - orgUploads,
             org_upload_pending: orgUploads,
             scope_sync_failed: failureCount,
-            platform_migration: run === null ? 0 : 1,
             ownership_transferred: noticeCount,
         };
         const total = Object.values(byType).reduce((a, b) => a + b, 0);
@@ -123,14 +105,13 @@ let PlatformInboxService = class PlatformInboxService {
      * requests and the failures; the permission confirmations are the catalog's pending list).
      */
     async count() {
-        const [requests, pending, failures, run, notices] = await Promise.all([
+        const [requests, pending, failures, notices] = await Promise.all([
             this.requests.countPendingDeployment(),
             this.catalog.list({ pending: true }),
             this.countScopeSyncFailures(),
-            this.migrationRun(),
             this.countNotices(),
         ]);
-        return requests + pending.length + failures + (run === null ? 0 : 1) + notices;
+        return requests + pending.length + failures + notices;
     }
     async countNotices() {
         const r = await this.kdb.db
@@ -240,36 +221,6 @@ let PlatformInboxService = class PlatformInboxService {
             failedAt: r.failed_at.toISOString(),
         }));
     }
-    /**
-     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
-     * finished without failed items, is still running, or there was none. An earlier run's failure
-     * is not shown: each run tries every unwritten item again.
-     */
-    async migrationRun() {
-        const run = await this.kdb.db
-            .selectFrom("platform_migration_runs")
-            .select(["id", "started_at", "finished_at", "stats"])
-            .orderBy("started_at", "desc")
-            .orderBy("id", "desc")
-            .limit(1)
-            .executeTakeFirst();
-        if (run === undefined)
-            return null;
-        const failed = run.stats.itemsFailed;
-        const itemsFailed = Array.isArray(failed)
-            ? failed.filter((x) => typeof x === "string")
-            : [];
-        const stuck = run.finished_at === null && run.started_at.getTime() < Date.now() - MIGRATION_RUN_STUCK_MS;
-        if (!stuck && (run.finished_at === null || itemsFailed.length === 0))
-            return null;
-        return {
-            id: run.id,
-            startedAt: run.started_at.toISOString(),
-            finishedAt: run.finished_at?.toISOString() ?? null,
-            stuck,
-            itemsFailed,
-        };
-    }
 };
 PlatformInboxService = __decorate([
     Injectable(),

package/dist/index.d.ts

@@ -70,6 +70,7 @@ export { ROUTE_SCHEMAS, type RouteSchemas } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export type { AgentLoop, LoopContext, LoopOutcome } from "./runtime/loop.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
+export { type OrphanCandidate, queuedRunsWithoutJob } from "./runtime/run-orphan-check.job.js";
 export { runJobId } from "./runtime/run-queue.js";
 export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";

package/dist/index.js

@@ -68,6 +68,7 @@ export { PlatformOperations } from "./platform/registry.js";
 export { ROUTE_SCHEMAS } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
+export { queuedRunsWithoutJob } from "./runtime/run-orphan-check.job.js";
 export { runJobId } from "./runtime/run-queue.js";
 export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, } from "./sandbox/sandbox.service.js";

package/dist/infra/cli/kernel-cli.module.js

@@ -21,6 +21,7 @@ import { KernelEventsModule } from "../events/kernel-events.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "../lock/lock.module.js";
 import { LoggingModule } from "../logging/logging.module.js";
+import { OutboxModule } from "../outbox/outbox.module.js";
 import { QueueModule } from "../queue/queue.module.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /** How long the CLI's Redis connection may take before a command fails (a publish only warns). */
@@ -110,6 +111,10 @@ let KernelCliModule = KernelCliModule_1 = class KernelCliModule {
                 ConfigModule.forRoot(config, opts.env !== undefined ? { env: opts.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
+                // owed jobs a command's domain writes carry (an extension's embed call owes its usage
+                // report); delivered by the fast path when the command's context has the queue, else by a
+                // worker's relay
+                OutboxModule,
                 // QueueModule's root gives the queues a command's modules register (the catalog's scope
                 // sync and maintenance queues) the configured Redis; without it BullMQ would connect to
                 // its default 127.0.0.1:6379

package/dist/infra/events/kernel-events.d.ts

@@ -23,8 +23,9 @@ export interface KernelEventMap {
     };
     /**
      * A person decided a tool call approval (after the commit, exactly once: only the decision that
-     * changed it from pending). The run's waits resume it and its IM delivery is enqueued; a lost
-     * event is re-derived by the wait sweep (runs waiting on a decided approval are resumed).
+     * changed it from pending). The decision's transaction resumed the run and, for a conversation
+     * with a channel target, owed the IM delivery that updates the card (with its `approval_decided`
+     * append); the event itself is only the decision's announcement.
      */
     "approval.decided": {
         id: string;
@@ -36,8 +37,7 @@ export interface KernelEventMap {
     };
     /**
      * A person answered a tool call's input request, or skipped it with a message (after the commit,
-     * exactly once). Same
-     * consumers and the same re-derivation as `approval.decided`.
+     * exactly once). The same transaction contract as `approval.decided`.
      */
     "question.answered": {
         id: string;
@@ -47,38 +47,20 @@ export interface KernelEventMap {
         /** `skipped`: the run's starter sent a message instead (reply-while-question spec §6.3). */
         outcome: "answered" | "skipped";
     };
-    /**
-     * EventAppended: a conversation's event log advanced to `toSeq` (after the commit, from
-     * `EventLog.notify`, right after the bus publish). The channel outbound delivery enqueues a job
-     * for a conversation with an IM target; a lost event is re-derived by the next append's (and the
-     * finished delivery job re-checks the log for content it has not delivered).
-     */
-    "conversation.event-appended": {
-        conversationId: string;
-        toSeq: number;
-    };
     /**
      * A run started executing on this replica (its first start, a resume, or a takeover after a
      * stall), after it took the conversation lock and an org quota slot. The channel outbound
-     * enqueues the conversation's IM delivery; a lost event is re-derived by the run's next append.
+     * enqueues the conversation's IM delivery at once (a hint: the run's appends owe it, transactional
+     * outbox spec §8.1).
      */
     "run.started": {
         conversationId: string;
         runId: string;
     };
     /**
-     * A stop of a run waiting on a person was handled (`RunControl.abortWaiting`, whether or not it
-     * still waited): its approval and question cards change, so the channel outbound enqueues the
-     * conversation's IM delivery (re-derived by the next append when lost).
-     */
-    "run.wait-stopped": {
-        conversationId: string;
-        runId: string;
-    };
-    /**
-     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active fork
-     * sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event is
-     * repaired by the wait sweep (fork children of finished runs).
+     * The `run-orphan-check` failed an orphaned run (after the commit): the waits stop its active
+     * fork sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event
+     * is repaired by the `stop-tree` job the run's terminal transaction owed.
      */
     "run.orphaned": {
         runId: string;
@@ -99,14 +81,6 @@ export interface KernelEventMap {
     "background_task.finished": {
         conversationId: string;
     };
-    /**
-     * An extension's `ctx.models.embed` call wrote a `model_usage` row (after the commit, spec B
-     * §5.4). The usage reporter enqueues its `usage.report` delivery; a lost event is re-derived by
-     * the usage sweep (rows whose `reported_at` is still null).
-     */
-    "model_usage.recorded": {
-        id: string;
-    };
 }
 type Handler<K extends keyof KernelEventMap> = (payload: KernelEventMap[K]) => Promise<void> | void;
 /** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */

package/dist/infra/outbox/outbox-relay.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The outbox relay (`@LockedInterval`), imported only by `WorkerModule`. Its dispatcher comes from
+ * the global `OutboxModule`, which every role has (the fast path runs everywhere).
+ */
+export declare class OutboxRelayModule {
+}

package/dist/infra/outbox/outbox-relay.module.js

@@ -0,0 +1,18 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { OutboxRelay } from "./outbox.relay.js";
+/**
+ * The outbox relay (`@LockedInterval`), imported only by `WorkerModule`. Its dispatcher comes from
+ * the global `OutboxModule`, which every role has (the fast path runs everywhere).
+ */
+let OutboxRelayModule = class OutboxRelayModule {
+};
+OutboxRelayModule = __decorate([
+    Module({ providers: [OutboxRelay] })
+], OutboxRelayModule);
+export { OutboxRelayModule };