@cjhyy/code-shell-server 0.9.44 → 0.9.47

package/dist/mobile-remote/room-process-stop.js

@@ -0,0 +1,28 @@
+/** Retire an unusable room transport without leaving an unresponsive CLI alive. */
+export function stopRoomProcess(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const signal = (value) => {
+        if (child.pid && child.pid > 1 && process.platform !== "win32") {
+            try {
+                process.kill(-child.pid, value);
+                return;
+            }
+            catch {
+                /* A failed spawn or an exited group falls back to the exact child. */
+            }
+        }
+        try {
+            child.kill(value);
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    signal("SIGTERM");
+    if (!child.pid)
+        return;
+    const timer = setTimeout(() => signal("SIGKILL"), 1_000);
+    timer.unref();
+    child.once("exit", () => clearTimeout(timer));
+}

package/dist/model-trace-history.d.ts

@@ -0,0 +1,29 @@
+import { ModelTraceStore, type ModelTraceConfig, type ModelTraceConfigPatch, type ModelTraceEvent, type ModelTraceListQuery, type ModelTracePage, type ModelTraceSessionPage, type ModelTraceRecord } from "@cjhyy/code-shell-core/internal";
+export type ModelTraceDetail = {
+    record: ModelTraceRecord;
+    events: ModelTraceEvent[];
+};
+export type ModelTraceReader = Pick<ModelTraceStore, "list" | "sessions" | "get" | "events" | "getConfig" | "setConfig">;
+export declare class ModelTraceRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Never forward renderer/browser-owned filesystem paths or unknown scan options. */
+export declare function validateModelTraceQuery(input?: unknown): ModelTraceListQuery;
+export declare function validateModelTraceId(input: unknown): string;
+export declare function validateModelTraceConfigPatch(input: unknown): ModelTraceConfigPatch;
+/** Host fixes storageDir once; no query or request can select a different store. */
+export declare function createModelTraceHistory(options: {
+    storageDir: string;
+    /** Set only by the authenticated Host, never by list/get arguments. */
+    workspacePath?: string;
+    /** Additional scopes fixed and authorized by the Host, never by list/get input. */
+    workspaceScopes?: ModelTraceListQuery["workspaceScopes"];
+    store?: ModelTraceReader;
+}): {
+    list(query?: unknown): ModelTracePage;
+    sessions(query?: unknown): ModelTraceSessionPage;
+    get(id: unknown): ModelTraceDetail | null;
+    getConfig(): ModelTraceConfig;
+    setConfig(patch: unknown): ModelTraceConfig;
+};

package/dist/model-trace-history.js

@@ -0,0 +1,198 @@
+import { ModelTraceStore, isModelTraceCallType, } from "@cjhyy/code-shell-core/internal";
+import { resolve } from "node:path";
+const QUERY_FIELDS = new Set([
+    "limit",
+    "cursor",
+    "search",
+    "traceId",
+    "sessionId",
+    "withoutSession",
+    "model",
+    "provider",
+    "purpose",
+    "callType",
+    "source",
+    "status",
+    "since",
+    "until",
+]);
+const CONFIG_FIELDS = new Set(["enabled", "captureContent", "includeEphemeral", "retentionDays"]);
+export class ModelTraceRequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function record(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ModelTraceRequestError(400, `Invalid model trace ${label}`);
+    return value;
+}
+/** Never forward renderer/browser-owned filesystem paths or unknown scan options. */
+export function validateModelTraceQuery(input) {
+    if (input === undefined)
+        return {};
+    const query = record(input, "query");
+    const result = {};
+    for (const [key, value] of Object.entries(query)) {
+        if (!QUERY_FIELDS.has(key))
+            throw new ModelTraceRequestError(400, `Unknown model trace query field: ${key}`);
+        if (value === undefined)
+            continue;
+        if (key === "callType") {
+            if (!isModelTraceCallType(value))
+                throw new ModelTraceRequestError(400, "Invalid model trace callType");
+        }
+        else if (key === "withoutSession") {
+            if (typeof value !== "boolean")
+                throw new ModelTraceRequestError(400, "Invalid model trace withoutSession");
+        }
+        else if (key === "limit") {
+            if (!Number.isSafeInteger(value) || value < 1 || value > 200)
+                throw new ModelTraceRequestError(400, "Model trace limit must be between 1 and 200");
+        }
+        else if (key === "since" || key === "until") {
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+                throw new ModelTraceRequestError(400, `Invalid model trace ${key}`);
+        }
+        else {
+            const max = key === "search" || key === "cursor" ? 2048 : 512;
+            if (typeof value !== "string" || value.length > max || value.includes("\0"))
+                throw new ModelTraceRequestError(400, `Invalid model trace ${key}`);
+            if (key === "status" && !["running", "completed", "failed", "cancelled"].includes(value))
+                throw new ModelTraceRequestError(400, "Invalid model trace status");
+        }
+        result[key] = value;
+    }
+    if (typeof result.since === "number" &&
+        typeof result.until === "number" &&
+        result.since > result.until)
+        throw new ModelTraceRequestError(400, "Model trace time range is reversed");
+    return result;
+}
+export function validateModelTraceId(input) {
+    if (typeof input !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(input))
+        throw new ModelTraceRequestError(400, "Invalid model trace id");
+    return input;
+}
+export function validateModelTraceConfigPatch(input) {
+    const patch = record(input, "configuration");
+    for (const [key, value] of Object.entries(patch)) {
+        if (!CONFIG_FIELDS.has(key))
+            throw new ModelTraceRequestError(400, `Unknown model trace configuration field: ${key}`);
+        if ((key === "enabled" || key === "captureContent" || key === "includeEphemeral") &&
+            typeof value !== "boolean")
+            throw new ModelTraceRequestError(400, `Invalid model trace ${key}`);
+        if (key === "retentionDays" &&
+            (!Number.isSafeInteger(value) || value < 1 || value > 365))
+            throw new ModelTraceRequestError(400, "Model trace retention must be between 1 and 365 days");
+    }
+    return { ...patch };
+}
+/** Host fixes storageDir once; no query or request can select a different store. */
+export function createModelTraceHistory(options) {
+    const store = options.store ?? new ModelTraceStore({ storageDir: options.storageDir });
+    const workspacePath = options.workspacePath === undefined ? undefined : resolve(options.workspacePath);
+    if (options.workspaceScopes !== undefined &&
+        (!Array.isArray(options.workspaceScopes) ||
+            options.workspaceScopes.length + (workspacePath === undefined ? 0 : 1) > 8 ||
+            options.workspaceScopes.some((scope) => !scope ||
+                typeof scope !== "object" ||
+                Array.isArray(scope) ||
+                Object.keys(scope).some((field) => !["workspacePath", "sourcePrefix"].includes(field)) ||
+                typeof scope.workspacePath !== "string" ||
+                !scope.workspacePath ||
+                scope.workspacePath.length > 4096 ||
+                scope.workspacePath.includes("\0") ||
+                (scope.sourcePrefix !== undefined &&
+                    (typeof scope.sourcePrefix !== "string" ||
+                        !scope.sourcePrefix ||
+                        scope.sourcePrefix.length > 256 ||
+                        scope.sourcePrefix.includes("\0"))))))
+        throw new ModelTraceRequestError(500, "Invalid Host model trace scopes");
+    const scopes = options.workspaceScopes
+        ? [
+            ...(workspacePath === undefined ? [] : [{ workspacePath }]),
+            ...options.workspaceScopes.map((scope) => ({
+                ...scope,
+                workspacePath: resolve(scope.workspacePath),
+            })),
+        ]
+        : undefined;
+    const matchesPath = (entry, path) => entry.workspacePath !== undefined && resolve(entry.workspacePath) === path;
+    const unrestricted = (entry) => scopes
+        ? scopes.some((scope) => scope.sourcePrefix === undefined && matchesPath(entry, scope.workspacePath))
+        : workspacePath === undefined || matchesPath(entry, workspacePath);
+    const visible = (entry) => unrestricted(entry) ||
+        !!scopes?.some((scope) => matchesPath(entry, scope.workspacePath) &&
+            typeof entry.source === "string" &&
+            scope.sourcePrefix !== undefined &&
+            entry.source.startsWith(scope.sourcePrefix));
+    const visibleEvents = (entry) => {
+        const events = store.events(entry.traceId);
+        const accepted = new Set(events.filter(unrestricted).map((event) => event.id));
+        // Events do not carry a source. A prefix-limited related scope may only
+        // expose the exact selected call's descendants, never another root chat's
+        // events merely because they share a trace identifier.
+        const children = new Map();
+        if (entry.workspacePath !== undefined)
+            for (const event of events)
+                if (event.parentId && matchesPath(event, resolve(entry.workspacePath))) {
+                    const siblings = children.get(event.parentId) ?? [];
+                    siblings.push(event);
+                    children.set(event.parentId, siblings);
+                }
+        const queue = [entry.id];
+        const visited = new Set(queue);
+        for (let index = 0; index < queue.length; index++)
+            for (const event of children.get(queue[index]) ?? [])
+                if (!visited.has(event.id)) {
+                    visited.add(event.id);
+                    accepted.add(event.id);
+                    queue.push(event.id);
+                }
+        return events.filter((event) => accepted.has(event.id));
+    };
+    return {
+        list(query) {
+            const validated = validateModelTraceQuery(query);
+            return store.list({
+                ...validated,
+                ...(scopes
+                    ? { workspaceScopes: scopes }
+                    : workspacePath === undefined
+                        ? {}
+                        : { workspacePath }),
+            });
+        },
+        sessions(query) {
+            const validated = validateModelTraceQuery(query);
+            try {
+                return store.sessions({
+                    ...validated,
+                    ...(scopes
+                        ? { workspaceScopes: scopes }
+                        : workspacePath === undefined
+                            ? {}
+                            : { workspacePath }),
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === "Invalid model trace session cursor")
+                    throw new ModelTraceRequestError(400, error.message);
+                throw error;
+            }
+        },
+        get(id) {
+            const entry = store.get(validateModelTraceId(id));
+            return entry && visible(entry) ? { record: entry, events: visibleEvents(entry) } : null;
+        },
+        getConfig() {
+            return store.getConfig();
+        },
+        setConfig(patch) {
+            return store.setConfig(validateModelTraceConfigPatch(patch));
+        },
+    };
+}

package/dist/model-trace-http.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ModelTraceListQuery } from "@cjhyy/code-shell-core/internal";
+import { type ModelTraceReader } from "./model-trace-history.js";
+/** Authenticated read-only facade over one Host-owned store and one fixed workspace. */
+export declare function createModelTraceHttp(options: {
+    storageDir: string;
+    workspacePath: string;
+    isAuthorized: (request: IncomingMessage) => boolean | Promise<boolean>;
+    /** Recomputed for each authenticated request and immediately before responding. */
+    resolveWorkspaceScopes?: (request: IncomingMessage) => ModelTraceListQuery["workspaceScopes"] | Promise<ModelTraceListQuery["workspaceScopes"]>;
+    store?: ModelTraceReader;
+}): {
+    handle(request: IncomingMessage, response: ServerResponse): Promise<boolean>;
+};

package/dist/model-trace-http.js

@@ -0,0 +1,105 @@
+import { resolve } from "node:path";
+import { createModelTraceHistory, ModelTraceRequestError, } from "./model-trace-history.js";
+const ROOT = "/api/v1/model-traces";
+function json(response, status, body) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+    });
+    response.end(JSON.stringify(body));
+}
+function queryFromUrl(url) {
+    const query = {};
+    for (const key of new Set(url.searchParams.keys())) {
+        if (key === "workspace")
+            continue; // Resolved and authorized by the outer Host route.
+        const values = url.searchParams.getAll(key);
+        if (values.length !== 1)
+            throw new ModelTraceRequestError(400, "Duplicate model trace query field");
+        const value = values[0];
+        if (key === "withoutSession") {
+            if (value !== "true" && value !== "false")
+                throw new ModelTraceRequestError(400, "Invalid model trace withoutSession");
+            query[key] = value === "true";
+        }
+        else if (["limit", "since", "until"].includes(key)) {
+            if (!value.trim())
+                throw new ModelTraceRequestError(400, "Invalid numeric model trace query");
+            query[key] = Number(value);
+        }
+        else
+            query[key] = value;
+    }
+    return query;
+}
+/** Authenticated read-only facade over one Host-owned store and one fixed workspace. */
+export function createModelTraceHttp(options) {
+    const resolveScopes = async (request) => {
+        const scopes = await options.resolveWorkspaceScopes?.(request);
+        return scopes?.map((scope) => ({ ...scope, workspacePath: resolve(scope.workspacePath) }));
+    };
+    const fingerprint = (scopes) => JSON.stringify(scopes?.map((scope) => [scope.workspacePath, scope.sourcePrefix ?? null]).sort());
+    return {
+        async handle(request, response) {
+            const url = new URL(request.url ?? "/", "http://localhost");
+            if (url.pathname !== ROOT && !url.pathname.startsWith(`${ROOT}/`))
+                return false;
+            try {
+                if (!(await options.isAuthorized(request)))
+                    throw new ModelTraceRequestError(401, "Model history authorization expired");
+                if (request.method !== "GET") {
+                    response.setHeader("allow", "GET");
+                    throw new ModelTraceRequestError(405, "Model history is read-only on remote clients");
+                }
+                const workspaceScopes = await resolveScopes(request);
+                const history = createModelTraceHistory({ ...options, workspaceScopes });
+                let result;
+                if (url.pathname === ROOT)
+                    result = history.list(queryFromUrl(url));
+                else if (url.pathname === `${ROOT}/sessions`)
+                    result = history.sessions(queryFromUrl(url));
+                else if (url.pathname === `${ROOT}/config`) {
+                    if (Object.keys(queryFromUrl(url)).length)
+                        throw new ModelTraceRequestError(400, "Configuration queries are not supported");
+                    result = history.getConfig();
+                }
+                else {
+                    const match = new RegExp(`^${ROOT}/([^/]+)$`).exec(url.pathname);
+                    if (!match)
+                        throw new ModelTraceRequestError(404, "Model record not found");
+                    if (Object.keys(queryFromUrl(url)).length)
+                        throw new ModelTraceRequestError(400, "Record queries are not supported");
+                    let id;
+                    try {
+                        id = decodeURIComponent(match[1]);
+                    }
+                    catch {
+                        throw new ModelTraceRequestError(400, "Invalid model trace id");
+                    }
+                    result = history.get(id);
+                    if (!result)
+                        throw new ModelTraceRequestError(404, "Model record not found");
+                }
+                // Authentication may have been revoked during asynchronous Host validation.
+                if (!(await options.isAuthorized(request)))
+                    throw new ModelTraceRequestError(401, "Model history authorization expired");
+                if (fingerprint(await resolveScopes(request)) !== fingerprint(workspaceScopes))
+                    throw new ModelTraceRequestError(401, "Model history workspace authorization changed");
+                if (!(await options.isAuthorized(request)))
+                    throw new ModelTraceRequestError(401, "Model history authorization expired");
+                json(response, 200, result);
+            }
+            catch (error) {
+                json(response, error instanceof ModelTraceRequestError ? error.status : 500, {
+                    error: error instanceof ModelTraceRequestError
+                        ? error.message
+                        : "Model history is unavailable",
+                });
+            }
+            return true;
+        },
+    };
+}

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

@@ -341,6 +341,7 @@ export function createPanelAgentTaskHost(options = {}) {
                         cwd: scope.cwd,
                         bucket: owner.bucket,
                         task: input.prompt,
+                        modelTraceSource: `panel:${scope.appId}`,
                         displayText: input.label,
                         clientMessageId: `panel-task:${scope.appId}:${input.sessionId}`,
                         behaviorMode: "isolatedTask",

package/dist/panels/agent-task-service.d.ts

@@ -96,7 +96,8 @@ export declare class PanelAppAgentTaskService {
     get(owner: PanelAgentTaskOwner, id: unknown): PanelAgentTaskView;
     cancel(owner: PanelAgentTaskOwner, id: unknown): Promise<PanelAgentTaskView>;
     rebind(owner: PanelAgentTaskOwner): void;
-    cancelApp(appId: string): void;
+    /** `projects` limits cancellation to tasks bound to those (canonical) projects. */
+    cancelApp(appId: string, projects?: ReadonlySet<string>): void;
     private execute;
     private scopedTask;
     private emit;

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

@@ -1,4 +1,4 @@
-import { panelExecutionGate } from "./execution-gate.js";
+import { panelExecutionGate, panelExecutionProject } from "./execution-gate.js";
 import { randomUUID } from "node:crypto";
 const MAX_TASKS = 200;
 const MAX_PROMPT_CHARS = 20_000;
@@ -131,7 +131,11 @@ export class PanelAppAgentTaskService {
             cancelRequested: false,
             activity: [],
         };
-        const release = panelExecutionGate.enter(owner);
+        const release = panelExecutionGate.enter({
+            appId: owner.appId,
+            projectPath: owner.projectPath,
+            holder: { kind: "agent-task", guestId: owner.guestId },
+        });
         this.tasks.set(task.id, task);
         this.trimHistory();
         this.emit(task);
@@ -174,10 +178,13 @@ export class PanelAppAgentTaskService {
             this.runtime.rebind(task.sessionId, task.owner);
         }
     }
-    cancelApp(appId) {
+    /** `projects` limits cancellation to tasks bound to those (canonical) projects. */
+    cancelApp(appId, projects) {
         for (const task of this.tasks.values()) {
             if (task.owner.appId !== appId || TERMINAL_STATUSES.has(task.status))
                 continue;
+            if (projects && !projects.has(panelExecutionProject(task.owner.projectPath)))
+                continue;
             task.cancelRequested = true;
             task.status = "cancelling";
             task.updatedAt = this.now();

package/dist/panels/directory-bookmarks.js

@@ -12,14 +12,14 @@ export function createPanelDirectoryProjectScope(workspacePath, expectedProjectP
     const binding = createHubPanelBinding(workspacePath);
     binding.assertBinding();
     const projectPath = realpathSync(expectedProjectPath);
-    const identity = lstatSync(projectPath);
+    const identity = lstatSync(projectPath, { bigint: true });
     if (!identity.isDirectory() ||
         identity.isSymbolicLink() ||
         realpathSync(binding.bindingCwd) !== projectPath)
         throw new Error("Panel directory project scope is unavailable");
     const assertCurrent = () => {
         binding.assertBinding();
-        const current = lstatSync(projectPath);
+        const current = lstatSync(projectPath, { bigint: true });
         if (!current.isDirectory() ||
             current.isSymbolicLink() ||
             current.dev !== identity.dev ||
@@ -65,11 +65,14 @@ export function hubPanelDirectoryBookmarks(dataDir) {
 const MAX_RECORDS = 256;
 const MAX_BYTES = 256 * 1024;
 const ID = /^[a-f0-9-]{36}$/i;
-function valid(record) {
+function parseBookmark(record, version) {
+    const invalid = () => {
+        throw new Error("Invalid Panel directory bookmarks");
+    };
     if (!record || typeof record !== "object" || Array.isArray(record))
-        return false;
+        return invalid();
     const item = record;
-    return (typeof item.id === "string" &&
+    if (!(typeof item.id === "string" &&
         ID.test(item.id) &&
         typeof item.appId === "string" &&
         /^[a-z][a-z0-9-]{0,63}$/.test(item.appId) &&
@@ -79,9 +82,36 @@ function valid(record) {
         isAbsolute(item.path) &&
         item.path.length <= 32_768 &&
         item.projectPath.length <= 32_768 &&
-        Number.isSafeInteger(item.dev) &&
-        Number.isSafeInteger(item.ino) &&
-        Number.isSafeInteger(item.savedAt));
+        Number.isSafeInteger(item.savedAt)))
+        return invalid();
+    let dev, ino;
+    if (version === 1) {
+        const legacy = record;
+        if (typeof legacy.dev !== "number" ||
+            !Number.isInteger(legacy.dev) ||
+            legacy.dev < 0 ||
+            typeof legacy.ino !== "number" ||
+            !Number.isInteger(legacy.ino) ||
+            legacy.ino < 0)
+            return invalid();
+        // Never recover an authorization by rounding a file ID. Retain a tombstone
+        // so this UUID cannot fall back to a different grant in the legacy file.
+        if (!Number.isSafeInteger(legacy.dev) || !Number.isSafeInteger(legacy.ino)) {
+            dev = ino = null;
+        }
+        else {
+            dev = String(legacy.dev);
+            ino = String(legacy.ino);
+        }
+    }
+    else {
+        const exact = (value) => typeof value === "string" && /^(0|[1-9][0-9]{0,19})$/.test(value);
+        if (!(item.dev === null && item.ino === null) && !(exact(item.dev) && exact(item.ino)))
+            return invalid();
+        dev = item.dev;
+        ino = item.ino;
+    }
+    return { ...item, dev, ino };
 }
 function read(file) {
     let fd;
@@ -97,12 +127,11 @@ function read(file) {
         if (!document || typeof document !== "object" || Array.isArray(document))
             throw new Error("Invalid Panel directory bookmarks");
         const value = document;
-        if (value.version !== 1 ||
+        if ((value.version !== 1 && value.version !== 2) ||
             !Array.isArray(value.bookmarks) ||
-            value.bookmarks.length > MAX_RECORDS ||
-            !value.bookmarks.every(valid))
+            value.bookmarks.length > MAX_RECORDS)
             throw new Error("Invalid Panel directory bookmarks");
-        return value.bookmarks;
+        return value.bookmarks.map((record) => parseBookmark(record, value.version));
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -129,7 +158,7 @@ function write(file, bookmarks) {
         if (error.code !== "ENOENT")
             throw error;
     }
-    const serialized = JSON.stringify({ version: 1, bookmarks });
+    const serialized = JSON.stringify({ version: 2, bookmarks });
     if (Buffer.byteLength(serialized) > MAX_BYTES)
         throw new Error("Panel directory bookmarks are full");
     const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
@@ -154,7 +183,7 @@ export class PanelAppDirectoryBookmarks {
     remember(appId, projectPath, path) {
         if (!/^[a-z][a-z0-9-]{0,63}$/.test(appId) || !isAbsolute(projectPath) || !isAbsolute(path))
             throw new Error("Invalid Panel directory bookmark scope");
-        const info = lstatSync(path);
+        const info = lstatSync(path, { bigint: true });
         if (!info.isDirectory() || info.isSymbolicLink() || realpathSync(path) !== path)
             throw new Error("Selected directory changed; choose it again");
         const bookmark = {
@@ -162,8 +191,8 @@ export class PanelAppDirectoryBookmarks {
             appId,
             projectPath,
             path,
-            dev: info.dev,
-            ino: info.ino,
+            dev: info.dev.toString(),
+            ino: info.ino.toString(),
             savedAt: Date.now(),
         };
         mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
@@ -173,18 +202,22 @@ export class PanelAppDirectoryBookmarks {
             const existing = previous.find((item) => item.appId === appId &&
                 item.projectPath === projectPath &&
                 item.path === path &&
-                item.dev === info.dev &&
-                item.ino === info.ino);
+                item.dev === bookmark.dev &&
+                item.ino === bookmark.ino);
             if (existing)
                 bookmark.id = existing.id;
-            write(this.file, [
-                bookmark,
-                ...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));
+            const retained = previous.filter((item) => item.id !== bookmark.id &&
+                !(item.dev !== null &&
+                    item.appId === appId &&
+                    item.projectPath === projectPath &&
+                    item.path === path &&
+                    (item.dev !== bookmark.dev || item.ino !== bookmark.ino)));
+            // Keep revocations even when the bounded store evicts older live grants:
+            // forgetting one could resurrect that UUID through a legacy-file fallback.
+            const revoked = retained.filter((item) => item.dev === null);
+            if (revoked.length >= MAX_RECORDS)
+                throw new Error("Panel directory bookmarks are full");
+            write(this.file, [bookmark, ...revoked, ...retained.filter((item) => item.dev !== null)].slice(0, MAX_RECORDS));
         }
         finally {
             release();
@@ -222,11 +255,11 @@ export class PanelAppDirectoryBookmarks {
         };
         assertProjectScope();
         try {
-            const info = lstatSync(bookmark.path);
+            const info = lstatSync(bookmark.path, { bigint: true });
             if (!info.isDirectory() ||
                 info.isSymbolicLink() ||
-                info.dev !== bookmark.dev ||
-                info.ino !== bookmark.ino ||
+                info.dev.toString() !== bookmark.dev ||
+                info.ino.toString() !== bookmark.ino ||
                 realpathSync(bookmark.path) !== bookmark.path)
                 throw new Error("Saved directory changed");
         }

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

@@ -1,13 +1,29 @@
+/** What holds an execution, so a refused change can name it. Host-assigned only. */
+export interface PanelExecutionHolder {
+    kind: "panel-call" | "agent-tool" | "process" | "agent-task" | "tool-job" | "automation";
+    /** Desktop WebContents id of the Panel instance that owns this execution. */
+    guestId?: number;
+    /** Trusted Host description, such as a native tool entry name. */
+    label?: string;
+}
 export interface PanelExecutionScope {
     appId: string;
     /** Host-verified binding project, never a directory supplied by the guest. */
     projectPath: string;
+    holder?: PanelExecutionHolder;
+}
+export interface PanelExecutionBlocker extends PanelExecutionScope {
+    count: number;
 }
 /** Existing path aliases must not create separate admission domains. */
 export declare function panelExecutionProject(path: string): string;
 export declare class PanelExecutionBusyError extends Error {
+    /** Present when executions block a change; empty while another change runs. */
+    readonly blockers: PanelExecutionBlocker[];
     readonly status = 409;
-    constructor(message: string);
+    constructor(message: string, 
+    /** Present when executions block a change; empty while another change runs. */
+    blockers?: PanelExecutionBlocker[]);
 }
 /** One process owns admission for every Panel runtime sharing its installed catalog.
  * Acquire synchronously before authorization/IO; release after real execution cleanup,
@@ -21,6 +37,8 @@ export declare class PanelExecutionGate {
     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;
+    /** Executions that a change matching `matches` would wait for, grouped by holder. */
+    blockers(matches: (scope: PanelExecutionScope) => boolean): PanelExecutionBlocker[];
     mutate<T>(matches: (scope: PanelExecutionScope) => boolean, work: () => Promise<T>): Promise<T>;
 }
 export declare const panelExecutionGate: PanelExecutionGate;