pi-session-mcp 0.8.3 → 0.12.0

package/.pi-session-mcp-cli/setup-platform.js

@@ -1,6 +1,12 @@
 import { execFile } from "node:child_process";
 import { constants, readdirSync, readFileSync, statSync } from "node:fs";
 import { open, statfs } from "node:fs/promises";
+const realProcfs = {
+    // Names only: `withFileTypes` makes Node lstat entries whose type procfs does
+    // not report, and that lstat throws ENOENT for a process that exits meanwhile.
+    list: () => readdirSync("/proc"),
+    readStat: (pid) => readFileSync(`/proc/${pid}/stat`, "utf8"),
+};
 export function currentSetupPlatform(platform = process.platform) {
     return platform === "linux" || platform === "darwin" ? platform : undefined;
 }
@@ -14,57 +20,78 @@ export function isTrustedSystemBinary(path, statFile = statSync) {
         return false;
     }
 }
-function readLinuxProcessGroup(pid) {
-    const line = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
+const VANISHED = Symbol("vanished");
+/** One stat sample, or VANISHED when the entry is gone (ENOENT) or was reaped between open and read (ESRCH). */
+function sampleLinuxProcess(procfs, pid) {
+    let line;
+    try {
+        line = procfs.readStat(pid).trim();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ESRCH")
+            return VANISHED;
+        throw error;
+    }
     const close = line.lastIndexOf(") ");
     const state = line[close + 2];
     if (close < 3 || !state || !/^[A-Za-z]$/.test(state) || line[close + 3] !== " ")
         throw new Error("process_stat_invalid");
     const fields = line.slice(close + 4).trim().split(/\s+/);
-    const group = Number(fields[1]);
-    if (!Number.isSafeInteger(group) || group < 0)
+    // fields starts at ppid (field 4); num_threads is field 20 in proc(5).
+    return { group: fields[1] ?? "", state, threads: fields[16] };
+}
+/**
+ * Undefined for a process that is already gone (#109). Besides ENOENT and ESRCH,
+ * `do_task_stat` reports process group -1 once the kernel has released the
+ * process's signal state while reaping it; that sample is read once more, and
+ * only a vanished entry on the second read counts as gone. Any other failure
+ * throws and makes the scan indeterminate.
+ */
+function readLinuxProcessGroup(procfs, pid) {
+    let sample = sampleLinuxProcess(procfs, pid);
+    if (sample !== VANISHED && sample.group === "-1") {
+        sample = sampleLinuxProcess(procfs, pid);
+        if (sample !== VANISHED && sample.group === "-1")
+            throw new Error("process_group_invalid");
+    }
+    if (sample === VANISHED)
+        return undefined;
+    const group = Number(sample.group);
+    if (sample.group === "" || !Number.isSafeInteger(group) || group < 0)
         throw new Error("process_group_invalid");
-    return { group, state };
+    return { group, state: sample.state, threads: sample.threads };
+}
+// Numeric /proc entries are process directories; a vanished one is skipped by readLinuxProcessGroup.
+function linuxProcessIds(procfs) {
+    return procfs.list().filter((name) => /^\d+$/.test(name)).map(Number);
 }
-function linuxGroupState(group) {
-    let entries;
+function linuxGroupState(procfs, group) {
     try {
-        entries = readdirSync("/proc", { withFileTypes: true });
+        for (const pid of linuxProcessIds(procfs)) {
+            const sample = readLinuxProcessGroup(procfs, pid);
+            if (!sample || sample.group !== group)
+                continue;
+            if (sample.state !== "Z")
+                return "alive";
+            const threads = /^\d+$/.test(sample.threads ?? "") ? Number(sample.threads) : Number.NaN;
+            if (!Number.isSafeInteger(threads) || threads < 1)
+                throw new Error("process_threads_invalid");
+            if (threads > 1)
+                return "alive";
+        }
     }
     catch {
         return "unknown";
     }
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
-            continue;
-        try {
-            const sample = readLinuxProcessGroup(Number(entry.name));
-            if (sample.group === group && sample.state !== "Z")
-                return "alive";
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                return "unknown";
-        }
-    }
     return "gone";
 }
-function linuxTableReadable(selfPid) {
+function linuxTableReadable(procfs, selfPid) {
     let sawSelf = false;
     try {
-        for (const entry of readdirSync("/proc", { withFileTypes: true })) {
-            if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
-                continue;
-            try {
-                const pid = Number(entry.name);
-                readLinuxProcessGroup(pid);
-                if (pid === selfPid)
-                    sawSelf = true;
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    return false;
-            }
+        for (const pid of linuxProcessIds(procfs)) {
+            if (readLinuxProcessGroup(procfs, pid) && pid === selfPid)
+                sawSelf = true;
         }
     }
     catch {
@@ -112,7 +139,8 @@ function runDarwinPs() {
 export function createProcessTable(platform, dependencies = {}) {
     const selfPid = dependencies.selfPid ?? process.pid;
     if (platform === "linux") {
-        return { pollMs: 10, groupState: async (group) => linuxGroupState(group), readable: async () => linuxTableReadable(selfPid) };
+        const procfs = dependencies.procfs ?? realProcfs;
+        return { pollMs: 10, groupState: async (group) => linuxGroupState(procfs, group), readable: async () => linuxTableReadable(procfs, selfPid) };
     }
     const runPs = dependencies.runPs ?? runDarwinPs;
     const scan = async () => {

package/.pi-session-mcp-cli/setup-process.js

@@ -0,0 +1,455 @@
+import { spawn } from "node:child_process";
+import { lstatSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const DEFAULT_TIMEOUT = 10_000;
+const DEFAULT_MAX = 65_536;
+const ABORT_GROUP_CLEANUP_TIMEOUT = 2_000;
+const GUARDIAN_START_TIMEOUT = 5_000;
+/**
+ * How long the verified server may take to exit after stdin EOF and SIGTERM before it is killed. A
+ * server that shuts down its registry and closes its event spool removes its spool instance
+ * directory on the way out; SIGKILL earlier leaves a stale `inst-*` directory behind (#125). A
+ * server that exits sooner is not waited for. Both MCP launchers use it. After the grace, `kill()`
+ * waits up to 1 s for the child to close and polls its process group for about 1 s; on macOS one
+ * `/bin/ps` call of that poll may take up to 2 s. A `kill()` that outlasts `MCP_KILL_BUDGET_MS` makes
+ * the verification fail closed.
+ */
+export const MCP_SERVER_SHUTDOWN_GRACE_MS = 2_000;
+let platformModule;
+/**
+ * Source-mode harnesses import this file through Node type stripping, which
+ * cannot map a static `./setup-platform.js` import to its `.ts` source.
+ */
+function loadSetupPlatform() {
+    platformModule ??= import(import.meta.url.endsWith(".ts") ? "./setup-platform.ts" : "./setup-platform.js");
+    return platformModule;
+}
+async function currentProcessTable() {
+    const platform = await loadSetupPlatform();
+    const name = platform.currentSetupPlatform();
+    return name ? platform.createProcessTable(name) : undefined;
+}
+/** Kill a detached process and every descendant in its process group. */
+function terminateProcessGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch { /* already exited or no group */ }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch { /* already exited */ }
+}
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+/** Runs only an explicit executable/argv pair, with bounded output and termination. */
+export function createProcessRunner(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX;
+    return { async run(command, args, signal, runOptions) {
+            const effectiveSignal = options.signal && signal ? AbortSignal.any([options.signal, signal]) : options.signal ?? signal;
+            const table = await currentProcessTable();
+            if (!table)
+                return { exitCode: 126, stdout: "", stderr: "" };
+            return new Promise((resolve) => {
+                const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe", ...(runOptions?.inheritFds ?? [])], env: runOptions?.env ? { ...(options.env ?? process.env), ...runOptions.env } : options.env, cwd: runOptions?.cwd, detached: process.platform !== "win32" });
+                let stdout = "";
+                let stderr = "";
+                let overflow = false;
+                let aborted = false;
+                const collect = (part) => (chunk) => { const value = chunk.toString("utf8"); const current = part === "stdout" ? stdout : stderr; if (Buffer.byteLength(current + value, "utf8") > maxOutputBytes) {
+                    overflow = true;
+                    return;
+                } if (part === "stdout")
+                    stdout += value;
+                else
+                    stderr += value; };
+                child.stdout.on("data", collect("stdout"));
+                child.stderr.on("data", collect("stderr"));
+                let done = false;
+                let timedOut = false;
+                let killTimer;
+                let hardTimer;
+                let groupPoll;
+                let groupDeadline = 0;
+                const finish = (exitCode) => { if (done)
+                    return; done = true; effectiveSignal?.removeEventListener("abort", abort); clearTimeout(timer); if (!timedOut && killTimer)
+                    clearTimeout(killTimer); if (!timedOut && hardTimer)
+                    clearTimeout(hardTimer); if (groupPoll)
+                    clearTimeout(groupPoll); resolve({ exitCode, stdout: overflow ? Buffer.from(stdout).subarray(0, maxOutputBytes).toString("utf8") : stdout, stderr: overflow ? "output_limit" : stderr }); };
+                let groupCheck = false;
+                const finishAfterGroup = (successCode) => {
+                    if (done || groupCheck)
+                        return;
+                    groupCheck = true;
+                    const group = child.pid;
+                    void (group === undefined ? Promise.resolve("unknown") : table.groupState(group)).then((state) => {
+                        groupCheck = false;
+                        if (done)
+                            return;
+                        if (state === "gone") {
+                            finish(successCode);
+                            return;
+                        }
+                        if (Date.now() >= groupDeadline) {
+                            finish(126);
+                            return;
+                        }
+                        groupPoll = setTimeout(() => finishAfterGroup(successCode), table.pollMs);
+                    });
+                };
+                const abort = () => { if (done)
+                    return; aborted = true; groupDeadline = Date.now() + ABORT_GROUP_CLEANUP_TIMEOUT; terminateProcessGroup(child, "SIGTERM"); killTimer = setTimeout(() => { terminateProcessGroup(child, "SIGKILL"); finishAfterGroup(125); }, 100); };
+                effectiveSignal?.addEventListener("abort", abort, { once: true });
+                if (effectiveSignal?.aborted)
+                    abort();
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    groupDeadline = Date.now() + ABORT_GROUP_CLEANUP_TIMEOUT;
+                    terminateProcessGroup(child, "SIGTERM");
+                    killTimer = setTimeout(() => {
+                        terminateProcessGroup(child, "SIGKILL");
+                        hardTimer = setTimeout(() => finishAfterGroup(124), 100);
+                    }, 100);
+                }, timeoutMs);
+                child.on("error", () => { if (!timedOut) {
+                    if (aborted)
+                        finishAfterGroup(125);
+                    else
+                        finish(127);
+                } });
+                child.on("close", (code) => { if (!timedOut) {
+                    if (aborted)
+                        finishAfterGroup(125);
+                    else
+                        finish(code ?? 1);
+                } });
+            });
+        } };
+}
+/** Generalized bounded stdio transport for a generated writer wrapper. */
+export function createCommandMcpStdioLauncher(command, env, options) {
+    return async (signal) => {
+        const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe", ...(options?.inheritFds ?? [])], env, detached: process.platform !== "win32" });
+        let buffer = "", closed = false, overflow = false;
+        child.stdout.on("data", (chunk) => { if (!overflow) {
+            buffer += chunk.toString("utf8");
+            if (Buffer.byteLength(buffer) > DEFAULT_MAX) {
+                overflow = true;
+                buffer = "";
+            }
+        } });
+        child.stderr.resume();
+        child.on("error", () => { closed = true; });
+        child.on("close", () => { closed = true; });
+        const abort = () => terminateProcessGroup(child, "SIGTERM");
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+        return {
+            write(frame) {
+                if (closed || overflow || Buffer.byteLength(frame) > DEFAULT_MAX)
+                    throw new Error("mcp_write_unavailable");
+                return new Promise((resolve, reject) => child.stdin.write(frame, (error) => error ? reject(new Error("mcp_write_failed")) : resolve()));
+            },
+            async read() {
+                const deadline = Date.now() + DEFAULT_TIMEOUT;
+                while (!closed && !overflow && !buffer.includes("\n") && Date.now() < deadline)
+                    await delay(5);
+                if (overflow)
+                    return null;
+                const end = buffer.indexOf("\n");
+                if (end >= 0) {
+                    const frame = buffer.slice(0, end + 1);
+                    buffer = buffer.slice(end + 1);
+                    return frame;
+                }
+                return null;
+            },
+            async kill() {
+                signal.removeEventListener("abort", abort);
+                child.stdin.end();
+                terminateProcessGroup(child, "SIGTERM");
+                // Same shutdown grace as the host server (#125): the writer's server closes its spool on the way out.
+                const graceDeadline = Date.now() + MCP_SERVER_SHUTDOWN_GRACE_MS;
+                while (!closed && Date.now() < graceDeadline)
+                    await delay(10);
+                terminateProcessGroup(child, "SIGKILL");
+                const table = await currentProcessTable(), deadline = Date.now() + 1_000;
+                while (table && child.pid !== undefined && Date.now() < deadline) {
+                    if (await table.groupState(child.pid) === "gone")
+                        return;
+                    await delay(table.pollMs);
+                }
+                throw new Error("mcp_process_cleanup_failed");
+            },
+        };
+    };
+}
+/**
+ * Starts the local MCP server with only the controlled configuration environment, plus the runtime
+ * directory when this process has one: a server with event delivery enabled resolves its spool
+ * there, as it does under Claude Code (#113). The runtime directory is a path, not a secret.
+ */
+export function createMcpStdioLauncher(options) {
+    return async (signal) => {
+        const table = await currentProcessTable();
+        const runtime = options.runtimeDir === undefined ? process.env.XDG_RUNTIME_DIR : options.runtimeDir;
+        const env = { PI_SESSION_MCP_CONFIG: options.configPath, ...(runtime === undefined || runtime === "" ? {} : { XDG_RUNTIME_DIR: runtime }) };
+        const child = spawn(options.nodePath, [options.entryPath], { stdio: ["pipe", "pipe", "pipe"], env, detached: process.platform !== "win32" });
+        const max = options.maxFrameBytes ?? DEFAULT_MAX;
+        let buffer = "";
+        let closed = false;
+        let overflow = false;
+        child.stdout.on("data", (chunk) => { if (overflow)
+            return; buffer += chunk.toString("utf8"); if (Buffer.byteLength(buffer, "utf8") > max) {
+            overflow = true;
+            buffer = "";
+        } });
+        child.stderr.on("data", () => { });
+        child.on("error", () => { closed = true; });
+        child.on("close", () => { closed = true; });
+        const abort = () => { if (!closed)
+            terminateProcessGroup(child, "SIGTERM"); };
+        signal.addEventListener("abort", abort, { once: true });
+        const waitForClose = async (milliseconds) => {
+            if (closed)
+                return true;
+            return new Promise((resolve) => {
+                const onClose = () => { clearTimeout(timer); resolve(true); };
+                const timer = setTimeout(() => { child.off("close", onClose); resolve(closed); }, milliseconds);
+                child.once("close", onClose);
+            });
+        };
+        return {
+            write(frame) {
+                if (closed || overflow || Buffer.byteLength(frame, "utf8") > max)
+                    return Promise.reject(new Error("mcp_write_unavailable"));
+                return new Promise((resolve, reject) => child.stdin.write(frame, (error) => error ? reject(new Error("mcp_write_failed")) : resolve()));
+            },
+            async read() {
+                const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT);
+                while (!overflow && !closed && buffer.indexOf("\n") < 0 && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 5));
+                if (overflow)
+                    return null;
+                const newline = buffer.indexOf("\n");
+                if (newline >= 0) {
+                    const line = buffer.slice(0, newline + 1);
+                    buffer = buffer.slice(newline + 1);
+                    return line;
+                }
+                if (closed && buffer.length > 0) {
+                    const tail = buffer;
+                    buffer = "";
+                    return tail;
+                }
+                return null;
+            },
+            async kill() {
+                signal.removeEventListener("abort", abort);
+                if (!closed)
+                    child.stdin.end();
+                terminateProcessGroup(child, "SIGTERM");
+                // Let the server finish its own shutdown (#125); SIGKILL only what is still running after the grace.
+                await waitForClose(options.shutdownGraceMs ?? MCP_SERVER_SHUTDOWN_GRACE_MS);
+                terminateProcessGroup(child, "SIGKILL");
+                const childClosed = await waitForClose(1_000);
+                const group = child.pid;
+                const groupState = async () => table && group !== undefined ? table.groupState(group) : "unknown";
+                const groupDeadline = Date.now() + 1_000;
+                let state = await groupState();
+                while (state !== "gone" && Date.now() < groupDeadline) {
+                    await delay(table?.pollMs ?? 10);
+                    state = await groupState();
+                }
+                if (!childClosed || state !== "gone")
+                    throw new Error("mcp_process_cleanup_failed");
+            },
+        };
+    };
+}
+/**
+ * Starts the transaction guardian with the kernel fence held. On Linux the
+ * trusted util-linux `flock` locks the caller's open file description first;
+ * on macOS the caller passes a descriptor from `openLockedDarwin`, which is
+ * locked at open time. The guardian inherits the locked file description, so
+ * parent death cannot release the fence while a client mutation or
+ * descendant is still live.
+ */
+export async function acquireSetupGuardian(lockFd, timeoutMs, signal, validateFence) {
+    const platform = await loadSetupPlatform();
+    const platformName = platform.currentSetupPlatform();
+    if (!platformName)
+        throw new Error("platform_unsupported");
+    const flockPath = platformName === "linux" ? ["/usr/bin/flock", "/bin/flock"].find((candidate) => platform.isTrustedSystemBinary(candidate)) : undefined;
+    if (platformName === "linux" && !flockPath)
+        throw new Error("ownership_lock_unavailable");
+    const modulePath = fileURLToPath(import.meta.url);
+    const guardianPath = fileURLToPath(new URL(modulePath.endsWith(".ts") ? "./setup-command-guardian.ts" : "./setup-command-guardian.js", import.meta.url));
+    try {
+        if (!lstatSync(guardianPath).isFile())
+            throw new Error("guardian_invalid");
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    if (flockPath) {
+        const waitSeconds = String(Math.ceil(Math.max(1_000, Math.min(timeoutMs, 120_000)) / 1_000));
+        let locker;
+        try {
+            locker = spawn(flockPath, ["-E", "75", "-w", waitSeconds, "3"], {
+                stdio: ["ignore", "ignore", "ignore", lockFd],
+                detached: true,
+            });
+        }
+        catch {
+            throw new Error("ownership_lock_unavailable");
+        }
+        const stopAcquisition = () => { if (locker.pid !== undefined) {
+            try {
+                process.kill(-locker.pid, "SIGKILL");
+            }
+            catch { /* already gone */ }
+        } };
+        if (signal?.aborted)
+            stopAcquisition();
+        signal?.addEventListener("abort", stopAcquisition, { once: true });
+        try {
+            await new Promise((resolve, reject) => {
+                locker.once("error", () => reject(new Error("ownership_lock_unavailable")));
+                locker.once("close", (code) => code === 0 ? resolve() : reject(new Error(code === 75 ? "ownership_lock_busy" : signal?.aborted ? "operation_aborted" : "ownership_lock_unavailable")));
+            });
+        }
+        finally {
+            signal?.removeEventListener("abort", stopAcquisition);
+        }
+    }
+    if (signal?.aborted)
+        throw new Error("operation_aborted");
+    try {
+        await validateFence?.();
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, [guardianPath, String(process.pid)], { stdio: ["ignore", "ignore", "ignore", lockFd, "ipc"], detached: true });
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    const stopGuardianStart = () => { if (child.pid !== undefined) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch { /* already gone */ }
+    } };
+    signal?.addEventListener("abort", stopGuardianStart, { once: true });
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => { stopGuardianStart(); settle(new Error("ownership_lock_unavailable")); }, GUARDIAN_START_TIMEOUT);
+            const settle = (error) => { if (settled)
+                return; settled = true; clearTimeout(timer); if (error)
+                reject(error);
+            else
+                resolve(); };
+            child.once("error", () => settle(new Error("ownership_lock_unavailable")));
+            child.once("close", () => settle(new Error(signal?.aborted ? "operation_aborted" : "ownership_lock_unavailable")));
+            child.on("message", (message) => { if (message && typeof message === "object" && message.type === "ready")
+                settle(); });
+        });
+    }
+    finally {
+        signal?.removeEventListener("abort", stopGuardianStart);
+    }
+    const compromised = new AbortController();
+    let nextId = 1;
+    let pending;
+    let released = false;
+    let unsafe = false;
+    const safeResult = (message) => {
+        if (!message || typeof message !== "object")
+            return undefined;
+        const value = message;
+        if (value.type !== "result" || !Number.isSafeInteger(value.id) || !Number.isSafeInteger(value.exitCode) || typeof value.stdout !== "string" || typeof value.stderr !== "string")
+            return undefined;
+        if (value.stdout.length > DEFAULT_MAX || value.stderr.length > DEFAULT_MAX)
+            return undefined;
+        return { exitCode: value.exitCode, stdout: value.stdout, stderr: value.stderr };
+    };
+    const failPending = () => {
+        if (!pending)
+            return;
+        pending.signal?.removeEventListener("abort", pending.abort);
+        const resolve = pending.resolve;
+        pending = undefined;
+        unsafe = true;
+        compromised.abort();
+        resolve({ exitCode: 126, stdout: "", stderr: "" });
+    };
+    child.on("message", (message) => {
+        const result = safeResult(message);
+        if (!result || !pending || message.id !== pending.id)
+            return;
+        pending.signal?.removeEventListener("abort", pending.abort);
+        const resolve = pending.resolve;
+        pending = undefined;
+        if (result.exitCode === 126) {
+            unsafe = true;
+            compromised.abort();
+        }
+        resolve(result);
+    });
+    child.once("error", failPending);
+    child.once("close", () => { if (!released) {
+        unsafe = true;
+        compromised.abort();
+        failPending();
+    } });
+    const runner = {
+        run(command, args, runSignal, runOptions) {
+            // The guardian child cannot pass descriptors through; refuse instead of dropping a caller's lease.
+            if (runOptions?.env !== undefined || runOptions?.inheritFds !== undefined || released || unsafe || pending || runSignal?.aborted || !child.connected)
+                return Promise.resolve({ exitCode: 126, stdout: "", stderr: "" });
+            const id = nextId++;
+            return new Promise((resolve) => {
+                const abort = () => { if (child.connected)
+                    child.send({ type: "abort", id }, undefined, undefined, () => undefined); };
+                pending = { id, resolve, ...(runSignal ? { signal: runSignal } : {}), abort };
+                runSignal?.addEventListener("abort", abort, { once: true });
+                child.send({ type: "run", id, command, args: [...args], timeoutMs: DEFAULT_TIMEOUT, maxOutputBytes: DEFAULT_MAX, ...(runOptions?.cwd !== undefined ? { cwd: runOptions.cwd } : {}) }, undefined, undefined, (error) => { if (error)
+                    failPending(); });
+            });
+        },
+    };
+    return {
+        runner,
+        signal: compromised.signal,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (pending)
+                pending.abort();
+            if (!unsafe && child.connected) {
+                child.send({ type: "shutdown" }, undefined, undefined, () => undefined);
+                const closed = await new Promise((resolve) => {
+                    const timer = setTimeout(() => resolve(false), 5_000);
+                    child.once("close", () => { clearTimeout(timer); resolve(true); });
+                });
+                if (closed)
+                    return;
+            }
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+        },
+    };
+}

package/.pi-session-mcp-cli/skill-library.js

@@ -41,10 +41,14 @@ export function resolveLibrarySkill(name, roots) {
     const override = join(roots.overrideDirectory, name);
     if (isRegularFile(join(override, "SKILL.md")))
         return Object.freeze({ name, source: "override", directory: override });
-    const shipped = join(shippedSkillsDirectory(roots.packageRoot), name);
-    if (isRegularFile(join(shipped, "SKILL.md")))
-        return Object.freeze({ name, source: "shipped", directory: shipped });
-    return undefined;
+    return shippedLibrarySkill(name, roots.packageRoot);
+}
+/** The shipped skill of that name, whatever overrides exist; undefined when the package ships none. */
+export function shippedLibrarySkill(name, packageRoot) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return undefined;
+    const shipped = join(shippedSkillsDirectory(packageRoot), name);
+    return isRegularFile(join(shipped, "SKILL.md")) ? Object.freeze({ name, source: "shipped", directory: shipped }) : undefined;
 }
 /** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
 export function builtinSkillPath(name, roots) {