@cjhyy/code-shell-server 0.9.21 → 0.9.23

package/dist/mobile-remote/remote-host-manager.js

@@ -7,6 +7,7 @@ import { WebSocketServer } from "ws";
 import { serveMobile } from "./mobile-static.js";
 import { PairingTokenManager } from "./pairing.js";
 import { parseMobileClientEvent } from "./mobile-client-event-validator.js";
+import { isRelayOrigin } from "../remote-relay/protocol.js";
 /**
  * Pick the Mac's real LAN IPv4 so a phone on the same Wi-Fi can reach the
  * remote host. We bind to a concrete LAN address (NOT 0.0.0.0) per the design's
@@ -40,6 +41,7 @@ export class RemoteHostManager extends EventEmitter {
     started;
     starting;
     stopping;
+    relayLifetime;
     pairing = new PairingTokenManager();
     /** ws → authenticated device id. A socket absent here is unauthenticated. */
     authed = new WeakMap();
@@ -111,8 +113,14 @@ export class RemoteHostManager extends EventEmitter {
         }
     }
     async startOnce(options) {
-        const tunnel = options.mode === "tunnel";
-        this.passcode = tunnel ? options.passcode : undefined;
+        const relay = options.mode === "relay";
+        const publicAccess = relay || options.mode === "tunnel";
+        if (relay && !options.passcode?.isSet()) {
+            throw new Error("Relay mode requires an initialized access passcode");
+        }
+        if (relay)
+            this.publicBaseUrl = undefined;
+        this.passcode = publicAccess ? options.passcode : undefined;
         const gate = this.passcode;
         this.opts.webApi?.start();
         const server = createServer((req, res) => {
@@ -166,7 +174,7 @@ export class RemoteHostManager extends EventEmitter {
             if (req.url && /^\/mobile(?:[/?#]|$)/.test(req.url)) {
                 serveMobile(req, res, {
                     rootDir: this.mobileRootDir,
-                    devUrl: tunnel ? undefined : this.mobileDevUrl,
+                    devUrl: publicAccess ? undefined : this.mobileDevUrl,
                 });
                 return;
             }
@@ -195,6 +203,13 @@ export class RemoteHostManager extends EventEmitter {
                     socket.destroy();
                     return;
                 }
+                if (relay &&
+                    (!this.publicBaseUrl ||
+                        req.headers.origin !== this.publicBaseUrl ||
+                        req.headers.host !== new URL(this.publicBaseUrl).host)) {
+                    socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+                    return;
+                }
                 if (!gate.allows(req)) {
                     socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
                     socket.destroy();
@@ -277,7 +292,7 @@ export class RemoteHostManager extends EventEmitter {
         // host: "lan" → resolve the Mac's real LAN IPv4 so a phone on the same
         // Wi-Fi can reach us. We bind that concrete address (never 0.0.0.0). If no
         // LAN interface is found, fall back to the requested host (e.g. localhost).
-        const bindHost = tunnel
+        const bindHost = publicAccess
             ? "127.0.0.1"
             : options.host === "lan"
                 ? (resolveLanHost() ?? "127.0.0.1")
@@ -314,11 +329,12 @@ export class RemoteHostManager extends EventEmitter {
         }
         const addr = server.address();
         const port = typeof addr === "object" && addr ? addr.port : options.port;
+        this.relayLifetime = relay ? new AbortController() : undefined;
         this.started = {
             host: bindHost,
             port,
             url: `http://${bindHost}:${port}`,
-            mode: tunnel ? "tunnel" : "lan",
+            mode: options.mode ?? "lan",
         };
         return this.started;
     }
@@ -328,11 +344,35 @@ export class RemoteHostManager extends EventEmitter {
      * address, not the loopback bind). Pass undefined to clear it.
      */
     setPublicBaseUrl(url) {
+        if (this.started?.mode === "relay" && url !== undefined && !isRelayOrigin(url)) {
+            throw new Error("Relay mode requires a canonical HTTPS origin");
+        }
         this.publicBaseUrl = url;
     }
+    /** Fixed loopback authority, revoked synchronously when this Host stops. */
+    relayTarget() {
+        const started = this.started;
+        const lifetime = this.relayLifetime;
+        if (started?.mode !== "relay" || !lifetime || lifetime.signal.aborted) {
+            throw new Error("Remote host is not running in relay mode");
+        }
+        return Object.freeze({
+            port: started.port,
+            signal: lifetime.signal,
+            setPublicBaseUrl: (origin) => {
+                lifetime.signal.throwIfAborted();
+                if (this.started !== started)
+                    throw new Error("Relay Host generation expired");
+                this.setPublicBaseUrl(origin);
+            },
+        });
+    }
     createPairingUrl() {
         if (!this.started)
             throw new Error("Remote host is not running");
+        if (this.started.mode === "relay" && !this.publicBaseUrl) {
+            throw new Error("Relay public origin is not configured");
+        }
         const token = this.pairing.createToken();
         const base = this.publicBaseUrl ?? this.started.url;
         return {
@@ -443,6 +483,9 @@ export class RemoteHostManager extends EventEmitter {
     }
     /** Call after revoking/removing a trusted device to release both transports immediately. */
     revokeDevice(deviceId) {
+        void this.opts.uploads?.revokeDevice(deviceId).catch((error) => {
+            this.emit("host-error", error instanceof Error ? error.message : String(error));
+        });
         this.opts.webApi?.revokeDevice(deviceId);
         for (const client of this.wss?.clients ?? []) {
             if (this.authed.get(client) !== deviceId)
@@ -452,6 +495,9 @@ export class RemoteHostManager extends EventEmitter {
         }
     }
     stop() {
+        // Listeners synchronously fence and destroy outbound sockets before the
+        // loopback listener can close or its port can be reused by another Host.
+        this.relayLifetime?.abort();
         if (this.stopping)
             return this.stopping;
         const attempt = Promise.resolve()
@@ -466,6 +512,8 @@ export class RemoteHostManager extends EventEmitter {
     async stopOnce() {
         if (this.starting)
             await this.starting.catch(() => undefined);
+        this.relayLifetime?.abort();
+        this.relayLifetime = undefined;
         const server = this.server;
         // Forcibly drop live WS sockets first. wss.close() alone waits for clients
         // to disconnect, so a phone left connected would hang stop() indefinitely.

package/dist/panels/agent-task-service.js

@@ -1,3 +1,4 @@
+import { panelExecutionGate } from "./execution-gate.js";
 import { randomUUID } from "node:crypto";
 const MAX_TASKS = 200;
 const MAX_PROMPT_CHARS = 20_000;
@@ -130,10 +131,11 @@ export class PanelAppAgentTaskService {
             cancelRequested: false,
             activity: [],
         };
+        const release = panelExecutionGate.enter(owner);
         this.tasks.set(task.id, task);
         this.trimHistory();
         this.emit(task);
-        void this.execute(task);
+        void this.execute(task).finally(release);
         return publicTask(task);
     }
     list(owner) {
@@ -237,7 +239,12 @@ export class PanelAppAgentTaskService {
         return task;
     }
     emit(task) {
-        this.emitChanged(task.owner, publicTask(task));
+        try {
+            this.emitChanged(task.owner, publicTask(task));
+        }
+        catch {
+            /* A disconnected viewer must not interrupt execution or cleanup. */
+        }
     }
     recordProgress(task, progress) {
         if (TERMINAL_STATUSES.has(task.status))

package/dist/panels/automations.d.ts

@@ -0,0 +1,49 @@
+import type { CronJob } from "@cjhyy/code-shell-core/internal";
+export declare const panelAutomationMethods: readonly ["automations.list", "automations.create", "automations.createUnique", "automations.update", "automations.updateIfRevision", "automations.deleteIfRevision", "automations.pause", "automations.resume", "automations.delete", "automations.runNow"];
+/** Derived by the transport; sessionId is still untrusted until the Host verifies its workspace. */
+export interface PanelAutomationScope {
+    appId: string;
+    cwd: string;
+    sessionId: string;
+    /** Host-selected installed package revision, never a field from Panel call JSON. */
+    revision?: string;
+    isAuthorized(): Promise<boolean>;
+}
+/** Borrowed Host service. A page/transport closing never stops the scheduler. */
+export interface PanelAutomationHost {
+    /** True only if revision checks happen inside the scheduler storage transaction. */
+    conditionalMutations?: boolean;
+    call(scope: PanelAutomationScope, method: string, params?: unknown): Promise<unknown>;
+}
+export declare function panelAutomationCreationKey(appId: string, cwd: string, sessionId: string, key: string): string;
+/** Definition identity excludes changing run statistics and execution receipts. */
+export declare function panelAutomationRevision(job: Readonly<CronJob>): string;
+export declare class PanelAutomationConflictError extends Error {
+    constructor();
+}
+export declare function assertPanelAutomationRevision(job: Readonly<CronJob>, expected?: string): void;
+type Definition = {
+    name: string;
+    schedule: string;
+    prompt: string;
+    timezone?: string;
+};
+export type PanelAutomationOperation = {
+    action: "list";
+} | {
+    action: "create";
+    input: Definition;
+    key?: string;
+} | {
+    action: "update";
+    id: string;
+    patch: Partial<Definition>;
+    expectedRevision?: string;
+} | {
+    action: "pause" | "resume" | "delete" | "runNow";
+    id: string;
+    expectedRevision?: string;
+};
+/** Common wire validation; authority fields are never supplied by Panel JSON. */
+export declare function parsePanelAutomationCall(method: string, params: unknown): PanelAutomationOperation;
+export {};

package/dist/panels/automations.js

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+export const panelAutomationMethods = [
+    "automations.list",
+    "automations.create",
+    "automations.createUnique",
+    "automations.update",
+    "automations.updateIfRevision",
+    "automations.deleteIfRevision",
+    "automations.pause",
+    "automations.resume",
+    "automations.delete",
+    "automations.runNow",
+];
+export function panelAutomationCreationKey(appId, cwd, sessionId, key) {
+    return `panel:${createHash("sha256")
+        .update(JSON.stringify([appId, cwd, sessionId, key]))
+        .digest("hex")}`;
+}
+/** Definition identity excludes changing run statistics and execution receipts. */
+export function panelAutomationRevision(job) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        job.id,
+        job.createdAt,
+        job.name,
+        job.schedule,
+        job.prompt,
+        job.enabled,
+        job.cwd ?? null,
+        job.projectId ?? null,
+        job.rootId ?? null,
+        job.resumeSessionId ?? null,
+        job.timezone ?? "UTC",
+        job.permissionLevel ?? "read-only",
+        job.once === true,
+        job.disabledReason ?? null,
+        job.creationKey ?? null,
+        job.panelSource?.appId ?? null,
+        job.panelSource?.revision ?? null,
+        job.templateSource?.installKey ?? null,
+        job.templateSource?.templateId ?? null,
+        job.templateSource?.revision ?? null,
+        job.templateSource?.pluginVersion ?? null,
+    ]))
+        .digest("hex");
+}
+export class PanelAutomationConflictError extends Error {
+    constructor() {
+        super("Automation changed; reload before editing or deleting it");
+    }
+}
+export function assertPanelAutomationRevision(job, expected) {
+    if (expected !== undefined && panelAutomationRevision(job) !== expected)
+        throw new PanelAutomationConflictError();
+}
+/** Common wire validation; authority fields are never supplied by Panel JSON. */
+export function parsePanelAutomationCall(method, params) {
+    if (!panelAutomationMethods.includes(method))
+        throw Error("Unknown Panel automation method");
+    if (params !== undefined && (!params || typeof params !== "object" || Array.isArray(params)))
+        throw Error("Panel automation parameters must be an object");
+    const input = (params ?? {});
+    const conditional = method.endsWith("IfRevision");
+    const action = method.slice("automations.".length).replace(/IfRevision$/, "");
+    let expectedRevision;
+    if (conditional) {
+        if (typeof input.expectedRevision !== "string" ||
+            !/^[a-f0-9]{64}$/.test(input.expectedRevision))
+            throw Error("Panel automation expectedRevision is invalid");
+        expectedRevision = input.expectedRevision;
+    }
+    const create = action === "create" || action === "createUnique";
+    const allowed = action === "list"
+        ? []
+        : create
+            ? [
+                "name",
+                "schedule",
+                "prompt",
+                "timezone",
+                "permissionLevel",
+                ...(action === "createUnique" ? ["key"] : []),
+            ]
+            : action === "update"
+                ? ["id", "name", "schedule", "prompt", "timezone"]
+                : ["id"];
+    if (conditional)
+        allowed.push("expectedRevision");
+    if (Object.keys(input).some((key) => !allowed.includes(key)))
+        throw Error("Panel automation parameters contain unsupported or authority fields");
+    if (action === "list")
+        return { action };
+    let id = "";
+    if (!create) {
+        if (typeof input.id !== "string" || !input.id.trim() || input.id.length > 128)
+            throw Error("Panel automation id is invalid");
+        id = input.id.trim();
+    }
+    if (!create && action !== "update")
+        return {
+            action: action,
+            id,
+            ...(expectedRevision ? { expectedRevision } : {}),
+        };
+    const patch = {};
+    for (const [key, limit] of [
+        ["name", 120],
+        ["schedule", 128],
+        ["prompt", 20000],
+        ["timezone", 120],
+    ]) {
+        const value = input[key];
+        if (value === undefined && (!create || key === "timezone"))
+            continue;
+        if (typeof value !== "string" || !value.trim() || value.length > limit || value.includes("\0"))
+            throw Error(`Panel automation ${key} is invalid`);
+        patch[key] = value.trim();
+    }
+    if (action === "update") {
+        if (!Object.keys(patch).length)
+            throw Error("Panel automation update is empty");
+        return { action, id, patch, ...(expectedRevision ? { expectedRevision } : {}) };
+    }
+    if (input.permissionLevel !== undefined && input.permissionLevel !== "full")
+        throw Error("Panel automation permissionLevel must be full");
+    if (action === "createUnique" &&
+        (typeof input.key !== "string" || !/^[A-Za-z0-9._:-]{1,80}$/.test(input.key)))
+        throw Error("Panel unique automation requires a bounded key");
+    return {
+        action: "create",
+        input: patch,
+        ...(action === "createUnique" ? { key: input.key } : {}),
+    };
+}

package/dist/panels/bridge-contract.d.ts

@@ -27,6 +27,7 @@ export declare function panelBridgeFailure(error: unknown): {
 };
 export declare function panelRuntimeCapabilities(input: {
     process: boolean;
+    cookieProcess?: boolean;
     resources?: unknown;
     tasks?: unknown;
     limits?: Partial<Record<keyof typeof panelBridgeLimits, number>>;
@@ -37,7 +38,8 @@ export declare function panelRuntimeCapabilities(input: {
         materialize: boolean;
         capture: boolean;
     } | undefined;
-    process?: Readonly<{
+    process?: {
+        cookieCredentials?: boolean | undefined;
         maxArguments: 256;
         maxArgumentLength: 8192;
         maxArgumentBytes: number;
@@ -58,11 +60,11 @@ export declare function panelRuntimeCapabilities(input: {
         stdinWriteTimeoutMs: 10000;
         maxEntryBytes: number;
         maxEntryHandlesPerGuest: 64;
-    }> | undefined;
+    } | undefined;
     bridge: {
         structuredErrors: boolean;
-        maxParamsBytes: number;
         maxResultBytes: number;
+        maxParamsBytes: number;
         rateWindowMs: number;
         maxCallsPerWindow: number;
         maxTransferCallsPerWindow: number;

package/dist/panels/bridge-contract.js

@@ -34,8 +34,11 @@ export const panelToolJobMethods = [
     "tasks.start",
     "tasks.list",
     "tasks.get",
+    "tasks.find",
     "tasks.cancel",
     "tasks.retry",
+    "tasks.queue.get",
+    "tasks.queue.set",
 ];
 export const panelBridgeLimits = Object.freeze({
     maxParamsBytes: 64 * 1024,
@@ -82,7 +85,14 @@ export function panelRuntimeCapabilities(input) {
             "INVALID_ARGUMENT",
             "OPERATION_FAILED",
         ],
-        ...(input.process ? { process: processLimits } : {}),
+        ...(input.process
+            ? {
+                process: {
+                    ...processLimits,
+                    ...(input.cookieProcess ? { cookieCredentials: true } : {}),
+                },
+            }
+            : {}),
         ...(input.resources
             ? {
                 resources: {

package/dist/panels/directory-bookmarks.d.ts

@@ -1,7 +1,15 @@
+import type { InstalledPanelApp } from "@cjhyy/code-shell-core";
+export type PanelDirectoryAuthorizer = (app: InstalledPanelApp, projectPath: string, workspacePath: string) => Promise<void>;
+export declare function desktopPanelDirectoryBookmarks(dataDir: string): PanelAppDirectoryBookmarks;
+/** The file mutex uses a sibling of its parent; keep both inside the data volume. */
+export declare function hubPanelDirectoryBookmarks(dataDir: string): PanelAppDirectoryBookmarks;
 /** The guest receives only a random bookmark. A path saved in guest storage grants nothing. */
 export declare class PanelAppDirectoryBookmarks {
     private readonly file;
-    constructor(file: string);
+    private readonly options;
+    constructor(file: string, options?: {
+        legacyFiles?: readonly string[];
+    });
     remember(appId: string, projectPath: string, path: string): string;
     restore(appId: string, projectPath: string, id: unknown): string;
 }

package/dist/panels/directory-bookmarks.js

@@ -1,7 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
-import { dirname, isAbsolute } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { acquireFileLock } from "@cjhyy/code-shell-core/internal";
+export function desktopPanelDirectoryBookmarks(dataDir) {
+    return new PanelAppDirectoryBookmarks(join(dataDir, "panel-app-directory-bookmarks.json"), {
+        legacyFiles: [join(dataDir, "panel-web-directory-bookmarks.json")],
+    });
+}
+/** The file mutex uses a sibling of its parent; keep both inside the data volume. */
+export function hubPanelDirectoryBookmarks(dataDir) {
+    return new PanelAppDirectoryBookmarks(join(dataDir, "panel-directories", "bookmarks.json"), {
+        legacyFiles: [join(dataDir, "panel-web-directory-bookmarks.json")],
+    });
+}
 const MAX_RECORDS = 256;
 const MAX_BYTES = 256 * 1024;
 const ID = /^[a-f0-9-]{36}$/i;
@@ -86,8 +97,10 @@ function write(file, bookmarks) {
 /** The guest receives only a random bookmark. A path saved in guest storage grants nothing. */
 export class PanelAppDirectoryBookmarks {
     file;
-    constructor(file) {
+    options;
+    constructor(file, options = {}) {
         this.file = file;
+        this.options = options;
     }
     remember(appId, projectPath, path) {
         if (!/^[a-z][a-z0-9-]{0,63}$/.test(appId) || !isAbsolute(projectPath) || !isAbsolute(path))
@@ -108,9 +121,20 @@ export class PanelAppDirectoryBookmarks {
         const release = acquireFileLock(this.file);
         try {
             const previous = read(this.file);
+            const existing = previous.find((item) => item.appId === appId &&
+                item.projectPath === projectPath &&
+                item.path === path &&
+                item.dev === info.dev &&
+                item.ino === info.ino);
+            if (existing)
+                bookmark.id = existing.id;
             write(this.file, [
                 bookmark,
-                ...previous.filter((item) => !(item.appId === appId && item.projectPath === projectPath && item.path === path)),
+                ...previous.filter((item) => item.id !== bookmark.id &&
+                    !(item.appId === appId &&
+                        item.projectPath === projectPath &&
+                        item.path === path &&
+                        (item.dev !== info.dev || item.ino !== info.ino))),
             ].slice(0, MAX_RECORDS));
         }
         finally {
@@ -121,8 +145,18 @@ export class PanelAppDirectoryBookmarks {
     restore(appId, projectPath, id) {
         if (typeof id !== "string" || !ID.test(id))
             throw new Error("Invalid directory bookmark");
-        const bookmark = read(this.file).find((item) => item.id === id && item.appId === appId && item.projectPath === projectPath);
-        if (!bookmark)
+        let bookmark = read(this.file).find((item) => item.id === id);
+        let legacy = false;
+        if (!bookmark) {
+            for (const file of this.options.legacyFiles ?? []) {
+                bookmark = read(file).find((item) => item.id === id);
+                if (bookmark) {
+                    legacy = true;
+                    break;
+                }
+            }
+        }
+        if (!bookmark || bookmark.appId !== appId || bookmark.projectPath !== projectPath)
             throw new Error("Saved directory is unavailable; choose it again");
         try {
             const info = lstatSync(bookmark.path);
@@ -136,6 +170,31 @@ export class PanelAppDirectoryBookmarks {
         catch {
             throw new Error("Saved directory changed; choose it again");
         }
+        if (legacy) {
+            mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+            const release = acquireFileLock(this.file);
+            try {
+                const previous = read(this.file);
+                const existing = previous.find((item) => item.id === id);
+                if (existing &&
+                    (existing.appId !== bookmark.appId ||
+                        existing.projectPath !== bookmark.projectPath ||
+                        existing.path !== bookmark.path ||
+                        existing.dev !== bookmark.dev ||
+                        existing.ino !== bookmark.ino))
+                    throw new Error("Saved directory identity conflicts with the current grant");
+                if (!existing) {
+                    // Migration never silently evicts another live bookmark. Preserve legacy
+                    // IDs as aliases when both interfaces previously selected the same path.
+                    if (previous.length >= MAX_RECORDS)
+                        throw new Error("Panel directory bookmarks are full");
+                    write(this.file, [bookmark, ...previous]);
+                }
+            }
+            finally {
+                release();
+            }
+        }
         return bookmark.path;
     }
 }

package/dist/panels/execution-gate.d.ts

@@ -0,0 +1,26 @@
+export interface PanelExecutionScope {
+    appId: string;
+    /** Host-verified binding project, never a directory supplied by the guest. */
+    projectPath: string;
+}
+/** Existing path aliases must not create separate admission domains. */
+export declare function panelExecutionProject(path: string): string;
+export declare class PanelExecutionBusyError extends Error {
+    readonly status = 409;
+    constructor(message: string);
+}
+/** One process owns admission for every Panel runtime sharing its installed catalog.
+ * Acquire synchronously before authorization/IO; release after real execution cleanup,
+ * not after a UI timeout, cancellation request or a terminal status notification.
+ */
+export declare class PanelExecutionGate {
+    private readonly executions;
+    private readonly sources;
+    private readonly mutations;
+    enter(scope: PanelExecutionScope): () => void;
+    run<T>(scope: PanelExecutionScope, work: () => Promise<T>): Promise<T>;
+    /** Durable queues remain occupied even while paused and between process attempts. */
+    register(source: () => Iterable<PanelExecutionScope>): () => void;
+    mutate<T>(matches: (scope: PanelExecutionScope) => boolean, work: () => Promise<T>): Promise<T>;
+}
+export declare const panelExecutionGate: PanelExecutionGate;

package/dist/panels/execution-gate.js

@@ -0,0 +1,70 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+/** Existing path aliases must not create separate admission domains. */
+export function panelExecutionProject(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export class PanelExecutionBusyError extends Error {
+    status = 409;
+    constructor(message) {
+        super(message);
+        this.name = "PanelExecutionBusyError";
+    }
+}
+/** One process owns admission for every Panel runtime sharing its installed catalog.
+ * Acquire synchronously before authorization/IO; release after real execution cleanup,
+ * not after a UI timeout, cancellation request or a terminal status notification.
+ */
+export class PanelExecutionGate {
+    executions = new Set();
+    sources = new Set();
+    mutations = new Set();
+    enter(scope) {
+        const held = { appId: scope.appId, projectPath: panelExecutionProject(scope.projectPath) };
+        if ([...this.mutations].some((matches) => matches(held)))
+            throw new PanelExecutionBusyError("面板正在更新，请完成后重试。");
+        this.executions.add(held);
+        return () => {
+            this.executions.delete(held);
+        };
+    }
+    async run(scope, work) {
+        const release = this.enter(scope);
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    /** Durable queues remain occupied even while paused and between process attempts. */
+    register(source) {
+        this.sources.add(source);
+        return () => {
+            this.sources.delete(source);
+        };
+    }
+    async mutate(matches, work) {
+        if (this.mutations.size)
+            throw new PanelExecutionBusyError("另一个面板修改正在进行，请稍后重试。");
+        // No await between the snapshot and installing the admission barrier.
+        if ([...this.executions].some(matches) ||
+            [...this.sources].some((source) => [...source()].some(matches)))
+            throw new PanelExecutionBusyError("面板还有正在提交、排队或运行的任务，请结束后再修改。");
+        this.mutations.add(matches);
+        try {
+            return await work();
+        }
+        finally {
+            this.mutations.delete(matches);
+        }
+    }
+}
+// Shared by native Desktop, its paired Web runtimes, and all Hub workspaces in this process.
+// This is not a cross-process catalog lock; management also serializes catalog writes.
+export const panelExecutionGate = new PanelExecutionGate();