pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/setup-command-guardian.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+const TERM_GRACE_MS = 100;
+const CLEANUP_REPORT_MS = 2_000;
+const RETRY_MS = 25;
+let active;
+let shuttingDown = false;
+// Source-mode signal injection is available only to credential-free tests. The
+// accepted production entry is the bound .js artifact, where this branch is off.
+let forceUnknownForSourceTest = false;
+if (process.argv[1]?.endsWith(".ts")) {
+    process.on("SIGUSR1", () => { forceUnknownForSourceTest = true; });
+    process.on("SIGUSR2", () => { forceUnknownForSourceTest = false; });
+}
+const parentArgument = Number(process.argv[2]);
+const owningParent = Number.isSafeInteger(parentArgument) && parentArgument > 1 ? parentArgument : process.ppid;
+const parentWatch = setInterval(() => {
+    if (process.ppid === owningParent)
+        return;
+    shuttingDown = true;
+    if (active)
+        void terminateActive();
+    else
+        exitWhenSafe();
+}, RETRY_MS);
+function send(message) {
+    if (process.connected)
+        process.send?.(message, undefined, undefined, () => undefined);
+}
+function exitWhenSafe() {
+    clearInterval(parentWatch);
+    if (process.connected)
+        process.disconnect();
+    process.exitCode = 0;
+}
+function parseRequest(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const input = value;
+    if (input.type === "shutdown" && Object.keys(input).length === 1)
+        return { type: "shutdown" };
+    if (input.type === "abort" && Object.keys(input).length === 2 && Number.isSafeInteger(input.id))
+        return { type: "abort", id: input.id };
+    if (input.type !== "run" || Object.keys(input).sort().join(",") !== "args,command,id,maxOutputBytes,timeoutMs,type")
+        return undefined;
+    if (!Number.isSafeInteger(input.id) || typeof input.command !== "string" || input.command.length === 0 || input.command.length > 4_096)
+        return undefined;
+    if (!Array.isArray(input.args) || input.args.length > 128 || !input.args.every((argument) => typeof argument === "string" && argument.length <= 16_384))
+        return undefined;
+    if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > 120_000)
+        return undefined;
+    if (!Number.isSafeInteger(input.maxOutputBytes) || input.maxOutputBytes < 1 || input.maxOutputBytes > 1_048_576)
+        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 {
+        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";
+}
+function signalGroup(group, signal) {
+    try {
+        process.kill(-group, signal);
+    }
+    catch { /* absence is confirmed by the scan */ }
+}
+function bounded(value, maximum) {
+    return Buffer.from(value).subarray(0, maximum).toString("utf8");
+}
+function start(request) {
+    if (active || shuttingDown) {
+        send({ type: "result", id: request.id, exitCode: 126, stdout: "", stderr: "" });
+        return;
+    }
+    let child;
+    try {
+        child = spawn(request.command, [...request.args], { stdio: ["ignore", "pipe", "pipe", 3], detached: true });
+    }
+    catch {
+        send({ type: "result", id: request.id, exitCode: 127, stdout: "", stderr: "" });
+        return;
+    }
+    if (child.pid === undefined || !child.stdout || !child.stderr) {
+        child.once("error", () => undefined);
+        send({ type: "result", id: request.id, exitCode: 127, stdout: "", stderr: "" });
+        return;
+    }
+    const execution = { id: request.id, child, group: child.pid, cleanupStarted: false, resultSent: false };
+    active = execution;
+    let stdout = "";
+    let stderr = "";
+    let overflow = false;
+    const collect = (stream) => (chunk) => {
+        const next = (stream === "stdout" ? stdout : stderr) + chunk.toString("utf8");
+        if (Buffer.byteLength(next, "utf8") > request.maxOutputBytes) {
+            overflow = true;
+            return;
+        }
+        if (stream === "stdout")
+            stdout = next;
+        else
+            stderr = next;
+    };
+    child.stdout.on("data", collect("stdout"));
+    child.stderr.on("data", collect("stderr"));
+    const finish = (exitCode) => {
+        if (execution.resultSent)
+            return;
+        execution.resultSent = true;
+        if (execution.timeout)
+            clearTimeout(execution.timeout);
+        send({ type: "result", id: request.id, exitCode, stdout: bounded(stdout, request.maxOutputBytes), stderr: overflow ? "output_limit" : bounded(stderr, request.maxOutputBytes) });
+    };
+    const cleanup = async (reportedCode) => {
+        if (execution.cleanupStarted)
+            return;
+        execution.cleanupStarted = true;
+        signalGroup(execution.group, "SIGTERM");
+        await new Promise((resolve) => setTimeout(resolve, TERM_GRACE_MS));
+        signalGroup(execution.group, "SIGKILL");
+        const reportDeadline = Date.now() + CLEANUP_REPORT_MS;
+        while (true) {
+            const state = groupState(execution.group);
+            if (state === "gone") {
+                finish(reportedCode);
+                active = undefined;
+                if (shuttingDown || !process.connected)
+                    exitWhenSafe();
+                return;
+            }
+            if (!execution.resultSent && Date.now() >= reportDeadline)
+                finish(126);
+            signalGroup(execution.group, "SIGKILL");
+            await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+        }
+    };
+    execution.timeout = setTimeout(() => { void cleanup(124); }, request.timeoutMs);
+    child.once("error", () => {
+        if (execution.cleanupStarted)
+            return;
+        finish(127);
+        active = undefined;
+        if (shuttingDown || !process.connected)
+            exitWhenSafe();
+    });
+    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);
+    });
+}
+process.on("message", (value) => {
+    const request = parseRequest(value);
+    if (!request) {
+        shuttingDown = true;
+        if (active)
+            void terminateActive();
+        else {
+            if (process.connected)
+                process.disconnect();
+            process.exitCode = 64;
+        }
+        return;
+    }
+    if (request.type === "run") {
+        start(request);
+        return;
+    }
+    if (request.type === "abort") {
+        if (active?.id === request.id)
+            void terminateActive();
+        return;
+    }
+    shuttingDown = true;
+    if (active)
+        void terminateActive();
+    else
+        exitWhenSafe();
+});
+async function terminateActive() {
+    const execution = active;
+    if (!execution || execution.cleanupStarted)
+        return;
+    execution.cleanupStarted = true;
+    if (execution.timeout)
+        clearTimeout(execution.timeout);
+    signalGroup(execution.group, "SIGTERM");
+    await new Promise((resolve) => setTimeout(resolve, TERM_GRACE_MS));
+    signalGroup(execution.group, "SIGKILL");
+    const reportDeadline = Date.now() + CLEANUP_REPORT_MS;
+    while (true) {
+        const state = groupState(execution.group);
+        if (state === "gone") {
+            if (!execution.resultSent) {
+                execution.resultSent = true;
+                send({ type: "result", id: execution.id, exitCode: 125, stdout: "", stderr: "" });
+            }
+            active = undefined;
+            if (shuttingDown || !process.connected)
+                exitWhenSafe();
+            return;
+        }
+        if (!execution.resultSent && Date.now() >= reportDeadline) {
+            execution.resultSent = true;
+            send({ type: "result", id: execution.id, exitCode: 126, stdout: "", stderr: "" });
+        }
+        signalGroup(execution.group, "SIGKILL");
+        await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+    }
+}
+process.on("disconnect", () => {
+    shuttingDown = true;
+    if (active)
+        void terminateActive();
+    else
+        exitWhenSafe();
+});
+process.once("SIGINT", () => { shuttingDown = true; if (active)
+    void terminateActive();
+else
+    exitWhenSafe(); });
+process.once("SIGTERM", () => { shuttingDown = true; if (active)
+    void terminateActive();
+else
+    exitWhenSafe(); });
+if (processTableReadable())
+    send({ type: "ready" });
+else {
+    clearInterval(parentWatch);
+    if (process.connected)
+        process.disconnect();
+    process.exitCode = 69;
+}

package/dist/setup-main.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createProductionSetup } from "./setup.js";
+/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias`. */
+export interface SetupMainDependencies {
+    readonly createSetup?: typeof createProductionSetup;
+    readonly packageRoot?: string;
+}
+export declare function main(argv?: readonly string[], dependencies?: SetupMainDependencies): Promise<number>;

package/dist/setup-main.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntryPoint } from "./entry-point.js";
+import { createProcessRunner } from "./setup-process.js";
+import { createProductionSetup, isSupportedTarget } from "./setup.js";
+import { formatSetupHuman, formatSetupResult, parseSetupArgs } from "./setup-cli.js";
+import { result } from "./setup-result.js";
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+    let json = argv.includes("--json");
+    let request;
+    try {
+        request = parseSetupArgs(argv);
+        json = request.json;
+    }
+    catch {
+        return write(cliFailure("dry-run", [], "usage_invalid", 64), json);
+    }
+    const operation = request.operation ?? "dry-run";
+    if (process.platform !== "linux")
+        return write(cliFailure(operation, request.targets, "platform_unsupported", 1), request.json);
+    const config = process.env.PI_SESSION_MCP_CONFIG;
+    if (!config)
+        return write(cliFailure(operation, request.targets, "config_required", 1), request.json);
+    const root = dependencies.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const controller = new AbortController();
+    let interrupted;
+    const onInterrupt = () => { interrupted ??= 130; controller.abort(); };
+    const onTerminate = () => { interrupted ??= 143; controller.abort(); };
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    let setup;
+    try {
+        try {
+            setup = await (dependencies.createSetup ?? createProductionSetup)(createProcessRunner({ signal: controller.signal }), root, resolve(config), undefined, controller.signal);
+        }
+        catch {
+            return write(cliFailure(operation, request.targets, interrupted ? "operation_interrupted" : "release_unavailable", interrupted ?? 1), request.json);
+        }
+        try {
+            const output = await setup.run(request);
+            return write(interrupted ? cliFailure(operation, request.targets, "operation_interrupted", interrupted) : output, request.json);
+        }
+        catch {
+            return write(cliFailure(operation, request.targets, interrupted ? "operation_interrupted" : "operation_failed", interrupted ?? 1), request.json);
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onInterrupt);
+        process.removeListener("SIGTERM", onTerminate);
+    }
+}
+function cliFailure(operation, targets, code, exitCode) {
+    const safeTargets = targets.filter(isSupportedTarget);
+    const reported = safeTargets.length === targets.length && safeTargets.length > 0 ? safeTargets : [{ client: "invalid", scope: "invalid", alias: "invalid" }];
+    return result(operation, reported.map((target) => ({ target, status: "failed", code })), "failed", exitCode);
+}
+function write(value, json) { process.stdout.write((json ? formatSetupResult(value) : formatSetupHuman(value)) + "\n"); return value.exitCode; }
+if (isEntryPoint(import.meta.url, process.argv[1]))
+    void main().then((code) => { process.exitCode = code; });

package/dist/setup-ownership.d.ts

@@ -0,0 +1,53 @@
+import type { CommandRunner } from "./client-adapters/types.js";
+import type { SetupTarget } from "./setup-result.js";
+export interface OwnershipRecord {
+    readonly target: SetupTarget;
+    readonly fingerprint: string;
+    readonly previous: "absent" | "equivalent";
+    readonly phase: "pending" | "owned";
+    readonly transactionId: string;
+}
+export interface RegistrationSnapshot {
+    /** Opaque adapter-owned snapshot; implementations must not persist secrets. */
+    readonly fingerprint: string;
+    readonly payload: unknown;
+}
+export type OwnedRegistration = OwnershipRecord;
+export interface OwnershipAccess {
+    get(target: SetupTarget): Promise<OwnershipRecord | undefined>;
+    put(registration: OwnershipRecord): Promise<void>;
+    delete(target: SetupTarget): Promise<void>;
+    /** Throws a stable, path-free error if the transaction fence is unhealthy. */
+    assertHealthy?(): void;
+    signal?(): AbortSignal;
+    readonly mutationRunner?: CommandRunner;
+}
+export interface OwnershipStore extends OwnershipAccess {
+    transaction<T>(operation: (access: OwnershipAccess) => Promise<T>): Promise<T>;
+}
+/** Safe default for one process; callers needing recovery inject a durable store. */
+export declare class MemoryOwnershipStore implements OwnershipStore {
+    private readonly entries;
+    private transactionTail;
+    get(target: SetupTarget): Promise<OwnershipRecord | undefined>;
+    put(registration: OwnershipRecord): Promise<void>;
+    delete(target: SetupTarget): Promise<void>;
+    transaction<T>(operation: (access: OwnershipAccess) => Promise<T>): Promise<T>;
+}
+export declare class DurableOwnershipStore implements OwnershipStore {
+    private readonly path;
+    private readonly options;
+    constructor(path: string, options?: {
+        readonly acquireTimeoutMs?: number;
+        readonly afterLockOpen?: () => Promise<void> | void;
+        readonly beforeRename?: () => Promise<void> | void;
+        readonly signal?: AbortSignal;
+    });
+    private read;
+    get(target: SetupTarget): Promise<OwnershipRecord | undefined>;
+    put(registration: OwnershipRecord): Promise<void>;
+    delete(target: SetupTarget): Promise<void>;
+    transaction<T>(operation: (access: OwnershipAccess) => Promise<T>): Promise<T>;
+    private withLock;
+    private write;
+}

package/dist/setup-ownership.js

@@ -0,0 +1,228 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, rename, rm, stat, statfs } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { acquireSetupGuardian } from "./setup-process.js";
+/** Safe default for one process; callers needing recovery inject a durable store. */
+export class MemoryOwnershipStore {
+    entries = new Map();
+    transactionTail = Promise.resolve();
+    async get(target) { return this.entries.get(key(target)); }
+    async put(registration) { this.entries.set(key(registration.target), registration); }
+    async delete(target) { this.entries.delete(key(target)); }
+    async transaction(operation) {
+        const previous = this.transactionTail;
+        let release;
+        this.transactionTail = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            return await operation(this);
+        }
+        finally {
+            release();
+        }
+    }
+}
+export class DurableOwnershipStore {
+    path;
+    options;
+    constructor(path, options = {}) {
+        this.path = path;
+        this.options = options;
+    }
+    async read() { let parsed; try {
+        if ((await stat(this.path)).size > 65_536)
+            throw new Error("ownership_too_large");
+        parsed = JSON.parse(await readFile(this.path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw new Error("ownership_unreadable");
+    } if (!Array.isArray(parsed) || parsed.length > 128 || !parsed.every(isRecord))
+        throw new Error("ownership_corrupt"); return parsed; }
+    async get(target) { return (await this.read()).find((entry) => key(entry.target) === key(target)); }
+    async put(registration) { await this.transaction((access) => access.put(registration)); }
+    async delete(target) { await this.transaction((access) => access.delete(target)); }
+    async transaction(operation) {
+        return this.withLock(operation);
+    }
+    async withLock(operation) {
+        if (process.platform !== "linux")
+            throw new Error("platform_unsupported");
+        const directory = dirname(this.path);
+        await ensureOwnershipDirectory(directory);
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        this.options.signal?.addEventListener("abort", abort, { once: true });
+        if (this.options.signal?.aborted)
+            controller.abort();
+        const assertHealthy = () => {
+            if (controller.signal.aborted)
+                throw new Error("operation_aborted");
+        };
+        const lockPath = `${this.path}.flock`;
+        let lockHandle;
+        try {
+            lockHandle = await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+            await lockHandle.chmod(0o600);
+            await lockHandle.sync();
+            await syncDirectory(directory);
+            const [descriptor, linked] = await Promise.all([lockHandle.stat(), stat(lockPath)]);
+            if (!descriptor.isFile() || !linked.isFile() || descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+                throw new Error("ownership_lock_invalid");
+            await this.options.afterLockOpen?.();
+        }
+        catch {
+            this.options.signal?.removeEventListener("abort", abort);
+            await lockHandle?.close().catch(() => undefined);
+            throw new Error("ownership_lock_unavailable");
+        }
+        const validateLock = async () => {
+            const [descriptor, linked] = await Promise.all([lockHandle.stat(), stat(lockPath)]);
+            if (!descriptor.isFile() || !linked.isFile() || descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+                throw new Error("ownership_lock_invalid");
+        };
+        let guardian;
+        try {
+            guardian = await acquireSetupGuardian(lockHandle.fd, this.options.acquireTimeoutMs ?? 30_000, controller.signal, validateLock);
+        }
+        catch (error) {
+            this.options.signal?.removeEventListener("abort", abort);
+            await lockHandle.close().catch(() => undefined);
+            const code = error.message;
+            throw new Error(["ownership_lock_busy", "operation_aborted"].includes(code) ? code : "ownership_lock_unavailable");
+        }
+        try {
+            await validateLock();
+        }
+        catch {
+            this.options.signal?.removeEventListener("abort", abort);
+            try {
+                await guardian.release();
+            }
+            finally {
+                await lockHandle.close().catch(() => undefined);
+            }
+            throw new Error("ownership_lock_unavailable");
+        }
+        const compromise = () => controller.abort();
+        guardian.signal.addEventListener("abort", compromise, { once: true });
+        try {
+            const access = {
+                get: async (target) => { assertHealthy(); const value = await this.read(); assertHealthy(); return value.find((entry) => key(entry.target) === key(target)); },
+                put: async (registration) => { assertHealthy(); if (!isRecord(registration))
+                    throw new Error("ownership_invalid"); const entries = (await this.read()).filter((entry) => key(entry.target) !== key(registration.target)); entries.push(registration); assertHealthy(); await this.write(entries, assertHealthy); assertHealthy(); },
+                delete: async (target) => { assertHealthy(); const entries = (await this.read()).filter((entry) => key(entry.target) !== key(target)); assertHealthy(); await this.write(entries, assertHealthy); assertHealthy(); },
+                assertHealthy,
+                signal: () => controller.signal,
+                mutationRunner: guardian.runner,
+            };
+            const value = await operation(access);
+            assertHealthy();
+            return value;
+        }
+        finally {
+            guardian.signal.removeEventListener("abort", compromise);
+            this.options.signal?.removeEventListener("abort", abort);
+            try {
+                await guardian.release();
+            }
+            finally {
+                await lockHandle.close().catch(() => undefined);
+            }
+        }
+    }
+    async write(entries, assertHealthy) { const directory = dirname(this.path); const temporary = `${this.path}.tmp-${process.pid}-${randomUUID()}`; let renamed = false; try {
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(entries));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await this.options.beforeRename?.();
+        assertHealthy();
+        await rename(temporary, this.path);
+        renamed = true;
+        await syncDirectory(directory);
+    }
+    finally {
+        if (!renamed)
+            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) {
+    const missing = [];
+    let cursor = directory;
+    while (true) {
+        try {
+            const existing = await lstat(cursor);
+            if (!existing.isDirectory() || existing.isSymbolicLink())
+                throw new Error("ownership_directory_invalid");
+            break;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw new Error("ownership_directory_unavailable");
+            missing.push(cursor);
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                throw new Error("ownership_directory_unavailable");
+            cursor = parent;
+        }
+    }
+    await assertSupportedFilesystem(cursor);
+    for (const candidate of missing.reverse()) {
+        try {
+            await mkdir(candidate, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw new Error("ownership_directory_unavailable");
+        }
+        const created = await lstat(candidate);
+        if (!created.isDirectory() || created.isSymbolicLink())
+            throw new Error("ownership_directory_unavailable");
+        await chmod(candidate, 0o700);
+        await syncDirectory(candidate);
+        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");
+}
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isRecord(value) { if (!value || typeof value !== "object")
+    return false; const x = value; if (!exactKeys(x, ["target", "fingerprint", "previous", "phase", "transactionId"]))
+    return false; const t = x.target; if (!t || typeof t !== "object")
+    return false; const target = t; if (!exactKeys(target, ["client", "scope", "alias"]))
+    return false; const client = target.client; const scope = target.scope; return (client === "codex" || client === "claude-code") && typeof scope === "string" && (client === "codex" ? scope === "user" : ["user", "project", "local"].includes(scope)) && target.alias === "pi-session-mcp" && typeof x.fingerprint === "string" && /^[a-f0-9]{64}$/.test(x.fingerprint) && (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" && typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId); }
+function exactKeys(value, expected) { const keys = Object.keys(value).sort(); return keys.length === expected.length && [...expected].sort().every((key, index) => keys[index] === key); }
+const key = (target) => `${target.client}\u0000${target.scope}\u0000${target.alias}`;

package/dist/setup-process.d.ts

@@ -0,0 +1,30 @@
+import type { CommandRunner } from "./client-adapters/types.js";
+import type { McpStdioProcess } from "./client-adapters/mcp-verifier.js";
+export interface ProcessRunnerOptions {
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+}
+export interface SetupGuardian {
+    readonly runner: CommandRunner;
+    readonly signal: AbortSignal;
+    release(): Promise<void>;
+}
+/** Runs only an explicit executable/argv pair, with bounded output and termination. */
+export declare function createProcessRunner(options?: ProcessRunnerOptions): CommandRunner;
+export interface McpLauncherOptions {
+    readonly nodePath: string;
+    readonly entryPath: string;
+    readonly configPath: string;
+    readonly timeoutMs?: number;
+    readonly maxFrameBytes?: number;
+}
+/** 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.
+ */
+export declare function acquireSetupGuardian(lockFd: number, timeoutMs: number, signal?: AbortSignal, validateFence?: () => Promise<void>): Promise<SetupGuardian>;