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

package/dist/admin/overview.service.js

@@ -18,6 +18,8 @@ import { PlatformInboxService } from "../inbox/platform-inbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { OrgsService } from "../orgs/orgs.service.js";
 import { ProviderRegistry } from "../runtime/providers.js";
+import { QueueLostJobs } from "../runtime/queue-lost-jobs.js";
+import { OutboxDeadService } from "./outbox-dead.service.js";
 /** The most rows each attention list returns; the rest are counted in `more`. */
 export const ATTENTION_LIST_MAX = 20;
 /** The reason an extension is listed, or null when it needs nothing. */
@@ -53,8 +55,9 @@ export function providerProblem(p) {
 /**
  * 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). 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).
+ * 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;
@@ -66,8 +69,10 @@ let AdminOverviewService = class AdminOverviewService {
     orgs;
     accounts;
     marketplaces;
+    outboxDead;
+    lostJobs;
     log;
-    constructor(extensions, catalog, registry, displayNames, icons, inbox, orgs, accounts, marketplaces, log) {
+    constructor(extensions, catalog, registry, displayNames, icons, inbox, orgs, accounts, marketplaces, outboxDead, lostJobs, log) {
         this.extensions = extensions;
         this.catalog = catalog;
         this.registry = registry;
@@ -77,6 +82,8 @@ let AdminOverviewService = class AdminOverviewService {
         this.orgs = orgs;
         this.accounts = accounts;
         this.marketplaces = marketplaces;
+        this.outboxDead = outboxDead;
+        this.lostJobs = lostJobs;
         this.log = log;
     }
     async stats() {
@@ -87,10 +94,17 @@ let AdminOverviewService = class AdminOverviewService {
             this.attention(),
         ]);
         const listed = (s) => attention[s].length + attention.more[s];
+        // each dead row waits for a super admin, not the one item that counts them
+        const dead = attention.outbox.reduce((n, o) => n + o.count, 0);
         return {
             orgs: orgs.length,
             accounts,
-            attentionTotal: inbox + listed("extensions") + listed("updates") + listed("providers"),
+            attentionTotal: inbox +
+                listed("extensions") +
+                listed("updates") +
+                listed("providers") +
+                dead +
+                attention.queue.length,
             partial: attention.unavailable.length > 0,
         };
     }
@@ -98,16 +112,20 @@ let AdminOverviewService = class AdminOverviewService {
         // the catalog is read once: the update rows, and the plugins the inbox already lists
         const items = this.catalogItems();
         items.catch(() => { }); // awaited (and reported) by updateRows
-        const [extensions, updates, providers] = await Promise.allSettled([
+        const [extensions, updates, providers, outbox, queue] = await Promise.allSettled([
             this.extensionRows(items),
             this.updateRows(items),
             this.providerRows(),
+            this.outboxRows(),
+            this.queueRows(),
         ]);
         const out = {
             extensions: [],
             updates: [],
             providers: [],
-            more: { extensions: 0, updates: 0, providers: 0 },
+            outbox: [],
+            queue: [],
+            more: { extensions: 0, updates: 0, providers: 0, outbox: 0, queue: 0 },
             unavailable: [],
         };
         /** The rows of a source that answered (capped), or none and its name in `unavailable`. */
@@ -127,8 +145,22 @@ let AdminOverviewService = class AdminOverviewService {
         out.extensions = take("extensions", extensions);
         out.updates = take("updates", updates);
         out.providers = take("providers", providers);
+        out.outbox = take("outbox", outbox);
+        out.queue = take("queue", queue);
         return out;
     }
+    /** The `queue_lost_jobs` item when the run queue lost jobs this week, else none. */
+    async queueRows() {
+        const lost = await this.lostJobs.summary();
+        return lost === null ? [] : [{ kind: "queue_lost_jobs", ...lost }];
+    }
+    /** The `outbox_dead` item when some outbox rows are dead, else none. */
+    async outboxRows() {
+        const { count, oldestAt } = await this.outboxDead.summary();
+        if (count === 0 || oldestAt === null)
+            return [];
+        return [{ kind: "outbox_dead", count, oldestAt: oldestAt.toISOString() }];
+    }
     /**
      * 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
@@ -218,6 +250,8 @@ AdminOverviewService = __decorate([
     __param(6, Inject(OrgsService)),
     __param(7, Inject(AccountsService)),
     __param(8, Inject(MarketplacesService)),
-    __param(9, Inject(KERNEL_LOGGER))
+    __param(9, Inject(OutboxDeadService)),
+    __param(10, Inject(QueueLostJobs)),
+    __param(11, Inject(KERNEL_LOGGER))
 ], AdminOverviewService);
 export { AdminOverviewService };

package/dist/agents/from-template.js

@@ -329,7 +329,7 @@ export async function planFromTemplate(db, orgId, row, opts) {
         }
         if (describesSubagents)
             listed.add(AGENT_TOOL);
-        // `TaskOutput` / `TaskStop` follow `Bash`
+        // `TaskOutput` / `TaskStop` / `TaskList` follow `Bash`
         for (const name of AGENT_BUILTIN_NAMES)
             if (!listed.has(name))
                 offBuiltin(name);

package/dist/background/finish.d.ts

@@ -1,6 +1,7 @@
 import { EventLog } from "../conversations/event-log.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 BackgroundTaskRow, BackgroundTaskStore } from "./store.js";
 /** Where a task ends (as {@link BackgroundTaskStore.finish} takes it). */
 export type BackgroundFinish = Parameters<BackgroundTaskStore["finish"]>[1];
@@ -19,7 +20,8 @@ export declare const finishedEventKey: (taskId: string) => string;
  * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
  * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
  * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
- * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module). A
+ * finish that may wake the conversation also owes the ensure-run backstop in the transaction.
  *
  * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
  */
@@ -28,7 +30,8 @@ export declare class BackgroundTaskFinisher {
     private readonly eventLog;
     private readonly events;
     readonly txHost: TransactionHost;
-    constructor(store: Pick<BackgroundTaskStore, "finish">, eventLog: EventLog, events: KernelEvents, txHost: TransactionHost);
+    private readonly outbox;
+    constructor(store: Pick<BackgroundTaskStore, "finish">, eventLog: EventLog, events: KernelEvents, txHost: TransactionHost, outbox: Pick<OutboxService, "add">);
     /**
      * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
      * `reported` when a tool call already told the model in its run. False (nothing written) when the

package/dist/background/finish.js

@@ -13,6 +13,8 @@ import { afterCommit } from "../infra/database/after-commit.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import { oweEnsureRun } from "../runtime/run-jobs.js";
 import { taskOutputFile } from "./launch.js";
 import { LAST_LINES_MAX_CHARS } from "./session.js";
 import { BackgroundTaskStore } from "./store.js";
@@ -25,7 +27,8 @@ export const finishedEventKey = (taskId) => `background_task_finished:${taskId}`
  * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
  * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
  * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
- * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module). A
+ * finish that may wake the conversation also owes the ensure-run backstop in the transaction.
  *
  * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
  */
@@ -34,11 +37,13 @@ let BackgroundTaskFinisher = class BackgroundTaskFinisher {
     eventLog;
     events;
     txHost;
-    constructor(store, eventLog, events, txHost) {
+    outbox;
+    constructor(store, eventLog, events, txHost, outbox) {
         this.store = store;
         this.eventLog = eventLog;
         this.events = events;
         this.txHost = txHost;
+        this.outbox = outbox;
     }
     /**
      * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
@@ -71,6 +76,11 @@ let BackgroundTaskFinisher = class BackgroundTaskFinisher {
                 },
             },
         ]);
+        // a finish that may wake the conversation owes the ensure-run backstop with its event: the
+        // wake after the commit (`BackgroundWake`) may never happen (transactional outbox spec §6)
+        if (event && !reported && opts.stoppedBy === undefined) {
+            await oweEnsureRun(this.outbox, task.conversationId, event.seq, task.orgId);
+        }
         const conversations = [...new Set([task.conversationId, task.sandboxConversationId])];
         afterCommit(async () => {
             if (event)
@@ -90,6 +100,7 @@ BackgroundTaskFinisher = __decorate([
     __param(0, Inject(BackgroundTaskStore)),
     __param(1, Inject(EventLog)),
     __param(2, Inject(KernelEvents)),
-    __param(3, Inject(TransactionHost))
+    __param(3, Inject(TransactionHost)),
+    __param(4, Inject(OutboxService))
 ], BackgroundTaskFinisher);
 export { BackgroundTaskFinisher };

package/dist/background/launch.d.ts

@@ -70,7 +70,8 @@ export declare const GROUP_LAUNCHER: string;
  * `setsid nohup sh -c 'timeout -s KILL <seconds> …'` and the sid is `$!`, the pid `setsid` started;
  * elsewhere (macOS: no `setsid`, no `timeout`, no `pgrep -s`) {@link GROUP_LAUNCHER} runs it in a
  * process group of its own, watched by the launcher, and writes the sid (the group id) itself,
- * which the launch waits for (up to 10 s). An
+ * which the launch waits for (up to 10 s). The script starts with `BACKGROUND_LAUNCH_LINE`, so a
+ * local device, which kills what any other exec leaves running, leaves the task alone. An
  * environment without one of the needed programs fails with a readable error on stderr and exit
  * code 127, before anything starts. `id` must be a task id and `seconds` a positive integer (both
  * go into the script unquoted).

package/dist/background/launch.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
+import { BACKGROUND_LAUNCH_LINE, DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
 /**
  * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
  * one short exec that starts the command detached from the exec, and the model-visible result.
@@ -112,7 +112,8 @@ export const GROUP_LAUNCHER = [
  * `setsid nohup sh -c 'timeout -s KILL <seconds> …'` and the sid is `$!`, the pid `setsid` started;
  * elsewhere (macOS: no `setsid`, no `timeout`, no `pgrep -s`) {@link GROUP_LAUNCHER} runs it in a
  * process group of its own, watched by the launcher, and writes the sid (the group id) itself,
- * which the launch waits for (up to 10 s). An
+ * which the launch waits for (up to 10 s). The script starts with `BACKGROUND_LAUNCH_LINE`, so a
+ * local device, which kills what any other exec leaves running, leaves the task alone. An
  * environment without one of the needed programs fails with a readable error on stderr and exit
  * code 127, before anything starts. `id` must be a task id and `seconds` a positive integer (both
  * go into the script unquoted).
@@ -127,6 +128,8 @@ export function launchScript(id, command, seconds) {
     const t = `${TASKS_DIR}/${id}`;
     const need = (list) => `for c in ${list.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${list.join(", ")} in this environment; $c is missing." >&2; exit 127; }; done`;
     return [
+        // first: a local device kills what an exec leaves running, except a launch's detached task
+        BACKGROUND_LAUNCH_LINE,
         "set -e",
         SESSION_MODE_SCRIPT,
         `if [ "$pg" = -s ]; then ${need(REQUIRED_SESSION)}; else ${need(REQUIRED_GROUP)}; fi`,

package/dist/background/store.d.ts

@@ -137,6 +137,14 @@ export declare class BackgroundTaskStore {
     runningStarted(): Promise<BackgroundTaskRow[]>;
     /** The running tasks one conversation owns (not those of its sub-agents), oldest first. */
     runningOwnedBy(conversationId: string): Promise<BackgroundTaskRow[]>;
+    /**
+     * The finished tasks one conversation owns (not those of its sub-agents), the most recently
+     * finished first, at most `limit` of them, with how many it owns in all (`TaskList`).
+     */
+    finishedOwnedBy(conversationId: string, limit: number): Promise<{
+        rows: BackgroundTaskRow[];
+        total: number;
+    }>;
     /** The running tasks of one root conversation's tree (what `maxTasks` limits). */
     countRunning(sandboxConversationId: string): Promise<number>;
     /** The tasks owned by any of the conversations, newest first. */

package/dist/background/store.js

@@ -258,6 +258,30 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             .execute();
         return rows.map(toRow);
     }
+    /**
+     * The finished tasks one conversation owns (not those of its sub-agents), the most recently
+     * finished first, at most `limit` of them, with how many it owns in all (`TaskList`).
+     */
+    async finishedOwnedBy(conversationId, limit) {
+        const [rows, count] = await Promise.all([
+            this.db
+                .selectFrom("background_tasks")
+                .selectAll()
+                .where("conversation_id", "=", conversationId)
+                .where("status", "<>", "running")
+                .orderBy("finished_at", "desc")
+                .orderBy("id", "desc")
+                .limit(limit)
+                .execute(),
+            this.db
+                .selectFrom("background_tasks")
+                .select((eb) => eb.fn.countAll().as("n"))
+                .where("conversation_id", "=", conversationId)
+                .where("status", "<>", "running")
+                .executeTakeFirstOrThrow(),
+        ]);
+        return { rows: rows.map(toRow), total: Number(count.n) };
+    }
     /** The running tasks of one root conversation's tree (what `maxTasks` limits). */
     async countRunning(sandboxConversationId) {
         const r = await this.db

package/dist/catalog/admin-catalog.controller.d.ts

@@ -5,12 +5,13 @@ import { type ClientBuildSummary, ClientBuilds } from "../client/client-builds.s
 import { PluginGuides, type RenderedSetupGuide } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
-import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogImportUpdateBody, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
 import { AppearanceApplyBody } from "./appearance.schemas.js";
 import { type AppearanceResult, AppearanceService } from "./appearance.service.js";
 import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
 import { CatalogScopeService, type ScopePreview } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
+import { PlatformImportUpdate, type PlatformImportUpdateResult } from "./platform-import-update.js";
 import { type PluginConfirmResult, PluginImport, type PluginReview } from "./plugin-import.js";
 import { PlatformPluginUpdater, type PlatformUpdatePreview, type PlatformUpdateResult } from "./plugin-upgrade.js";
 declare const ConfirmBody: z.ZodObject<{
@@ -41,11 +42,12 @@ export declare class AdminCatalogController {
     private readonly orgCatalog;
     private readonly scope;
     private readonly updater;
+    private readonly importUpdate;
     private readonly icons;
     private readonly appearance;
     private readonly clientBuilds;
     private readonly guides;
-    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, icons: PluginIcons, appearance: AppearanceService, clientBuilds: ClientBuilds, guides: PluginGuides);
+    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, importUpdate: PlatformImportUpdate, icons: PluginIcons, appearance: AppearanceService, clientBuilds: ClientBuilds, guides: PluginGuides);
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
      * `application/octet-stream`, at most `packages.maxBytes`): reads and checks the whole plugin
@@ -108,6 +110,23 @@ export declare class AdminCatalogController {
      * is an unknown field (400 `validation_failed`).
      */
     confirm(principal: Principal, stagingId: string, body: z.infer<typeof ConfirmBody>): Promise<PluginConfirmResult>;
+    /**
+     * What confirming a staged new version of an installed platform plugin would do as the platform
+     * update (`PlatformImportUpdate`, the one 更新到 wizard): the update preview of the staged
+     * version, nothing written (cancelling the wizard leaves only the staging row). Not a platform
+     * plugin yet -> 409 `plugin.upgrade_target_invalid` (reason `not_installed`); staging missing ->
+     * 404 `plugin.staging_not_found`; otherwise as `items/:id/update/preview`.
+     */
+    importUpdatePreview(stagingId: string): Promise<PlatformUpdatePreview>;
+    /**
+     * Imports the staged version and updates the platform plugin to it, confirmed with the import
+     * review's `reviewHash` and the update preview's `diffHash` (201 `{ item, update }`). Stale review
+     * -> 409 `plugin.review_stale`, stale preview -> 409 `plugin.upgrade_stale`, another update
+     * running -> 409 `plugin.install_in_progress`: nothing written. The update failing after the
+     * import -> 409 `plugin.imported_not_updated` (the version stays in the catalog, the platform on
+     * its version, the extension's approval put back; details name the cause).
+     */
+    importAndUpdate(principal: Principal, stagingId: string, body: z.infer<typeof CatalogImportUpdateBody>): Promise<PlatformImportUpdateResult>;
     /**
      * The item list (`includeDeleted=true` includes deleted items). Paging: `limit` (default 200, at
      * most 1000) and `offset`; `nextOffset` is the next page's offset, null when there is none.

package/dist/catalog/admin-catalog.controller.js

@@ -16,13 +16,14 @@ import { PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
-import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogImportUpdateBody, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
 import { AppearanceApplyBody } from "./appearance.schemas.js";
 import { AppearanceService, suggestedAppearanceOf, } from "./appearance.service.js";
 import { CatalogService, } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { sendCatalogIcon } from "./org-catalog.controller.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
+import { PlatformImportUpdate } from "./platform-import-update.js";
 import { PluginImport } from "./plugin-import.js";
 import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
 const ConfirmBody = z
@@ -66,6 +67,8 @@ class CatalogUpdatePreviewBodyDto extends createZodDto(CatalogUpdatePreviewBody,
 }
 class CatalogUpdateBodyDto extends createZodDto(CatalogUpdateBody, "CatalogUpdateBody") {
 }
+class CatalogImportUpdateBodyDto extends createZodDto(CatalogImportUpdateBody, "CatalogImportUpdateBody") {
+}
 class AppearanceApplyBodyDto extends createZodDto(AppearanceApplyBody, "AppearanceApplyBody") {
 }
 /**
@@ -80,16 +83,18 @@ let AdminCatalogController = class AdminCatalogController {
     orgCatalog;
     scope;
     updater;
+    importUpdate;
     icons;
     appearance;
     clientBuilds;
     guides;
-    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons, appearance, clientBuilds, guides) {
+    constructor(catalog, pluginImport, orgCatalog, scope, updater, importUpdate, icons, appearance, clientBuilds, guides) {
         this.catalog = catalog;
         this.pluginImport = pluginImport;
         this.orgCatalog = orgCatalog;
         this.scope = scope;
         this.updater = updater;
+        this.importUpdate = importUpdate;
         this.icons = icons;
         this.appearance = appearance;
         this.clientBuilds = clientBuilds;
@@ -169,6 +174,28 @@ let AdminCatalogController = class AdminCatalogController {
             ...(body.orgs !== undefined && { orgs: body.orgs }),
         }, actorOpts(actor));
     }
+    /**
+     * What confirming a staged new version of an installed platform plugin would do as the platform
+     * update (`PlatformImportUpdate`, the one 更新到 wizard): the update preview of the staged
+     * version, nothing written (cancelling the wizard leaves only the staging row). Not a platform
+     * plugin yet -> 409 `plugin.upgrade_target_invalid` (reason `not_installed`); staging missing ->
+     * 404 `plugin.staging_not_found`; otherwise as `items/:id/update/preview`.
+     */
+    importUpdatePreview(stagingId) {
+        return this.importUpdate.preview(stagingId);
+    }
+    /**
+     * Imports the staged version and updates the platform plugin to it, confirmed with the import
+     * review's `reviewHash` and the update preview's `diffHash` (201 `{ item, update }`). Stale review
+     * -> 409 `plugin.review_stale`, stale preview -> 409 `plugin.upgrade_stale`, another update
+     * running -> 409 `plugin.install_in_progress`: nothing written. The update failing after the
+     * import -> 409 `plugin.imported_not_updated` (the version stays in the catalog, the platform on
+     * its version, the extension's approval put back; details name the cause).
+     */
+    importAndUpdate(principal, stagingId, body) {
+        const actor = requireUser(principal);
+        return this.importUpdate.confirm(actor.account.id, stagingId, body, actorOpts(actor));
+    }
     /**
      * The item list (`includeDeleted=true` includes deleted items). Paging: `limit` (default 200, at
      * most 1000) and `offset`; `nextOffset` is the next page's offset, null when there is none.
@@ -367,6 +394,17 @@ __decorate([
     __param(1, Param("stagingId")),
     __param(2, ZBody(CatalogImportConfirmBody))
 ], AdminCatalogController.prototype, "confirm", null);
+__decorate([
+    Get("imports/:stagingId/update-preview"),
+    __param(0, Param("stagingId"))
+], AdminCatalogController.prototype, "importUpdatePreview", null);
+__decorate([
+    Post("imports/:stagingId/update"),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("stagingId")),
+    __param(2, ZBody(CatalogImportUpdateBodyDto))
+], AdminCatalogController.prototype, "importAndUpdate", null);
 __decorate([
     Get("items"),
     __param(0, ZQuery(CatalogItemsQueryDto))
@@ -457,9 +495,10 @@ AdminCatalogController = __decorate([
     __param(2, Inject(OrgCatalogService)),
     __param(3, Inject(CatalogScopeService)),
     __param(4, Inject(PlatformPluginUpdater)),
-    __param(5, Inject(PluginIcons)),
-    __param(6, Inject(AppearanceService)),
-    __param(7, Inject(ClientBuilds)),
-    __param(8, Inject(PluginGuides))
+    __param(5, Inject(PlatformImportUpdate)),
+    __param(6, Inject(PluginIcons)),
+    __param(7, Inject(AppearanceService)),
+    __param(8, Inject(ClientBuilds)),
+    __param(9, Inject(PluginGuides))
 ], AdminCatalogController);
 export { AdminCatalogController };

package/dist/catalog/admin-catalog.schemas.d.ts

@@ -20,6 +20,11 @@ export declare const CatalogUpdateBody: z.ZodObject<{
     version: z.ZodString;
     diffHash: z.ZodString;
 }, z.core.$strict>;
+/** `POST imports/:stagingId/update`: the import review's hash and the update preview's. */
+export declare const CatalogImportUpdateBody: z.ZodObject<{
+    reviewHash: z.ZodString;
+    diffHash: z.ZodString;
+}, z.core.$strict>;
 /** `:id` as the routes take it (`@Param`). */
 export declare const CatalogIdPathParams: z.ZodObject<{
     id: z.ZodString;

package/dist/catalog/admin-catalog.schemas.js

@@ -13,6 +13,10 @@ export const CatalogUpdatePreviewBody = z.object({ version: CatalogVersion }).st
 export const CatalogUpdateBody = z
     .object({ version: CatalogVersion, diffHash: CatalogHash })
     .strict();
+/** `POST imports/:stagingId/update`: the import review's hash and the update preview's. */
+export const CatalogImportUpdateBody = z
+    .object({ reviewHash: CatalogHash, diffHash: CatalogHash })
+    .strict();
 /** `:id` as the routes take it (`@Param`). */
 export const CatalogIdPathParams = z.object({ id: z.string().min(1) });
 /** `:stagingId` of a staged import as the route takes it (`@Param`). */
@@ -75,6 +79,10 @@ export const ADMIN_CATALOG_ROUTES = [
     { route: "POST /api/v1/admin/catalog/import/npm", body: CatalogNpmImportBody },
     { route: "POST /api/v1/admin/catalog/import/git", body: CatalogGitImportBody },
     { route: "GET /api/v1/admin/catalog/imports/:stagingId", params: CatalogStagingPathParams },
+    {
+        route: "GET /api/v1/admin/catalog/imports/:stagingId/update-preview",
+        params: CatalogStagingPathParams,
+    },
     {
         route: "POST /api/v1/admin/catalog/items/:id/scope/preview",
         params: CatalogIdPathParams,

package/dist/catalog/catalog.module.d.ts

@@ -2,7 +2,8 @@ import { CatalogImportModule } from "./catalog-import.module.js";
 export { CatalogImportModule };
 /**
  * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, org installs
- * with their dependencies, the platform plugin update (`PlatformPluginUpdater`), the admin's scope
+ * with their dependencies, the platform plugin update (`PlatformPluginUpdater`) and the update to a
+ * staged version (`PlatformImportUpdate`), the admin's scope
  * and disable
  * (`CatalogScopeService`), org admins' plugin uploads (`OrgPluginUploads`) and their own plugins (`OwnedItems`), and the producer of the plugin scope sync
  * (`PluginScopeSync`; its consumer is the worker role's `PluginScopeWorkersModule`). The catalog's periodic jobs (`CatalogJobs`) are

package/dist/catalog/catalog.module.js

@@ -21,6 +21,7 @@ import { OrgCatalogService } from "./org-catalog.service.js";
 import { OrgExtensionSwitch } from "./org-extension-switch.js";
 import { OrgPluginUploads } from "./org-plugin-uploads.js";
 import { OwnedItems } from "./owned-items.js";
+import { PlatformImportUpdate } from "./platform-import-update.js";
 import { PluginInstaller } from "./plugin-install.js";
 import { PlatformPluginUpdater } from "./plugin-upgrade.js";
 import { CatalogRequestsService } from "./requests.service.js";
@@ -32,7 +33,8 @@ const PLUGIN_SCOPE_QUEUE_MODULE = QueueModule.registerQueue(PLUGIN_SCOPE_QUEUE);
 const MAINTENANCE_QUEUE_MODULE = QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME);
 /**
  * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, org installs
- * with their dependencies, the platform plugin update (`PlatformPluginUpdater`), the admin's scope
+ * with their dependencies, the platform plugin update (`PlatformPluginUpdater`) and the update to a
+ * staged version (`PlatformImportUpdate`), the admin's scope
  * and disable
  * (`CatalogScopeService`), org admins' plugin uploads (`OrgPluginUploads`) and their own plugins (`OwnedItems`), and the producer of the plugin scope sync
  * (`PluginScopeSync`; its consumer is the worker role's `PluginScopeWorkersModule`). The catalog's periodic jobs (`CatalogJobs`) are
@@ -69,6 +71,7 @@ CatalogModule = __decorate([
             ComponentScopeService,
             OrgPluginUploads,
             OwnedItems,
+            PlatformImportUpdate,
         ],
         exports: [
             PLUGIN_SCOPE_QUEUE_MODULE,
@@ -84,6 +87,7 @@ CatalogModule = __decorate([
             ComponentScopeService,
             OrgPluginUploads,
             OwnedItems,
+            PlatformImportUpdate,
         ],
     })
 ], CatalogModule);

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.17";
+    readonly sdk: "0.1.0-rc.18";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

package/dist/catalog/platform-import-update.d.ts

@@ -0,0 +1,50 @@
+import type { KernelLogger } from "../log.js";
+import type { ActorOpts, CatalogItemView } from "./catalog.service.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, type PlatformUpdatePreview, type PlatformUpdateResult } from "./plugin-upgrade.js";
+/** `POST /api/v1/admin/catalog/imports/:stagingId/update`: the import and the update it applied. */
+export interface PlatformImportUpdateResult {
+    item: CatalogItemView;
+    update: PlatformUpdateResult;
+}
+/**
+ * The platform's update of an installed plugin to a version staged for import (the one wizard of
+ * the admin plugin pages, maintainer decision 2026-11-13): the import review (prepared as any
+ * import, `PluginImport.prepare`) and the platform update preview of the staged version
+ * ({@link preview}: `PlatformPluginUpdater.previewStaged`, the target read from the staging) are
+ * confirmed together ({@link confirm} with the review's `reviewHash` and the preview's `diffHash`).
+ * Nothing is written before that confirm: cancelling the wizard leaves only the staging row, which
+ * expires like any staged import.
+ *
+ * The confirm holds the item's update lock (`PlatformPluginUpdater.withItemLock`, one per item
+ * across replicas: another update -> 409 `plugin.install_in_progress`), recomputes the preview
+ * (another `diffHash` -> 409 `plugin.upgrade_stale`, nothing written), commits the import without
+ * deploying its extension (the permission snapshot is written as the review approved it), then
+ * runs the platform update, which moves the extension with its own rollback and writes the
+ * components in one transaction. When that update fails, the platform stays on its version, the
+ * extension where it was and its previous approval is put back; the imported version stays in the
+ * catalog (its 版本 tab, and 更新到 retries the update with the plain update preview): 409
+ * `plugin.imported_not_updated` says so, with the cause in the details. No in-process state.
+ */
+export declare class PlatformImportUpdate {
+    private readonly pluginImport;
+    private readonly updater;
+    private readonly log;
+    constructor(pluginImport: PluginImport, updater: PlatformPluginUpdater, log: KernelLogger);
+    /**
+     * The platform update the staged version would apply (writes nothing). The staging must be a
+     * platform staging (else 404 `plugin.staging_not_found`) of a new version of a live
+     * platform-owned plugin (else 409 `plugin.upgrade_target_invalid`, reason `not_installed`); the
+     * updater's refusals apply as for any update preview. `needsApproval` is false: the confirm
+     * approves the permissions the review shows.
+     */
+    preview(stagingId: string): Promise<PlatformUpdatePreview>;
+    /** Confirms the import and the update together (see the class comment). */
+    confirm(actor: string, stagingId: string, input: {
+        reviewHash: string;
+        diffHash: string;
+    }, opts?: ActorOpts): Promise<PlatformImportUpdateResult>;
+    /** The staged target, which must be a new version of a live platform-owned plugin. */
+    private target;
+    private previewOf;
+}