pi-session-mcp 0.6.3 → 0.7.0

package/dist/setup-command-guardian.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { readdirSync, readFileSync } from "node:fs";
+// Source-mode tests run this guardian through Node type stripping, which cannot
+// map a static `./setup-platform.js` import to its `.ts` source.
+const platform = await import(import.meta.url.endsWith(".ts") ? "./setup-platform.ts" : "./setup-platform.js");
+const platformName = platform.currentSetupPlatform();
+const table = platformName ? platform.createProcessTable(platformName) : undefined;
 const TERM_GRACE_MS = 100;
 const CLEANUP_REPORT_MS = 2_000;
 const RETRY_MS = 25;
+// Each macOS scan starts `ps`, so cleanup loops poll no faster than the table allows.
+const CLEANUP_RETRY_MS = Math.max(RETRY_MS, table?.pollMs ?? RETRY_MS);
 let active;
 let shuttingDown = false;
 // Source-mode signal injection is available only to credential-free tests. The
@@ -54,65 +60,10 @@ function parseRequest(value) {
         return undefined;
     return { type: "run", id: input.id, command: input.command, args: input.args, timeoutMs: input.timeoutMs, maxOutputBytes: input.maxOutputBytes };
 }
-function readProcessGroup(pid) {
-    const line = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
-    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)
-        throw new Error("process_group_invalid");
-    return { group, state };
-}
-function processTableReadable() {
-    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);
-                readProcessGroup(pid);
-                if (pid === process.pid)
-                    sawSelf = true;
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    return false;
-            }
-        }
-    }
-    catch {
-        return false;
-    }
-    return sawSelf;
-}
-function groupState(group) {
-    if (forceUnknownForSourceTest)
-        return "unknown";
-    let entries;
-    try {
-        entries = readdirSync("/proc", { withFileTypes: true });
-    }
-    catch {
+async function groupState(group) {
+    if (forceUnknownForSourceTest || !table)
         return "unknown";
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
-            continue;
-        try {
-            const processState = readProcessGroup(Number(entry.name));
-            if (processState.group === group && processState.state !== "Z")
-                return "alive";
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                return "unknown";
-        }
-    }
-    return "gone";
+    return table.groupState(group);
 }
 function signalGroup(group, signal) {
     try {
@@ -176,7 +127,7 @@ function start(request) {
         signalGroup(execution.group, "SIGKILL");
         const reportDeadline = Date.now() + CLEANUP_REPORT_MS;
         while (true) {
-            const state = groupState(execution.group);
+            const state = await groupState(execution.group);
             if (state === "gone") {
                 finish(reportedCode);
                 active = undefined;
@@ -187,7 +138,7 @@ function start(request) {
             if (!execution.resultSent && Date.now() >= reportDeadline)
                 finish(126);
             signalGroup(execution.group, "SIGKILL");
-            await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+            await new Promise((resolve) => setTimeout(resolve, CLEANUP_RETRY_MS));
         }
     };
     execution.timeout = setTimeout(() => { void cleanup(124); }, request.timeoutMs);
@@ -202,15 +153,20 @@ function start(request) {
     child.once("close", (code) => {
         if (execution.cleanupStarted)
             return;
-        const state = groupState(execution.group);
-        if (state === "gone") {
-            finish(code ?? 1);
-            active = undefined;
-            if (shuttingDown || !process.connected)
-                exitWhenSafe();
-        }
-        else
-            void cleanup(code ?? 1);
+        if (execution.timeout)
+            clearTimeout(execution.timeout);
+        void groupState(execution.group).then((state) => {
+            if (execution.cleanupStarted)
+                return;
+            if (state === "gone") {
+                finish(code ?? 1);
+                active = undefined;
+                if (shuttingDown || !process.connected)
+                    exitWhenSafe();
+            }
+            else
+                void cleanup(code ?? 1);
+        });
     });
 }
 process.on("message", (value) => {
@@ -253,7 +209,7 @@ async function terminateActive() {
     signalGroup(execution.group, "SIGKILL");
     const reportDeadline = Date.now() + CLEANUP_REPORT_MS;
     while (true) {
-        const state = groupState(execution.group);
+        const state = await groupState(execution.group);
         if (state === "gone") {
             if (!execution.resultSent) {
                 execution.resultSent = true;
@@ -269,7 +225,7 @@ async function terminateActive() {
             send({ type: "result", id: execution.id, exitCode: 126, stdout: "", stderr: "" });
         }
         signalGroup(execution.group, "SIGKILL");
-        await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+        await new Promise((resolve) => setTimeout(resolve, CLEANUP_RETRY_MS));
     }
 }
 process.on("disconnect", () => {
@@ -287,7 +243,7 @@ process.once("SIGTERM", () => { shuttingDown = true; if (active)
     void terminateActive();
 else
     exitWhenSafe(); });
-if (processTableReadable())
+if (table && await table.readable())
     send({ type: "ready" });
 else {
     clearInterval(parentWatch);

package/dist/setup-main.js

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isEntryPoint } from "./entry-point.js";
 import { createProcessRunner } from "./setup-process.js";
+import { currentSetupPlatform } from "./setup-platform.js";
 import { createProductionSetup, isSupportedTarget } from "./setup.js";
 import { formatSetupHuman, formatSetupResult, parseSetupArgs } from "./setup-cli.js";
 import { result } from "./setup-result.js";
@@ -17,7 +18,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
         return write(cliFailure("dry-run", [], "usage_invalid", 64), json);
     }
     const operation = request.operation ?? "dry-run";
-    if (process.platform !== "linux")
+    if (!currentSetupPlatform())
         return write(cliFailure(operation, request.targets, "platform_unsupported", 1), request.json);
     const config = process.env.PI_SESSION_MCP_CONFIG;
     if (!config)

package/dist/setup-ownership.js

@@ -1,8 +1,9 @@
 import { constants } from "node:fs";
-import { chmod, lstat, mkdir, open, readFile, rename, rm, stat, statfs } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { acquireSetupGuardian } from "./setup-process.js";
+import { assertSupportedFilesystem, currentSetupPlatform, openLockedDarwin } from "./setup-platform.js";
 /** Safe default for one process; callers needing recovery inject a durable store. */
 export class MemoryOwnershipStore {
     entries = new Map();
@@ -48,10 +49,11 @@ export class DurableOwnershipStore {
         return this.withLock(operation);
     }
     async withLock(operation) {
-        if (process.platform !== "linux")
+        const platform = currentSetupPlatform();
+        if (!platform)
             throw new Error("platform_unsupported");
         const directory = dirname(this.path);
-        await ensureOwnershipDirectory(directory);
+        await ensureOwnershipDirectory(directory, platform);
         const controller = new AbortController();
         const abort = () => controller.abort();
         this.options.signal?.addEventListener("abort", abort, { once: true });
@@ -62,9 +64,14 @@ export class DurableOwnershipStore {
                 throw new Error("operation_aborted");
         };
         const lockPath = `${this.path}.flock`;
+        const acquireTimeoutMs = this.options.acquireTimeoutMs ?? 30_000;
         let lockHandle;
         try {
-            lockHandle = await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+            // macOS takes the kernel lock at open time; on Linux the trusted flock
+            // locks this same open file description in acquireSetupGuardian.
+            lockHandle = platform === "darwin"
+                ? await openLockedDarwin(lockPath, { timeoutMs: acquireTimeoutMs, signal: controller.signal })
+                : await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
             await lockHandle.chmod(0o600);
             await lockHandle.sync();
             await syncDirectory(directory);
@@ -73,10 +80,11 @@ export class DurableOwnershipStore {
                 throw new Error("ownership_lock_invalid");
             await this.options.afterLockOpen?.();
         }
-        catch {
+        catch (error) {
             this.options.signal?.removeEventListener("abort", abort);
             await lockHandle?.close().catch(() => undefined);
-            throw new Error("ownership_lock_unavailable");
+            const code = error.message;
+            throw new Error(["ownership_lock_busy", "operation_aborted"].includes(code) ? code : "ownership_lock_unavailable");
         }
         const validateLock = async () => {
             const [descriptor, linked] = await Promise.all([lockHandle.stat(), stat(lockPath)]);
@@ -85,7 +93,7 @@ export class DurableOwnershipStore {
         };
         let guardian;
         try {
-            guardian = await acquireSetupGuardian(lockHandle.fd, this.options.acquireTimeoutMs ?? 30_000, controller.signal, validateLock);
+            guardian = await acquireSetupGuardian(lockHandle.fd, acquireTimeoutMs, controller.signal, validateLock);
         }
         catch (error) {
             this.options.signal?.removeEventListener("abort", abort);
@@ -153,20 +161,7 @@ export class DurableOwnershipStore {
             await rm(temporary, { force: true }).catch(() => undefined);
     } }
 }
-// Kernel flock and directory fsync semantics are accepted only on the local
-// Linux filesystems covered by the setup test matrix.
-const SUPPORTED_LOCAL_FILESYSTEMS = new Set([
-    0xef53, // ext2/3/4
-    0x58465342, // XFS
-    0x9123683e, // Btrfs
-    0x01021994, // tmpfs
-    0x794c7630, // overlayfs
-    0x2fc12fc1, // ZFS
-    0xf2f52010, // F2FS
-    0x24051905, // UBIFS
-    0xca451a4e, // bcachefs
-]);
-async function ensureOwnershipDirectory(directory) {
+async function ensureOwnershipDirectory(directory, platform) {
     const missing = [];
     let cursor = directory;
     while (true) {
@@ -186,7 +181,7 @@ async function ensureOwnershipDirectory(directory) {
             cursor = parent;
         }
     }
-    await assertSupportedFilesystem(cursor);
+    await assertSupportedFilesystem(cursor, platform);
     for (const candidate of missing.reverse()) {
         try {
             await mkdir(candidate, { mode: 0o700 });
@@ -203,12 +198,7 @@ async function ensureOwnershipDirectory(directory) {
         await syncDirectory(dirname(candidate));
     }
     await chmod(directory, 0o700);
-    await assertSupportedFilesystem(directory);
-}
-async function assertSupportedFilesystem(path) {
-    const filesystem = await statfs(path);
-    if (!SUPPORTED_LOCAL_FILESYSTEMS.has(filesystem.type))
-        throw new Error("ownership_filesystem_unsupported");
+    await assertSupportedFilesystem(directory, platform);
 }
 async function syncDirectory(path) {
     const handle = await open(path, "r");

package/dist/setup-platform.d.ts

@@ -0,0 +1,57 @@
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+/**
+ * Operating-system facts behind the setup fence. This module has no relative
+ * imports: the transaction guardian and source-mode harnesses load it through
+ * Node type stripping, which cannot map a `.js` specifier to its `.ts` source.
+ */
+export type SetupPlatform = "linux" | "darwin";
+export type ProcessGroupState = "alive" | "gone" | "unknown";
+export interface ProcessEntry {
+    readonly pid: number;
+    readonly group: number;
+    readonly state: string;
+}
+export interface ProcessTable {
+    /** "alive" if any non-zombie process has this process group ID. */
+    groupState(group: number): Promise<ProcessGroupState>;
+    /** True only if a scan is determinate and contains the calling process. */
+    readable(): Promise<boolean>;
+    /** Poll interval for cleanup loops. */
+    readonly pollMs: number;
+}
+export interface PsOutput {
+    readonly exitCode: number;
+    readonly stdout: string;
+}
+export interface ProcessTableDependencies {
+    /** Test seam for the macOS `ps` call; undefined means it could not run. */
+    readonly runPs?: () => Promise<PsOutput | undefined>;
+    readonly selfPid?: number;
+}
+export declare function currentSetupPlatform(platform?: NodeJS.Platform): SetupPlatform | undefined;
+/** A regular, root-owned executable that no group or other user can replace. */
+export declare function isTrustedSystemBinary(path: string, statFile?: (path: string) => Pick<Stats, "isFile" | "uid" | "mode">): boolean;
+export declare const DARWIN_PS_PATH = "/bin/ps";
+/** Parses `ps -A -o pid=,pgid=,stat=`; any unexpected line rejects the whole sample. */
+export declare function parsePsTable(output: string): readonly ProcessEntry[] | undefined;
+export declare function createProcessTable(platform: SetupPlatform, dependencies?: ProcessTableDependencies): ProcessTable;
+export type StatfsReader = (path: string) => Promise<{
+    readonly type: number;
+}>;
+export declare function assertSupportedFilesystem(path: string, platform: SetupPlatform, readStatfs?: StatfsReader): Promise<void>;
+/** From XNU `bsd/sys/fcntl.h`; Node's `fs.constants` does not export these. */
+export declare const DARWIN_O_NONBLOCK = 4;
+export declare const DARWIN_O_EXLOCK = 32;
+export interface DarwinLockOptions {
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+    readonly retryMs?: number;
+    readonly openFile?: (path: string, flags: number, mode: number) => Promise<FileHandle>;
+}
+/**
+ * Opens the lock file with an exclusive lock on its open file description,
+ * which has flock(2) semantics on macOS. A busy lock is retried until the
+ * acquisition bound; a failed attempt holds no descriptor.
+ */
+export declare function openLockedDarwin(path: string, options: DarwinLockOptions): Promise<FileHandle>;

package/dist/setup-platform.js

@@ -0,0 +1,195 @@
+import { execFile } from "node:child_process";
+import { constants, readdirSync, readFileSync, statSync } from "node:fs";
+import { open, statfs } from "node:fs/promises";
+export function currentSetupPlatform(platform = process.platform) {
+    return platform === "linux" || platform === "darwin" ? platform : undefined;
+}
+/** A regular, root-owned executable that no group or other user can replace. */
+export function isTrustedSystemBinary(path, statFile = statSync) {
+    try {
+        const file = statFile(path);
+        return file.isFile() && file.uid === 0 && (file.mode & 0o022) === 0 && (file.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readLinuxProcessGroup(pid) {
+    const line = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
+    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)
+        throw new Error("process_group_invalid");
+    return { group, state };
+}
+function linuxGroupState(group) {
+    let entries;
+    try {
+        entries = readdirSync("/proc", { withFileTypes: true });
+    }
+    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) {
+    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;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return sawSelf;
+}
+export const DARWIN_PS_PATH = "/bin/ps";
+const PS_ARGUMENTS = ["-A", "-o", "pid=,pgid=,stat="];
+const PS_TIMEOUT_MS = 2_000;
+const PS_MAX_OUTPUT_BYTES = 1_048_576;
+/** Parses `ps -A -o pid=,pgid=,stat=`; any unexpected line rejects the whole sample. */
+export function parsePsTable(output) {
+    const body = output.endsWith("\n") ? output.slice(0, -1) : output;
+    if (body.length === 0)
+        return undefined;
+    const entries = [];
+    for (const line of body.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+        if (!match)
+            return undefined;
+        const pid = Number(match[1]);
+        const group = Number(match[2]);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(group))
+            return undefined;
+        entries.push({ pid, group, state: match[3] });
+    }
+    return entries;
+}
+function runDarwinPs() {
+    if (!isTrustedSystemBinary(DARWIN_PS_PATH))
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        try {
+            execFile(DARWIN_PS_PATH, [...PS_ARGUMENTS], { env: { LC_ALL: "C" }, timeout: PS_TIMEOUT_MS, maxBuffer: PS_MAX_OUTPUT_BYTES, encoding: "utf8" }, (error, stdout) => {
+                // A non-zero exit, timeout, output overflow or spawn failure is indeterminate.
+                resolve(error ? undefined : { exitCode: 0, stdout });
+            });
+        }
+        catch {
+            resolve(undefined);
+        }
+    });
+}
+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 runPs = dependencies.runPs ?? runDarwinPs;
+    const scan = async () => {
+        const output = await runPs();
+        if (!output || output.exitCode !== 0)
+            return undefined;
+        const entries = parsePsTable(output.stdout);
+        // A sample without the caller cannot be a complete process table.
+        return entries?.some((entry) => entry.pid === selfPid) ? entries : undefined;
+    };
+    return {
+        pollMs: 50,
+        async groupState(group) {
+            const entries = await scan();
+            if (!entries)
+                return "unknown";
+            return entries.some((entry) => entry.group === group && !entry.state.startsWith("Z")) ? "alive" : "gone";
+        },
+        async readable() { return (await scan()) !== undefined; },
+    };
+}
+// Kernel flock and directory fsync semantics are accepted only on the local
+// Linux filesystems covered by the setup test matrix.
+const SUPPORTED_LINUX_FILESYSTEMS = new Set([
+    0xef53, // ext2/3/4
+    0x58465342, // XFS
+    0x9123683e, // Btrfs
+    0x01021994, // tmpfs
+    0x794c7630, // overlayfs
+    0x2fc12fc1, // ZFS
+    0xf2f52010, // F2FS
+    0x24051905, // UBIFS
+    0xca451a4e, // bcachefs
+]);
+export async function assertSupportedFilesystem(path, platform, readStatfs = (target) => statfs(target)) {
+    const filesystem = await readStatfs(path);
+    if (platform === "linux") {
+        if (!SUPPORTED_LINUX_FILESYSTEMS.has(filesystem.type))
+            throw new Error("ownership_filesystem_unsupported");
+        return;
+    }
+    // macOS assigns f_type dynamically, so the directory must share the type of
+    // `/`, the sealed APFS system volume on every macOS that Node.js 22 supports.
+    if (filesystem.type !== (await readStatfs("/")).type)
+        throw new Error("ownership_filesystem_unsupported");
+}
+/** From XNU `bsd/sys/fcntl.h`; Node's `fs.constants` does not export these. */
+export const DARWIN_O_NONBLOCK = 0x4;
+export const DARWIN_O_EXLOCK = 0x20;
+/**
+ * Opens the lock file with an exclusive lock on its open file description,
+ * which has flock(2) semantics on macOS. A busy lock is retried until the
+ * acquisition bound; a failed attempt holds no descriptor.
+ */
+export async function openLockedDarwin(path, options) {
+    const openFile = options.openFile ?? ((target, flags, mode) => open(target, flags, mode));
+    const flags = constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW | DARWIN_O_EXLOCK | DARWIN_O_NONBLOCK;
+    const boundMs = Number.isFinite(options.timeoutMs) ? Math.max(1_000, Math.min(options.timeoutMs, 120_000)) : 120_000;
+    const deadline = Date.now() + boundMs;
+    const retryMs = options.retryMs ?? 50;
+    while (true) {
+        if (options.signal?.aborted)
+            throw new Error("operation_aborted");
+        try {
+            return await openFile(path, flags, 0o600);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EAGAIN" && code !== "EWOULDBLOCK")
+                throw new Error("ownership_lock_unavailable");
+        }
+        if (Date.now() >= deadline)
+            throw new Error("ownership_lock_busy");
+        await new Promise((resolve) => {
+            const done = () => { clearTimeout(timer); options.signal?.removeEventListener("abort", done); resolve(); };
+            const timer = setTimeout(done, retryMs);
+            options.signal?.addEventListener("abort", done, { once: true });
+        });
+    }
+}

package/dist/setup-process.d.ts

@@ -23,8 +23,11 @@ export interface McpLauncherOptions {
 /** Starts the local MCP server with only the controlled configuration environment. */
 export declare function createMcpStdioLauncher(options: McpLauncherOptions): (signal: AbortSignal) => Promise<McpStdioProcess>;
 /**
- * Acquires the Linux kernel fence and starts the transaction guardian. The
- * guardian inherits the locked file description, so parent death cannot release
- * the fence while a client mutation or descendant is still live.
+ * 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 declare function acquireSetupGuardian(lockFd: number, timeoutMs: number, signal?: AbortSignal, validateFence?: () => Promise<void>): Promise<SetupGuardian>;