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

package/dist/background/stop.js

@@ -13,30 +13,10 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { BackgroundTaskFinisher, } from "./finish.js";
-import { TASKS_DIR } from "./launch.js";
-import { actingAs, assertTaskRef, decodeTail, killSession, tailCommand, taskActor, } from "./session.js";
+import { actingAs, assertTaskRef, decodeTail, killSession, TERM_EXEC_TIMEOUT_MS, tailCommand, taskActor, termScript, } from "./session.js";
 import { BackgroundTaskStore } from "./store.js";
-/** How long a stop waits after SIGTERM before SIGKILL (spec §2.3). */
-export const STOP_GRACE_MS = 5000;
-/** The time limit of the SIGTERM exec: the grace period plus some room. */
-const TERM_EXEC_TIMEOUT_MS = STOP_GRACE_MS + 5000;
 /** The time limit of reading the last lines after a stop. */
 const TAIL_EXEC_TIMEOUT_MS = 10_000;
-/**
- * Exit code 0 with `exited <code>` when the task had already finished (its exit file exists),
- * else sends SIGTERM to the session and waits up to {@link STOP_GRACE_MS} for it to empty, then
- * prints `term`. Relative to the workspace root.
- */
-function termScript(id, sid) {
-    const f = `${TASKS_DIR}/${id}`;
-    const tries = Math.ceil(STOP_GRACE_MS / 200);
-    return [
-        `if [ -s ${f}.exit ]; then echo "exited $(cat ${f}.exit)"; exit 0; fi`,
-        `pkill -TERM -s ${sid} >/dev/null 2>&1`,
-        `i=0; while [ "$i" -lt ${tries} ] && pgrep -s ${sid} >/dev/null 2>&1; do sleep 0.2; i=$((i+1)); done`,
-        "echo term",
-    ].join("\n");
-}
 /** How a task that exited by itself ends (spec §4.3): exit 137 past its deadline timed out. */
 export function exitedAs(task, code, now) {
     if (code === 0)

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

@@ -72,6 +72,11 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template file says `defaultEnabled: false`: it starts switched off in every org, so the
+     * install wizard does not ask for it (an org admin sets it up when switching it on).
+     */
+    defaultOff: 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).

package/dist/catalog/catalog-content.js

@@ -29,6 +29,7 @@ export function orgTemplateView(id, file, guide = null) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        defaultOff: file.defaultEnabled === false,
         guide,
     };
 }

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.16";
+    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;
+}

package/dist/catalog/platform-import-update.js

@@ -0,0 +1,116 @@
+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 } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
+const notInstalled = (name) => new ApiError("plugin.upgrade_target_invalid", `Plugin ${name} is not a platform plugin of this deployment yet; install it with the import review instead`, [{ reason: "not_installed" }]);
+/**
+ * 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.
+ */
+let PlatformImportUpdate = class PlatformImportUpdate {
+    pluginImport;
+    updater;
+    log;
+    constructor(pluginImport, updater, log) {
+        this.pluginImport = pluginImport;
+        this.updater = updater;
+        this.log = log;
+    }
+    /**
+     * 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.
+     */
+    async preview(stagingId) {
+        const st = await this.target(stagingId);
+        return this.previewOf(st);
+    }
+    /** Confirms the import and the update together (see the class comment). */
+    async confirm(actor, stagingId, input, opts = {}) {
+        const st = await this.target(stagingId);
+        return this.updater.withItemLock(st.itemId, async () => {
+            const preview = await this.previewOf(st);
+            if (preview.diffHash !== input.diffHash) {
+                throw new ApiError("plugin.upgrade_stale", `What updating plugin ${preview.name} to ${st.version} does changed since the preview; preview it again`);
+            }
+            // The review hash is checked by the import's confirm (409 plugin.review_stale, nothing
+            // written)
+            const imported = await this.pluginImport.confirm(actor, stagingId, { reviewHash: input.reviewHash, deploy: false }, opts);
+            try {
+                const update = await this.updater.updateHeld(actor, st.itemId, { version: st.version, diffHash: input.diffHash }, opts);
+                return { item: await this.pluginImport.view(st.itemId), update };
+            }
+            catch (e) {
+                let restored = imported.approval === undefined;
+                if (imported.approval !== undefined) {
+                    try {
+                        restored = await this.pluginImport.restoreApproval(actor, imported.approval, opts);
+                    }
+                    catch (err) {
+                        this.log.error("cannot restore an extension's approval after a failed update", {
+                            itemId: st.itemId,
+                            err,
+                        });
+                    }
+                }
+                const cause = e instanceof ApiError ? e : undefined;
+                throw new ApiError("plugin.imported_not_updated", `Version ${st.version} of plugin ${preview.name} was imported, but updating the platform to it failed (${cause?.code ?? "internal"}); the platform stays on ${preview.from ?? "(none)"}. Update to ${st.version} from the plugin's page to retry`, [
+                    {
+                        version: st.version,
+                        from: preview.from,
+                        code: cause?.code ?? "internal",
+                        ...(cause !== undefined && { message: cause.message }),
+                        ...(cause?.details !== undefined && { causeDetails: cause.details }),
+                        approvalRestored: restored,
+                    },
+                ]);
+            }
+        });
+    }
+    /** The staged target, which must be a new version of a live platform-owned plugin. */
+    async target(stagingId) {
+        const st = await this.pluginImport.stagedTarget(stagingId);
+        if (!st.existing) {
+            throw notInstalled((await this.pluginImport.staged(stagingId)).review.name);
+        }
+        return st;
+    }
+    async previewOf(st) {
+        const p = await this.updater.previewStaged(st.itemId, st.version, st.target);
+        return p.extension === null ? p : { ...p, extension: { ...p.extension, needsApproval: false } };
+    }
+};
+PlatformImportUpdate = __decorate([
+    Injectable(),
+    __param(0, Inject(PluginImport)),
+    __param(1, Inject(PlatformPluginUpdater)),
+    __param(2, Inject(KERNEL_LOGGER))
+], PlatformImportUpdate);
+export { PlatformImportUpdate };

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

@@ -8,6 +8,7 @@ import { ExtensionBlobs } from "../extensions/blobs.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
 import { PluginApproveLock, PluginInstallLock } from "../extensions/locks.js";
 import { ExtensionPackageError } from "../extensions/package.js";
+import { type PermissionSet } from "../extensions/permission-set.js";
 import { type PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import type { SingleProviderBlock } from "../extensions/single-provider.js";
@@ -317,6 +318,18 @@ export interface PluginConfirmResult {
      * extension (applied at once, plan Task 6).
      */
     firstVersion: boolean;
+    /**
+     * A confirm with `deploy: false` that approved the extension's permissions (its snapshot
+     * written): what {@link PluginImport.restoreApproval} needs to put the previous approval back
+     * when the step that was to deploy it fails. Never sent over HTTP (the route always deploys).
+     */
+    approval?: HeldApproval;
+}
+/** The approval a confirm without its deploy wrote (see {@link PluginConfirmResult.approval}). */
+export interface HeldApproval {
+    review: PluginReview;
+    extension: PluginReviewExtension;
+    previous: PreviousSnapshot | null;
 }
 /** What prepare checks besides the package itself (npm and marketplace imports). */
 export interface PluginPrepareExpect {
@@ -338,6 +351,14 @@ export interface ReviewProvenance {
     provenance: ProvenanceResult;
     warning?: "repository_mismatch";
 }
+/** The snapshot overwritten at confirm (restored when deploying an upgrade fails). */
+export interface PreviousSnapshot {
+    version: string;
+    permissions: PermissionSet;
+    approvedBy: string | null;
+    approvedAt: Date;
+    source: "auto" | "web" | "cli" | "bootstrap";
+}
 /** What an org's staged upload targets (see {@link PluginImport.stagedTarget}). */
 export interface StagedTarget {
     itemId: string;
@@ -521,8 +542,10 @@ export declare class PluginImport {
      * whether the item exists (a new version of the org's own plugin) or the version is imported
      * already (F4), and the target as the platform updater reads it: the staged manifest and files,
      * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     * Without `owner`: a platform staging, and `existing` means a live platform-owned item (the
+     * platform's import and update, `PlatformImportUpdate`).
      */
-    stagedTarget(stagingId: string, owner: ImportOwner): Promise<StagedTarget>;
+    stagedTarget(stagingId: string, owner?: ImportOwner): Promise<StagedTarget>;
     /** The catalog item's view (as a confirm returns it). */
     view(itemId: string): Promise<CatalogItemView>;
     /**
@@ -553,6 +576,13 @@ export declare class PluginImport {
         orgs?: string[];
         /** An org upload's new item: shared with other orgs by its owner (default false, P3-16). */
         shareable?: boolean;
+        /**
+         * Deploy the extension after the commit (default true). false (the platform's import and
+         * update, `PlatformImportUpdate`) leaves the deployment to the platform update that follows,
+         * which moves the extension with its own rollback; the approval written is returned in
+         * `approval`.
+         */
+        deploy?: boolean;
     }, opts?: ActorOpts & {
         owner?: ImportOwner;
     }): Promise<PluginConfirmResult>;
@@ -603,6 +633,11 @@ export declare class PluginImport {
      * admin (the package is already in the package store) with the sha256 from the result.
      */
     private deploy;
+    /**
+     * Puts back the approval a confirm with `deploy: false` wrote, after the step that was to deploy
+     * the extension failed (see {@link restoreSnapshot}; false when someone changed it meanwhile).
+     */
+    restoreApproval(actor: string | null, held: HeldApproval, opts?: ActorOpts): Promise<boolean>;
     /**
      * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
      * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the