@cjhyy/code-shell-server 0.9.9 → 0.9.11

package/dist/panels/process-service.js

@@ -1,19 +1,22 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { constants } from "node:fs";
+import { constants, lstatSync, realpathSync } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
 import { basename, delimiter, extname, join } from "node:path";
 import { killProcessGroup } from "@cjhyy/code-shell-core/extension";
+import { verifyProcessEntry } from "./process-entry.js";
+import { appendProcessEvent, ProcessReceipts, processLimits, sameProcessOwner, } from "./process-state.js";
+export { processLimits } from "./process-state.js";
 const EXECUTABLE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,127}$/;
 const FILE_ARGUMENT_NAME = /^--[a-zA-Z][a-zA-Z0-9-]{0,63}$/;
-const MAX_ARGUMENTS = 256;
-const MAX_ARGUMENT_LENGTH = 8_192;
-const MAX_ARGUMENT_BYTES = 64 * 1024;
-const MAX_CONCURRENT_PROCESSES = 3;
-const MAX_FILE_ARGUMENTS = 8;
-const MAX_EVENT_CHARS = 16_384;
-const MAX_PROCESS_OUTPUT_BYTES = 4 * 1024 * 1024;
-const PROCESS_LIFETIME_MS = 24 * 60 * 60 * 1_000;
+const MAX_ARGUMENTS = processLimits.maxArguments;
+const MAX_ARGUMENT_LENGTH = processLimits.maxArgumentLength;
+const MAX_ARGUMENT_BYTES = processLimits.maxArgumentBytes;
+const MAX_CONCURRENT_PROCESSES = processLimits.maxConcurrentProcesses;
+const MAX_FILE_ARGUMENTS = processLimits.maxFileArguments;
+const MAX_EVENT_CHARS = processLimits.maxEventChars;
+const MAX_PROCESS_OUTPUT_BYTES = processLimits.maxOutputBytes;
+const PROCESS_LIFETIME_MS = processLimits.maxLifetimeMs;
 export function panelProcessInfo(platform = process.platform, arch = process.arch, report = process.report?.getReport()) {
     if (platform !== "linux")
         return { platform, arch };
@@ -160,13 +163,20 @@ export class PanelAppProcessService {
     executables = new Map();
     directories = new Map();
     fileArguments = new Map();
+    entries = new Map();
     processes = new Map();
+    retiring = new Map();
+    receipts;
     approvedExecutables = new Set();
     guestEpochs = new Map();
     reservations = new Map();
     closed = false;
     constructor(options) {
         this.options = options;
+        this.receipts = new ProcessReceipts(options.now);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
     }
     epoch(owner) {
         if (this.closed)
@@ -202,7 +212,13 @@ export class PanelAppProcessService {
         if (!path)
             return { available: false, name };
         const handle = randomUUID();
-        this.executables.set(handle, { guestId: owner.guestId, name, path });
+        this.executables.set(handle, {
+            guestId: owner.guestId,
+            appId: owner.appId,
+            revision: owner.revision,
+            name,
+            path,
+        });
         return { available: true, name, handle };
     }
     async grantDirectory(owner, path) {
@@ -217,7 +233,14 @@ export class PanelAppProcessService {
         if (!info.isDirectory())
             throw new Error("selected process directory is not a directory");
         const handle = randomUUID();
-        this.directories.set(handle, { guestId: owner.guestId, path: resolved });
+        this.directories.set(handle, {
+            guestId: owner.guestId,
+            appId: owner.appId,
+            revision: owner.revision,
+            path: resolved,
+            dev: info.dev,
+            ino: info.ino,
+        });
         return { handle, path: resolved, name: basename(resolved) || resolved };
     }
     executableName(owner, handle) {
@@ -225,7 +248,7 @@ export class PanelAppProcessService {
         if (typeof handle !== "string")
             throw new Error("executable handle is required");
         const executable = this.executables.get(handle);
-        if (!executable || executable.guestId !== owner.guestId) {
+        if (!executable || !sameProcessOwner(executable, owner)) {
             throw new Error("executable handle is invalid or belongs to another Panel App");
         }
         return executable.name;
@@ -238,7 +261,7 @@ export class PanelAppProcessService {
             throw new Error("sealed file arguments require an executable handle");
         }
         const executable = this.executables.get(input.executableHandle);
-        if (!executable || executable.guestId !== owner.guestId) {
+        if (!executable || !sameProcessOwner(executable, owner)) {
             throw new Error("executable handle is invalid or belongs to another Panel App");
         }
         if (typeof input.argumentName !== "string" || !FILE_ARGUMENT_NAME.test(input.argumentName)) {
@@ -254,6 +277,8 @@ export class PanelAppProcessService {
         const handle = randomUUID();
         this.fileArguments.set(handle, {
             guestId: owner.guestId,
+            appId: owner.appId,
+            revision: owner.revision,
             executablePath: executable.path,
             argumentName: input.argumentName,
             path: resolved,
@@ -261,16 +286,85 @@ export class PanelAppProcessService {
         });
         return { handle };
     }
+    /** Seal an already authorized directory as a long-option argument for one executable. */
+    async grantDirectoryArgument(owner, input) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        this.executableName(owner, input.executableHandle);
+        if (typeof input.argumentName !== "string" || !FILE_ARGUMENT_NAME.test(input.argumentName))
+            throw new Error("sealed directory arguments require a simple long-option name");
+        const path = this.directoryPath(owner, input.directoryHandle);
+        const executable = this.executables.get(input.executableHandle);
+        const handle = randomUUID();
+        this.fileArguments.set(handle, {
+            guestId: owner.guestId,
+            appId: owner.appId,
+            revision: owner.revision,
+            executablePath: executable.path,
+            argumentName: input.argumentName,
+            path,
+            directoryHandle: input.directoryHandle,
+            cleanup: () => { },
+        });
+        return { handle };
+    }
     directoryPath(owner, handle) {
         this.epoch(owner);
         if (typeof handle !== "string")
             throw new Error("directory handle is required");
         const grant = this.directories.get(handle);
-        if (!grant || grant.guestId !== owner.guestId) {
+        if (!grant || !sameProcessOwner(grant, owner)) {
             throw new Error("directory handle is invalid or belongs to another Panel App");
         }
+        // Final synchronous identity check preserves the existing handle API and avoids
+        // an await between validating a cwd and spawning the child into that directory.
+        const current = lstatSync(grant.path);
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            current.dev !== grant.dev ||
+            current.ino !== grant.ino ||
+            realpathSync(grant.path) !== grant.path)
+            throw new Error("granted process directory changed; select it again");
         return grant.path;
     }
+    async resolveEntry(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const input = params;
+        if (!input || typeof input.name !== "string" || !EXECUTABLE_NAME.test(input.name))
+            throw new Error("process.resolveEntry requires a declared entry name");
+        this.executableName(owner, input.executableHandle);
+        if (!this.options.resolvePackageEntry)
+            throw new Error("package entries are unavailable");
+        const executableHandle = input.executableHandle;
+        const executable = this.executables.get(executableHandle);
+        const entry = await this.options.resolvePackageEntry(owner, input.name);
+        await this.authorize(owner, epoch);
+        const identity = await verifyProcessEntry(entry.path, entry.sha256);
+        const fingerprint = await executableFingerprint(executable.path);
+        await this.authorize(owner, epoch);
+        if (this.executables.get(executableHandle) !== executable)
+            throw new Error("Panel App process handles were revoked");
+        if ([...this.entries.values()].filter((grant) => grant.guestId === owner.guestId).length >=
+            processLimits.maxEntryHandlesPerGuest)
+            throw new Error("too many package entry handles");
+        const handle = randomUUID();
+        this.entries.set(handle, {
+            guestId: owner.guestId,
+            appId: owner.appId,
+            revision: owner.revision,
+            name: input.name,
+            executableHandle,
+            executablePath: executable.path,
+            executableFingerprint: fingerprint,
+            path: entry.path,
+            sha256: entry.sha256,
+            identity,
+        });
+        return { handle, name: input.name, sha256: entry.sha256 };
+    }
     async start(owner, params) {
         owner = { ...owner };
         const epoch = this.epoch(owner);
@@ -279,24 +373,38 @@ export class PanelAppProcessService {
             throw new Error("process.spawn requires an executable handle from process.find");
         }
         const executable = this.executables.get(input.executableHandle);
-        if (!executable || executable.guestId !== owner.guestId) {
+        if (!executable || !sameProcessOwner(executable, owner)) {
             throw new Error("executable handle is invalid or belongs to another Panel App");
         }
         const cwd = this.directoryPath(owner, input.directoryHandle);
+        if (input.stdin !== undefined && input.stdin !== "ignore" && input.stdin !== "pipe")
+            throw new Error("process.spawn stdin must be ignore or pipe");
+        let entry;
+        if (input.entryHandle !== undefined) {
+            entry =
+                typeof input.entryHandle === "string" ? this.entries.get(input.entryHandle) : undefined;
+            if (!entry || !sameProcessOwner(entry, owner))
+                throw new Error("package entry handle is invalid or belongs to another Panel App");
+            if (entry.executableHandle !== input.executableHandle ||
+                entry.executablePath !== executable.path)
+                throw new Error("package entry is bound to a different executable");
+        }
         const rawArgs = validateArguments(input.args);
         const fileArgumentHandles = validateFileArgumentHandles(input.fileArgumentHandles);
         const sealedArgs = [];
         for (const handle of fileArgumentHandles) {
             const grant = this.fileArguments.get(handle);
-            if (!grant || grant.guestId !== owner.guestId) {
+            if (!grant || !sameProcessOwner(grant, owner)) {
                 throw new Error("sealed file argument handle is invalid or belongs to another Panel App");
             }
             if (grant.executablePath !== executable.path) {
                 throw new Error("sealed file argument is bound to a different executable");
             }
+            if (grant.directoryHandle && this.directoryPath(owner, grant.directoryHandle) !== grant.path)
+                throw new Error("sealed directory argument was replaced");
             sealedArgs.push(grant.argumentName, grant.path);
         }
-        const args = validateArguments([...sealedArgs, ...rawArgs]);
+        const args = validateArguments([...(entry ? [entry.path] : []), ...sealedArgs, ...rawArgs]);
         const active = [...this.processes.values()].filter((process) => process.guestId === owner.guestId).length;
         const reserved = this.reservations.get(owner.guestId) ?? 0;
         if (active + reserved >= MAX_CONCURRENT_PROCESSES) {
@@ -312,6 +420,8 @@ export class PanelAppProcessService {
                 executablePath: executable.path,
                 executableFingerprint: await executableFingerprint(executable.path),
             };
+            if (entry && scope.executableFingerprint !== entry.executableFingerprint)
+                throw new Error("package entry executable changed; resolve the entry again");
             await this.authorize(owner, epoch);
             const guestScoped = this.options.approvalScope === "guest";
             const approvalKey = (guestScoped ? `${owner.guestId}\0${epoch}\0` : "") +
@@ -342,12 +452,29 @@ export class PanelAppProcessService {
                 throw new Error("resolved executable changed; find it and approve it again");
             }
             await this.authorize(owner, epoch);
+            if (entry) {
+                const current = await this.options.resolvePackageEntry(owner, entry.name);
+                if (current.path !== entry.path || current.sha256 !== entry.sha256)
+                    throw new Error("reviewed package entry changed; resolve it again");
+                await this.authorize(owner, epoch);
+                if ((await verifyProcessEntry(entry.path, entry.sha256)) !== entry.identity)
+                    throw new Error("reviewed package entry was replaced; resolve it again");
+            }
             const env = safeProcessEnv(this.options.env ?? process.env, this.options.extraPathDirectories?.() ?? []);
             this.assertLive(owner, epoch);
             if (this.executables.get(input.executableHandle) !== executable ||
-                this.directoryPath(owner, input.directoryHandle) !== cwd) {
+                this.directoryPath(owner, input.directoryHandle) !== cwd ||
+                (entry && this.entries.get(input.entryHandle) !== entry)) {
                 throw new Error("Panel App process handles were revoked");
             }
+            for (const handle of fileArgumentHandles) {
+                const grant = this.fileArguments.get(handle);
+                if (!grant || !sameProcessOwner(grant, owner))
+                    throw new Error("sealed argument was revoked");
+                if (grant.directoryHandle &&
+                    this.directoryPath(owner, grant.directoryHandle) !== grant.path)
+                    throw new Error("sealed directory argument was replaced");
+            }
             this.approvedExecutables.add(approvalKey);
             const processId = randomUUID();
             const child = spawn(executable.path, args, {
@@ -355,9 +482,28 @@ export class PanelAppProcessService {
                 detached: process.platform !== "win32",
                 env,
                 shell: false,
-                stdio: ["ignore", "pipe", "pipe"],
+                stdio: [input.stdin === "pipe" ? "pipe" : "ignore", "pipe", "pipe"],
                 windowsHide: true,
             });
+            const record = {
+                owner: { guestId: owner.guestId, appId: owner.appId, revision: owner.revision },
+                processId,
+                status: "running",
+                startedAt: this.now(),
+                cancelRequested: false,
+                sequence: 0,
+                events: [],
+                eventBytes: 0,
+            };
+            const emit = (event, payload) => {
+                const item = appendProcessEvent(record, event, payload);
+                try {
+                    owner.send(event, { ...item.payload });
+                }
+                catch {
+                    // The owner can recover a missed event through process.get.
+                }
+            };
             const sendOutput = (stream, chunk) => {
                 const running = this.processes.get(processId);
                 if (running?.child !== child || running.outputTruncated)
@@ -366,7 +512,7 @@ export class PanelAppProcessService {
                 running.outputBytes += Buffer.byteLength(text, "utf8");
                 if (running.outputBytes > MAX_PROCESS_OUTPUT_BYTES) {
                     running.outputTruncated = true;
-                    owner.send("process.output", {
+                    emit("process.output", {
                         processId,
                         stream: "stderr",
                         text: `Process output exceeded ${MAX_PROCESS_OUTPUT_BYTES} bytes; CodeShell stopped it.\n`,
@@ -375,19 +521,22 @@ export class PanelAppProcessService {
                     return;
                 }
                 for (let offset = 0; offset < text.length; offset += MAX_EVENT_CHARS) {
-                    owner.send("process.output", {
+                    emit("process.output", {
                         processId,
                         stream,
                         text: text.slice(offset, offset + MAX_EVENT_CHARS),
                     });
                 }
             };
-            child.stdout?.on("data", (chunk) => sendOutput("stdout", chunk));
-            child.stderr?.on("data", (chunk) => sendOutput("stderr", chunk));
+            child.stdout?.setEncoding("utf8").on("data", (chunk) => sendOutput("stdout", chunk));
+            child.stderr?.setEncoding("utf8").on("data", (chunk) => sendOutput("stderr", chunk));
+            child.stdin?.on("error", () => {
+                /* write/end report pipe errors to their caller */
+            });
             child.once("error", (error) => {
                 if (this.processes.get(processId)?.child !== child)
                     return;
-                owner.send("process.output", {
+                emit("process.output", {
                     processId,
                     stream: "stderr",
                     text: `${error.message}\n`,
@@ -399,19 +548,43 @@ export class PanelAppProcessService {
                     this.terminate(running);
             }, PROCESS_LIFETIME_MS);
             lifetime.unref();
-            this.processes.set(processId, {
+            let finishExit;
+            const running = {
                 guestId: owner.guestId,
                 child,
                 lifetime,
                 outputBytes: 0,
                 outputTruncated: false,
-            });
+                record,
+                stdinBytes: 0,
+                stdinPendingBytes: 0,
+                stdinPendingWrites: 0,
+                stdinEnded: input.stdin !== "pipe",
+                stdinTail: Promise.resolve(),
+                exit: new Promise((resolve) => {
+                    finishExit = resolve;
+                }),
+            };
+            this.processes.set(processId, running);
             child.once("close", (code, signal) => {
-                clearTimeout(lifetime);
-                if (this.processes.get(processId)?.child !== child)
-                    return;
-                this.processes.delete(processId);
-                owner.send("process.exit", { processId, code, signal });
+                void (async () => {
+                    clearTimeout(lifetime);
+                    // Cancellation also waits for the process group, not just its leader.
+                    await running.termination;
+                    finishExit({ code, signal });
+                    this.retiring.delete(processId);
+                    if (this.processes.get(processId)?.child !== child)
+                        return;
+                    this.processes.delete(processId);
+                    record.status = "exited";
+                    record.exitedAt = this.now();
+                    record.code = code;
+                    record.signal = signal;
+                    emit("process.exit", { processId, code, signal });
+                    // Keep the receipt only after the operating system reports the real close.
+                    if (!this.closed && (this.guestEpochs.get(owner.guestId) ?? 0) === epoch)
+                        this.receipts.add(record);
+                })();
             });
             return { processId, executable: executable.name };
         }
@@ -424,15 +597,164 @@ export class PanelAppProcessService {
         }
     }
     cancel(owner, params) {
+        this.epoch(owner);
         const processId = params?.processId;
         if (typeof processId !== "string")
             throw new Error("process.cancel requires processId");
         const running = this.processes.get(processId);
-        if (!running || running.guestId !== owner.guestId)
+        if (!running || !sameProcessOwner(running.record.owner, owner))
             return { cancelled: false };
         this.terminate(running);
         return { cancelled: true };
     }
+    /** Host-only wait captured while the owner is live; never exposes output after revocation. */
+    waitForExit(owner, params) {
+        const running = this.processes.get(params.processId) ?? this.retiring.get(params.processId);
+        if (running && sameProcessOwner(running.record.owner, owner))
+            return running.exit;
+        const receipt = this.receipts.get(params.processId);
+        if (receipt && sameProcessOwner(receipt.owner, owner))
+            return Promise.resolve({ code: receipt.code ?? null, signal: receipt.signal ?? null });
+        return Promise.reject(new Error("process is unavailable or belongs to another Panel App"));
+    }
+    async get(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const input = params;
+        if (typeof input?.processId !== "string" || input.processId.length > 160)
+            throw new Error("process.get requires a processId");
+        const after = input.afterSequence ?? 0;
+        const limit = input.limit ?? 128;
+        if (!Number.isSafeInteger(after) || after < 0)
+            throw new Error("process.get afterSequence must be a nonnegative integer");
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256)
+            throw new Error("process.get limit must be between 1 and 256");
+        const record = this.processes.get(input.processId)?.record ?? this.receipts.get(input.processId);
+        if (!record || !sameProcessOwner(record.owner, owner))
+            return { found: false, processId: input.processId };
+        if (after > record.sequence)
+            throw new Error("process.get cursor is ahead of this process");
+        const events = record.events
+            .filter((event) => event.sequence > after)
+            .slice(0, limit);
+        const nextSequence = events.at(-1)?.sequence ?? after;
+        return {
+            found: true,
+            processId: record.processId,
+            status: record.status,
+            startedAt: record.startedAt,
+            ...(record.exitedAt === undefined ? {} : { exitedAt: record.exitedAt }),
+            ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
+            ...(record.code === undefined ? {} : { code: record.code }),
+            ...(record.signal === undefined ? {} : { signal: record.signal }),
+            cancelRequested: record.cancelRequested,
+            sequence: record.sequence,
+            nextSequence,
+            events: structuredClone(events),
+            truncated: after < (record.events[0]?.sequence ?? 1) - 1,
+            hasMore: nextSequence < record.sequence,
+        };
+    }
+    writableProcess(owner, processId) {
+        if (typeof processId !== "string")
+            throw new Error("process input requires a processId");
+        const running = this.processes.get(processId);
+        if (!running || !sameProcessOwner(running.record.owner, owner))
+            throw new Error("process is unavailable or belongs to another Panel App");
+        if (running.record.status !== "running" ||
+            !running.child.stdin ||
+            running.child.stdin.destroyed)
+            throw new Error("process stdin is unavailable");
+        return running;
+    }
+    async write(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const input = params;
+        if (typeof input?.text !== "string")
+            throw new Error("process.write requires UTF-8 text");
+        const bytes = Buffer.byteLength(input.text);
+        if (bytes > processLimits.maxStdinChunkBytes)
+            throw new Error("process stdin chunk exceeds limit");
+        const running = this.writableProcess(owner, input.processId);
+        if (running.stdinEnded)
+            throw new Error("process stdin has ended");
+        if (running.stdinBytes + bytes > processLimits.maxStdinBytes)
+            throw new Error("process stdin total exceeds limit");
+        if (running.stdinPendingBytes + bytes > processLimits.maxStdinPendingBytes ||
+            running.stdinPendingWrites >= processLimits.maxStdinPendingWrites)
+            throw new Error("process stdin is backpressured; await pending writes");
+        running.stdinBytes += bytes;
+        running.stdinPendingBytes += bytes;
+        running.stdinPendingWrites++;
+        const totalBytes = running.stdinBytes;
+        const operation = running.stdinTail
+            .then(async () => {
+            await this.authorize(owner, epoch);
+            this.writableProcess(owner, input.processId);
+            await this.sendInput(running, input.text);
+        })
+            .finally(() => {
+            running.stdinPendingBytes -= bytes;
+            running.stdinPendingWrites--;
+        });
+        running.stdinTail = operation.catch(() => {
+            running.stdinEnded = true;
+        });
+        await operation;
+        return { bytesWritten: bytes, totalBytes };
+    }
+    async end(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const processId = params?.processId;
+        const running = this.writableProcess(owner, processId);
+        if (running.stdinEnded)
+            throw new Error("process stdin has ended");
+        running.stdinEnded = true;
+        const operation = running.stdinTail.then(async () => {
+            await this.authorize(owner, epoch);
+            this.writableProcess(owner, processId);
+            await this.sendInput(running);
+        });
+        running.stdinTail = operation.catch(() => { });
+        await operation;
+        return { ended: true, totalBytes: running.stdinBytes };
+    }
+    sendInput(running, text) {
+        const stream = running.child.stdin;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                stream.off("error", onError);
+                running.child.off("close", onClose);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const onError = (error) => finish(error);
+            const onClose = () => finish(new Error("process exited before stdin completed"));
+            const timer = setTimeout(() => {
+                this.terminate(running);
+                finish(new Error("process stdin write timed out"));
+            }, processLimits.stdinWriteTimeoutMs);
+            timer.unref();
+            stream.once("error", onError);
+            running.child.once("close", onClose);
+            if (text === undefined)
+                stream.end(() => finish());
+            else
+                stream.write(text, "utf8", finish);
+        });
+    }
     revokeGuest(guestId) {
         this.guestEpochs.set(guestId, (this.guestEpochs.get(guestId) ?? 0) + 1);
         if (this.options.approvalScope === "guest") {
@@ -449,11 +771,17 @@ export class PanelAppProcessService {
             if (grant.guestId === guestId)
                 this.directories.delete(handle);
         }
+        for (const [handle, grant] of this.entries) {
+            if (grant.guestId === guestId)
+                this.entries.delete(handle);
+        }
+        this.receipts.revokeGuest(guestId);
         for (const [processId, running] of this.processes) {
             if (running.guestId !== guestId)
                 continue;
             clearTimeout(running.lifetime);
             this.terminate(running);
+            this.retiring.set(processId, running);
             this.processes.delete(processId);
         }
         for (const [handle, grant] of this.fileArguments) {
@@ -479,16 +807,22 @@ export class PanelAppProcessService {
             ...[...this.executables.values()].map((grant) => grant.guestId),
             ...[...this.directories.values()].map((grant) => grant.guestId),
             ...[...this.fileArguments.values()].map((grant) => grant.guestId),
+            ...[...this.entries.values()].map((grant) => grant.guestId),
             ...[...this.processes.values()].map((running) => running.guestId),
         ]);
         for (const guestId of guests)
             this.revokeGuest(guestId);
         this.approvedExecutables.clear();
+        this.receipts.close();
     }
     terminate(running) {
+        if (running.termination)
+            return;
+        running.record.cancelRequested = true;
+        running.record.status = "stopping";
         const pid = running.child.pid;
         if (typeof pid === "number" && pid > 1) {
-            void killProcessGroup(pid);
+            running.termination = killProcessGroup(pid).catch(() => { });
             return;
         }
         try {

package/dist/panels/process-state.d.ts

@@ -0,0 +1,58 @@
+import type { PanelProcessOwner } from "./process-service.js";
+export declare const processLimits: Readonly<{
+    maxArguments: 256;
+    maxArgumentLength: 8192;
+    maxArgumentBytes: number;
+    maxConcurrentProcesses: 3;
+    maxFileArguments: 8;
+    maxEventChars: 16384;
+    maxOutputBytes: number;
+    maxLifetimeMs: number;
+    receiptTtlMs: number;
+    maxRetainedProcesses: 128;
+    maxRetainedProcessesPerGuest: 32;
+    maxEventsPerProcess: 256;
+    maxRetainedOutputBytes: number;
+    maxStdinChunkBytes: number;
+    maxStdinBytes: number;
+    maxStdinPendingBytes: number;
+    maxStdinPendingWrites: 4;
+    stdinWriteTimeoutMs: 10000;
+    maxEntryBytes: number;
+    maxEntryHandlesPerGuest: 64;
+}>;
+export type ProcessEvent = "process.output" | "process.exit";
+export interface PanelProcessEvent {
+    event: ProcessEvent;
+    sequence: number;
+    payload: Record<string, unknown>;
+}
+export interface ProcessRecord {
+    owner: Pick<PanelProcessOwner, "guestId" | "appId" | "revision">;
+    processId: string;
+    status: "running" | "stopping" | "exited";
+    startedAt: number;
+    exitedAt?: number;
+    expiresAt?: number;
+    code?: number | null;
+    signal?: string | null;
+    cancelRequested: boolean;
+    sequence: number;
+    events: PanelProcessEvent[];
+    eventBytes: number;
+}
+export declare function sameProcessOwner(a: Pick<PanelProcessOwner, "guestId" | "appId" | "revision">, b: Pick<PanelProcessOwner, "guestId" | "appId" | "revision">): boolean;
+/** Only terminal receipts are retained here; live process admission has its own limit. */
+export declare class ProcessReceipts {
+    private readonly now;
+    private readonly records;
+    private timer?;
+    constructor(now?: () => number);
+    get(id: string): ProcessRecord | undefined;
+    add(record: ProcessRecord): void;
+    revokeGuest(guestId: number): void;
+    close(): void;
+    private prune;
+    private arm;
+}
+export declare function appendProcessEvent(record: ProcessRecord, event: ProcessEvent, payload: Record<string, unknown>): PanelProcessEvent;