pi-session-mcp 0.8.3 → 0.12.0

package/dist/child-stdio-transport.d.ts

@@ -0,0 +1,21 @@
+import { type Transport } from "@modelcontextprotocol/client";
+/** A launcher is a lease guardian: EOF requests cleanup; killing it would break that contract. */
+/** A frame carries a result twice (text content and structured content); 2 MiB covers both at the relay's size bound. */
+export declare class ChildStdioTransport implements Transport {
+    private readonly command;
+    private readonly env;
+    private readonly args;
+    onclose: Transport["onclose"];
+    onerror: Transport["onerror"];
+    onmessage: Transport["onmessage"];
+    private child?;
+    private closed;
+    private started;
+    private readonly buffer;
+    private pending;
+    constructor(command: string, env: Record<string, string>, args?: readonly string[]);
+    start(): Promise<void>;
+    send(message: Parameters<Transport["send"]>[0]): Promise<void>;
+    close(): Promise<void>;
+    private finish;
+}

package/dist/child-stdio-transport.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/client";
+/** A launcher is a lease guardian: EOF requests cleanup; killing it would break that contract. */
+/** A frame carries a result twice (text content and structured content); 2 MiB covers both at the relay's size bound. */
+export class ChildStdioTransport {
+    command;
+    env;
+    args;
+    onclose;
+    onerror;
+    onmessage;
+    child;
+    closed = false;
+    started = false;
+    buffer = new ReadBuffer({ maxBufferSize: 2_097_152 });
+    pending = Buffer.alloc(0);
+    constructor(command, env, args = []) {
+        this.command = command;
+        this.env = env;
+        this.args = args;
+    }
+    async start() {
+        if (this.started || this.closed)
+            throw new Error("Transport cannot start");
+        this.started = true;
+        const child = this.child = spawn(this.command, [...this.args], { detached: true, stdio: ["pipe", "pipe", "pipe"], env: { ...this.env }, shell: false });
+        child.stderr.on("data", () => undefined);
+        child.stdin.on("error", () => this.onerror?.(new Error("Writer input failed")));
+        child.on("error", () => this.onerror?.(new Error("Writer process failed")));
+        child.on("close", () => this.finish());
+        child.stdout.on("data", (chunk) => {
+            if (this.closed)
+                return;
+            try {
+                this.pending = Buffer.concat([this.pending, chunk]);
+                let newline;
+                while ((newline = this.pending.indexOf(10)) !== -1) {
+                    if (newline > 2_097_152)
+                        throw new Error();
+                    const line = this.pending.subarray(0, newline + 1);
+                    this.pending = this.pending.subarray(newline + 1);
+                    // ReadBuffer silently skips JSON syntax errors; detect them before decoding.
+                    JSON.parse(line.toString("utf8"));
+                    this.buffer.append(line);
+                    const message = this.buffer.readMessage();
+                    if (message === null)
+                        throw new Error();
+                    this.onmessage?.(message);
+                }
+                if (this.pending.length > 2_097_152)
+                    throw new Error();
+            }
+            catch {
+                this.onerror?.(new Error("Invalid writer frame"));
+                void this.close();
+            }
+        });
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", () => reject(new Error("Writer spawn failed")));
+        });
+    }
+    async send(message) {
+        if (this.closed || !this.child)
+            throw new Error("Writer transport is closed");
+        await new Promise((resolve, reject) => {
+            this.child.stdin.write(serializeMessage(message), error => error ? reject(new Error("Writer send failed")) : resolve());
+        });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.child?.stdin.end();
+        // Keep draining diagnostics/output while the guardian cleans up, without keeping the host alive.
+        this.child?.unref();
+        this.child?.stdout?.unref?.();
+        this.child?.stderr?.unref?.();
+        this.finish();
+    }
+    finish() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.buffer.clear();
+        this.pending = Buffer.alloc(0);
+        this.onclose?.();
+    }
+}

package/dist/client-adapters/claude-code.js

@@ -1,5 +1,6 @@
-import { safeRunner, versionFromOutput } from "./command.js";
+import { CLAUDE_DID_YOU_MEAN_SUFFIX, safeRunner, versionFromOutput } from "./command.js";
 const NAME = "pi-session-mcp";
+const ABSENT = new RegExp(`^No MCP server named "pi-session-mcp"\\.(?:(?:\\s+Configured servers:.*)|(?:\\s+Run \u0060claude mcp add\u0060 to add one\\.)|(?:${CLAUDE_DID_YOU_MEAN_SUFFIX}))?\\s*$`, "i");
 function scopeArgs(scope) { return ["-s", scope]; }
 function inspectText(text, intent) {
     const bounded = text.slice(0, 32_768);
@@ -23,7 +24,7 @@ export function createClaudeCodeAdapter(input) {
     return {
         client: "claude-code",
         async discover() { const versionResult = await runner.run("claude", ["--version"]); const v = versionResult.exitCode === 0 ? versionFromOutput("claude-code", versionResult.stdout) : undefined; const probe = await runner.run("claude", ["mcp", "--help"]); const supported = probe.exitCode === 0 && ["get", "add", "remove"].every((command) => new RegExp(`\\b${command}\\b`).test(probe.stdout)); return { client: "claude-code", version: v ?? "unknown", supportsJson: false, supportsAdd: supported, supportsRemove: supported, scopes: supported ? ["user", "project", "local"] : [] }; },
-        async inspect(scope, intent) { const r = await runner.run("claude", ["mcp", "get", NAME]); const absent = /^No MCP server named \"pi-session-mcp\"\.(?:(?:\s+Configured servers:.*)|(?:\s+Run `claude mcp add` to add one\.))?\s*$/i.test(r.stderr.trim()); const x = r.exitCode === 0 ? inspectText(r.stdout, intent) : absent ? { state: "absent", expected: false } : { state: "unsupported", expected: false }; return { client: "claude-code", scope, name: NAME, state: x.state, command: x.expected ? "node" : "unknown", hasExpectedConfig: x.expected, supported: x.state !== "unsupported" }; },
+        async inspect(scope, intent) { const r = await runner.run("claude", ["mcp", "get", NAME]); const absent = ABSENT.test(r.stderr.trim()); const x = r.exitCode === 0 ? inspectText(r.stdout, intent) : absent ? { state: "absent", expected: false } : { state: "unsupported", expected: false }; return { client: "claude-code", scope, name: NAME, state: x.state, command: x.expected ? "node" : "unknown", hasExpectedConfig: x.expected, supported: x.state !== "unsupported" }; },
         async plan(intent) { const r = await this.inspect(intent.scope, intent); return { client: "claude-code", scope: intent.scope, state: r.state, operation: r.state === "absent" ? "add" : "none", reason: r.state === "absent" ? "missing" : r.state === "equivalent" ? "already_registered" : r.state }; },
         async add(intent, execution) { const r = await (execution?.runner ?? runner).run("claude", ["mcp", "add", NAME, "-s", intent.scope, "-e", `PI_SESSION_MCP_CONFIG=${intent.configPath}`, "--", intent.nodePath, intent.entryPath], execution?.signal); if (r.exitCode !== 0)
             throw new Error("client registration failed"); },

package/dist/client-adapters/command.d.ts

@@ -7,6 +7,14 @@ export declare const MAX_OUTPUT_BYTES = 32768;
  * on any other output. The version is reported for information only.
  */
 export type ClientName = "codex" | "claude-code";
+/**
+ * Regular-expression source of the suggestion suffix that Claude Code 2.1.310 appends to the absent message
+ * when a similar server name exists. Claude suggests from all its servers, including plugin servers
+ * (`plugin:<plugin>:<server>`) and connectors with spaces or dots, so the suggestion is any quoted text
+ * without a quote or line break, at most 256 characters. The message head pins the queried name exactly;
+ * the suggestion never decides which registration is absent.
+ */
+export declare const CLAUDE_DID_YOU_MEAN_SUFFIX: string;
 export declare function boundedResult(result: CommandResult): CommandResult;
 export declare function versionFromOutput(client: ClientName, output: string): string | undefined;
 export declare function safeRunner(run: CommandRunner["run"]): CommandRunner;

package/dist/client-adapters/command.js

@@ -1,5 +1,13 @@
 export const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
 export const MAX_OUTPUT_BYTES = 32_768;
+/**
+ * Regular-expression source of the suggestion suffix that Claude Code 2.1.310 appends to the absent message
+ * when a similar server name exists. Claude suggests from all its servers, including plugin servers
+ * (`plugin:<plugin>:<server>`) and connectors with spaces or dots, so the suggestion is any quoted text
+ * without a quote or line break, at most 256 characters. The message head pins the queried name exactly;
+ * the suggestion never decides which registration is absent.
+ */
+export const CLAUDE_DID_YOU_MEAN_SUFFIX = String.raw `\s+Did you mean "[^"\r\n]{1,256}"\? Run \u0060claude mcp list\u0060 to see all\.`;
 export function boundedResult(result) {
     const truncate = (value) => {
         const bytes = Buffer.from(value, "utf8");
@@ -21,5 +29,5 @@ export function versionFromOutput(client, output) {
     return match?.[1];
 }
 export function safeRunner(run) {
-    return { run: async (command, args, signal) => boundedResult(await run(command, args, signal)) };
+    return { run: async (command, args, signal, options) => boundedResult(await run(command, args, signal, options)) };
 }

package/dist/client-adapters/mcp-verifier.d.ts

@@ -1,5 +1,12 @@
 export declare const MCP_VERIFY_TIMEOUT_MS = 5000;
 export declare const MCP_MAX_FRAME_BYTES = 65536;
+/**
+ * Upper bound for stopping the launched server once verification has ended. It starts when the
+ * exchange ends, so a verification takes at most `timeoutMs` plus `min(timeoutMs, this)`. It covers
+ * the launchers' usual worst-case `kill()` (shutdown grace plus about 2 s of cleanup polling); a slower
+ * `kill()`, possible with slow `/bin/ps` calls on macOS, reports `failed`.
+ */
+export declare const MCP_KILL_BUDGET_MS = 5000;
 export interface McpStdioProcess {
     write(frame: string): void | Promise<void>;
     read(): Promise<string | null>;

package/dist/client-adapters/mcp-verifier.js

@@ -1,8 +1,16 @@
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
+import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS } from "../session-tools.js";
 import { MAX_PROFILE_SKILLS } from "../skill-catalog.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../package-metadata.js";
 export const MCP_VERIFY_TIMEOUT_MS = 5_000;
 export const MCP_MAX_FRAME_BYTES = 65_536;
+/**
+ * Upper bound for stopping the launched server once verification has ended. It starts when the
+ * exchange ends, so a verification takes at most `timeoutMs` plus `min(timeoutMs, this)`. It covers
+ * the launchers' usual worst-case `kill()` (shutdown grace plus about 2 s of cleanup polling); a slower
+ * `kill()`, possible with slow `/bin/ps` calls on macOS, reports `failed`.
+ */
+export const MCP_KILL_BUDGET_MS = 5_000;
 const EXPECTED_TOOLS = ["pi_capabilities_get", "pi_session_start", "pi_session_list", "pi_session_get", "pi_session_prompt", "pi_session_abort", "pi_session_close", "pi_turn_get"];
 const EXPECTED_PROTOCOL = "2025-03-26";
 const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
@@ -80,27 +88,33 @@ function validCapabilities(value) {
     if (!value || typeof value !== "object")
         return false;
     const x = value;
-    if (x.ok !== true || !exactKeys(x, ["ok", "server", "configuration", "workspaces", "executionProfiles"]) || !x.server || typeof x.server !== "object")
+    if (x.ok !== true || !exactKeys(x, ["ok", "server", "configuration", "events", "workspaces", "executionProfiles"]) || !x.server || typeof x.server !== "object")
         return false;
     const info = x.server;
     if (!exactKeys(info, ["name", "version"]) || info.name !== PACKAGE_NAME || info.version !== PACKAGE_VERSION || !Array.isArray(x.workspaces) || !Array.isArray(x.executionProfiles))
         return false;
     if (!validConfiguration(x.configuration))
         return false;
+    if (!x.events || typeof x.events !== "object")
+        return false;
+    const events = x.events;
+    if (!exactKeys(events, ["delivery"]) || (events.delivery !== "spool" && events.delivery !== "off"))
+        return false;
     const workspaces = x.workspaces;
     const profiles = x.executionProfiles;
     if (!workspaces.every((workspace) => {
         if (!workspace || typeof workspace !== "object")
             return false;
         const record = workspace;
-        return exactKeys(record, ["alias"]) && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias);
+        return exactKeys(record, ["alias", "mode"]) && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
+            && typeof record.mode === "string" && ["unset", "host", "container", "read-only"].includes(record.mode);
     }))
         return false;
     if (!profiles.every((profile) => {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "skills"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "grantedExtensionTools", "skills"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
@@ -109,6 +123,9 @@ function validCapabilities(value) {
             && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel)
             && Array.isArray(record.extensions) && record.extensions.length <= MAX_PROFILE_EXTENSIONS
             && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined)
+            && Array.isArray(record.grantedExtensionTools) && record.grantedExtensionTools.length <= MAX_GRANTED_EXTENSION_TOOLS
+            && record.grantedExtensionTools.every((name) => typeof name === "string" && isAcceptableExtensionToolName(name))
+            && new Set(record.grantedExtensionTools).size === record.grantedExtensionTools.length
             && Array.isArray(record.skills) && record.skills.length <= MAX_PROFILE_SKILLS
             && record.skills.every((skill) => typeof skill === "string" && ALIAS_PATTERN.test(skill))
             && new Set(record.skills).size === record.skills.length;
@@ -171,7 +188,7 @@ export async function verifyMcpCapabilities(options) {
     controller.abort();
     if (process) {
         try {
-            await beforeDeadline(Promise.resolve(process.kill()), Date.now() + Math.min(timeout, 1_000));
+            await beforeDeadline(Promise.resolve(process.kill()), Date.now() + Math.min(timeout, MCP_KILL_BUDGET_MS));
         }
         catch {
             return { ...outcome, status: "failed" };

package/dist/client-adapters/types.d.ts

@@ -8,7 +8,11 @@ export interface CommandResult {
     readonly stderr: string;
 }
 export interface CommandRunner {
-    run(command: string, args: readonly string[], signal?: AbortSignal): Promise<CommandResult>;
+    run(command: string, args: readonly string[], signal?: AbortSignal, options?: {
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+        inheritFds?: readonly number[];
+    }): Promise<CommandResult>;
 }
 export interface CommandExecution {
     readonly signal?: AbortSignal;

package/dist/client-adapters/writer-registration.d.ts

@@ -0,0 +1,16 @@
+import type { ClientName, CommandExecution, CommandRunner, RegistrationState } from "./types.js";
+import type { OwnershipStore } from "../setup-ownership.js";
+export interface WriterRegistrationIntent {
+    readonly client: ClientName;
+    readonly name: string;
+    readonly wrapperPath: string;
+    readonly projectDir: string;
+}
+export interface WriterRegistrationAdapter {
+    inspect(intent: WriterRegistrationIntent): Promise<RegistrationState>;
+    add(intent: WriterRegistrationIntent, execution?: CommandExecution): Promise<void>;
+    remove(intent: WriterRegistrationIntent, execution?: CommandExecution): Promise<void>;
+}
+export declare function createWriterRegistrationAdapter(input: CommandRunner): WriterRegistrationAdapter;
+export declare function registerWriter(ownership: OwnershipStore, adapter: WriterRegistrationAdapter, intent: WriterRegistrationIntent): Promise<void>;
+export declare function unregisterWriter(ownership: OwnershipStore, adapter: WriterRegistrationAdapter, intent: WriterRegistrationIntent): Promise<void>;

package/dist/client-adapters/writer-registration.js

@@ -0,0 +1,156 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { CLAUDE_DID_YOU_MEAN_SUFFIX, safeRunner } from "./command.js";
+import { WRITER_NAME_PATTERN } from "../writer-state.js";
+import { wrapperDigest } from "../writer-wrapper.js";
+function validate(intent) {
+    if (!["claude-code", "codex"].includes(intent.client) || !intent.name.startsWith("pi-coding-") ||
+        !WRITER_NAME_PATTERN.test(intent.name.slice("pi-coding-".length)) || !isAbsolute(intent.wrapperPath) ||
+        !isAbsolute(intent.projectDir) || intent.projectDir.length > 4_096 || /[\0\r\n]/.test(intent.wrapperPath + intent.projectDir)) {
+        throw new Error("writer_registration_invalid");
+    }
+}
+function claudeState(text, intent) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== `${intent.name}:`)
+        return "unsupported";
+    const field = (name) => new RegExp(`^\\s*${name}\\s*:[ \\t]*(.*)$`, "im").exec(text)?.[1]?.trim();
+    const scope = field("scope");
+    const type = field("type");
+    const command = field("command");
+    if (!scope || !type || !command)
+        return "unsupported";
+    // Any nonempty inline environment or indented environment entry is divergent.
+    const environment = /(?:^|\n)[ \t]*environment[ \t]*:[ \t]*(\S[^\n]*)/i.test(text) ||
+        /(?:^|\n)[ \t]*environment[ \t]*:[ \t]*\r?\n(?:[ \t]*\r?\n)*[ \t]{4,}\S/i.test(text);
+    return /^local config\b/i.test(scope) && type === "stdio" && command === intent.wrapperPath &&
+        !field("args?") && !environment ? "equivalent" : "divergent";
+}
+function codexState(text, intent) {
+    try {
+        const value = JSON.parse(text);
+        if (!value || typeof value !== "object" || !value.transport || typeof value.transport !== "object")
+            return "unsupported";
+        const t = value.transport;
+        const emptyEnvironment = t.env === null || (typeof t.env === "object" && !Array.isArray(t.env) && Object.keys(t.env).length === 0);
+        return value.name === intent.name && value.enabled === true && t.type === "stdio" && t.command === intent.wrapperPath &&
+            Array.isArray(t.args) && t.args.length === 0 && emptyEnvironment && Array.isArray(t.env_vars) && t.env_vars.length === 0 &&
+            t.cwd === null ? "equivalent" : "divergent";
+    }
+    catch {
+        return "unsupported";
+    }
+}
+export function createWriterRegistrationAdapter(input) {
+    const runner = safeRunner(input.run);
+    const options = (intent) => intent.client === "claude-code" ? { cwd: intent.projectDir } : undefined;
+    return {
+        async inspect(intent) {
+            validate(intent);
+            const claude = intent.client === "claude-code";
+            const result = await runner.run(claude ? "claude" : "codex", ["mcp", "get", intent.name, ...(claude ? [] : ["--json"])], undefined, options(intent));
+            if (result.exitCode === 0)
+                return claude ? claudeState(result.stdout, intent) : codexState(result.stdout, intent);
+            // Interpolate only a validated, regex-escaped registration name.
+            const name = intent.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const absent = claude
+                ? new RegExp(`^No MCP server named "${name}"\\.(?:(?:\\s+Configured servers:.*)|(?:\\s+Run \u0060claude mcp add\u0060 to add one\\.)|(?:${CLAUDE_DID_YOU_MEAN_SUFFIX}))?\\s*$`, "i")
+                : new RegExp(`^Error: No MCP server named '${name}' found\\.\\s*$`, "i");
+            return absent.test(result.stderr.trim()) ? "absent" : "unsupported";
+        },
+        async add(intent, execution) {
+            validate(intent);
+            const claude = intent.client === "claude-code";
+            const result = await (execution?.runner ?? runner).run(claude ? "claude" : "codex", ["mcp", "add", intent.name, ...(claude ? ["-s", "local"] : []), "--", intent.wrapperPath], execution?.signal, options(intent));
+            if (result.exitCode !== 0)
+                throw new Error("client_registration_failed");
+        },
+        async remove(intent, execution) {
+            validate(intent);
+            const claude = intent.client === "claude-code";
+            const result = await (execution?.runner ?? runner).run(claude ? "claude" : "codex", ["mcp", "remove", intent.name, ...(claude ? ["-s", "local"] : [])], execution?.signal, options(intent));
+            if (result.exitCode !== 0)
+                throw new Error("client_removal_failed");
+        },
+    };
+}
+async function fingerprint(intent, owned = false) {
+    let text;
+    try {
+        text = await readFile(intent.wrapperPath, "utf8");
+    }
+    catch {
+        throw Object.assign(new Error(owned ? "ownership_diverged" : "release_binding_mismatch"), { code: owned ? "ownership_diverged" : "release_binding_mismatch" });
+    }
+    return createHash("sha256").update(JSON.stringify({ wrapper: intent.wrapperPath, digest: wrapperDigest(text) })).digest("hex");
+}
+const targetFor = (intent) => ({ client: intent.client, scope: intent.client === "codex" ? "user" : "local", alias: intent.name });
+function execution(access) {
+    const signal = access.signal?.();
+    return { ...(signal ? { signal } : {}), ...(access.mutationRunner ? { runner: access.mutationRunner } : {}) };
+}
+export async function registerWriter(ownership, adapter, intent) {
+    validate(intent);
+    await ownership.transaction(async (access) => {
+        access.assertHealthy?.();
+        const target = targetFor(intent);
+        const owned = await access.get(target);
+        const expected = await fingerprint(intent, !!owned);
+        const current = await adapter.inspect(intent);
+        access.assertHealthy?.();
+        if (owned && owned.fingerprint !== expected)
+            throw new Error("release_binding_mismatch");
+        if (current === "absent" && owned?.phase === "owned")
+            throw new Error("ownership_diverged");
+        if (current === "equivalent") {
+            if (await fingerprint(intent, !!owned) !== expected)
+                throw new Error("registration_fingerprint_mismatch");
+            access.assertHealthy?.();
+            if (owned?.phase === "pending") {
+                await access.put({ ...owned, phase: "owned" });
+                access.assertHealthy?.();
+            }
+            return;
+        }
+        if (current !== "absent")
+            throw new Error(current === "divergent" ? "divergence_requires_replacement" : "client_unsupported");
+        const pending = { target, fingerprint: expected, previous: "absent", phase: "pending", transactionId: randomUUID() };
+        access.assertHealthy?.();
+        await access.put(pending);
+        access.assertHealthy?.();
+        await adapter.add(intent, execution(access));
+        access.assertHealthy?.();
+        const after = await adapter.inspect(intent);
+        access.assertHealthy?.();
+        if (after !== "equivalent" || await fingerprint(intent, true) !== expected)
+            throw new Error("post_apply_mismatch");
+        await access.put({ ...pending, phase: "owned" });
+        access.assertHealthy?.();
+    });
+}
+export async function unregisterWriter(ownership, adapter, intent) {
+    validate(intent);
+    await ownership.transaction(async (access) => {
+        access.assertHealthy?.();
+        const target = targetFor(intent);
+        const owned = await access.get(target);
+        if (!owned)
+            throw new Error("ownership_unavailable");
+        const current = await adapter.inspect(intent);
+        access.assertHealthy?.();
+        if (!["equivalent", "absent"].includes(current) || (current === "equivalent" && await fingerprint(intent, true) !== owned.fingerprint))
+            throw new Error("ownership_diverged");
+        if (current === "equivalent") {
+            await adapter.remove(intent, execution(access));
+            access.assertHealthy?.();
+            const after = await adapter.inspect(intent);
+            access.assertHealthy?.();
+            if (after !== "absent")
+                throw new Error("post_remove_mismatch");
+        }
+        access.assertHealthy?.();
+        await access.delete(target);
+        access.assertHealthy?.();
+    });
+}

package/dist/config.d.ts

@@ -1,11 +1,18 @@
 import { z } from "zod";
 import { type ConfiguredExecutionProfile } from "./execution-profile.js";
-export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level";
+import { type WorkspaceModeEntry } from "./execution-modes.js";
+export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level" | "invalid_execution_modes" | "invalid_event_delivery";
 export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
     constructor(code: ConfigErrorCode);
 }
 export declare const configSchema: z.ZodObject<{
+    events: z.ZodOptional<z.ZodObject<{
+        delivery: z.ZodEnum<{
+            off: "off";
+            spool: "spool";
+        }>;
+    }, z.core.$strict>>;
     workspaces: z.ZodRecord<z.ZodString, z.ZodString>;
     skillCatalog: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     executionProfiles: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -27,6 +34,7 @@ export declare const configSchema: z.ZodObject<{
         }>;
         mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
         extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        grantedExtensionTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -41,9 +49,12 @@ export interface ConfigurationMetadata {
 }
 export interface AppConfig {
     readonly workspaces: ReadonlyMap<string, string>;
+    readonly workspaceModes: ReadonlyMap<string, WorkspaceModeEntry>;
     readonly executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
     readonly defaultExecutionProfile: string;
     readonly configuration: ConfigurationMetadata;
+    /** Turn-event delivery: `spool` writes content-free event files, `off` (the default) writes nothing. */
+    readonly eventDelivery: "spool" | "off";
     /** Absolute skill override directory next to the configuration file. Internal; never projected. */
     readonly skillOverrideDirectory: string;
 }

package/dist/config.js

@@ -7,6 +7,8 @@ import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
 import { builtinSkillName, isSkillCatalogPath, MAX_PROFILE_SKILLS, MAX_SKILL_CATALOG_ENTRIES } from "./skill-catalog.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
 import { builtinSkillPath, skillOverrideDirectory } from "./skill-library.js";
+import { loadExecutionModes } from "./execution-modes.js";
+import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS, PROFILE_TOOLS } from "./session-tools.js";
 const alias = z.string().regex(ALIAS_PATTERN);
 const permissionProfile = z.enum(["read-only", "coding"]);
 const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
@@ -17,6 +19,7 @@ const profileSchema = z.object({
     model: z.string().trim().min(1).max(256), thinkingLevel,
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
     extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
+    grantedExtensionTools: z.array(z.string().refine(isAcceptableExtensionToolName)).max(MAX_GRANTED_EXTENSION_TOOLS).optional(),
     skills: z.array(alias).max(MAX_PROFILE_SKILLS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
@@ -28,6 +31,21 @@ const profileSchema = z.object({
             context.addIssue({ code: "custom", path: ["extensions"], message: "An extension package may appear only once per profile" });
         }
     }
+    if (profile.grantedExtensionTools !== undefined) {
+        if (profile.permissionProfile !== "read-only") {
+            context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "Extension tool grants require a read-only profile" });
+        }
+        if (!profile.extensions?.length) {
+            context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "Extension tool grants require extensions" });
+        }
+        if (new Set(profile.grantedExtensionTools).size !== profile.grantedExtensionTools.length) {
+            context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "An extension tool may be granted only once per profile" });
+        }
+        const builtins = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"]]);
+        if (profile.grantedExtensionTools.some((name) => builtins.has(name))) {
+            context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "Extension tool grants must not name built-in tools" });
+        }
+    }
     if (profile.skills !== undefined && new Set(profile.skills).size !== profile.skills.length) {
         context.addIssue({ code: "custom", path: ["skills"], message: "A skill alias may appear only once per profile" });
     }
@@ -36,6 +54,8 @@ const CONFIG_ERROR_MESSAGES = {
     config_path_required: "Configuration path is required",
     invalid_execution_profile_config: "Execution profile configuration is invalid",
     invalid_thinking_level: "Execution profile thinking level is invalid",
+    invalid_execution_modes: "Execution modes file is invalid",
+    invalid_event_delivery: "Event delivery configuration is invalid",
 };
 export class ConfigError extends Error {
     code;
@@ -45,7 +65,9 @@ export class ConfigError extends Error {
         this.code = code;
     }
 }
+const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
+    events: eventsSchema.optional(),
     workspaces: z.record(alias, z.string().min(1)),
     skillCatalog: z.record(alias, skillCatalogPath).refine((catalog) => Object.keys(catalog).length <= MAX_SKILL_CATALOG_ENTRIES).optional(),
     executionProfiles: z.record(alias, profileSchema).superRefine((profiles, context) => {
@@ -114,7 +136,9 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
     catch (error) {
         if (error instanceof z.ZodError) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : "invalid_execution_profile_config");
+            // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
+            const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
         }
         throw error;
     }
@@ -122,17 +146,19 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
     const overrideDirectory = skillOverrideDirectory(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
     const catalog = parsed.skillCatalog ?? {};
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, skills, ...value }]) => {
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, grantedExtensionTools, skills, ...value }]) => {
         const selection = resolveSkillSelection(skills, catalog, base, overrideDirectory);
         return [key, Object.freeze({
                 alias: key, ...value,
                 ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
                 ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
+                ...(grantedExtensionTools === undefined ? {} : { grantedExtensionTools: Object.freeze([...grantedExtensionTools]) }),
                 ...(selection === undefined ? {} : { skills: selection }),
             })];
     }));
+    const workspaceModes = await loadExecutionModes(absoluteConfig, new Set(workspaces.keys()), executionProfiles);
     const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
     if (!defaultEntry)
         throw new Error("Execution profile configuration is invalid");
-    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration, skillOverrideDirectory: overrideDirectory };
+    return { workspaces, workspaceModes, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration, eventDelivery: parsed.events?.delivery ?? "off", skillOverrideDirectory: overrideDirectory };
 }

package/dist/container-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Offline, bounded rootless Podman check; no runtime diagnostics enter reports or stdout. */
+export declare function containerRuntimeUsable(): Promise<boolean>;

package/dist/container-runtime.js

@@ -0,0 +1,18 @@
+import { execFile } from "node:child_process";
+/** Offline, bounded rootless Podman check; no runtime diagnostics enter reports or stdout. */
+export async function containerRuntimeUsable() {
+    try {
+        return await new Promise((resolve) => {
+            execFile("podman", ["info", "--format", "{{.Host.Security.Rootless}}"], {
+                shell: false,
+                encoding: "utf8",
+                timeout: 10_000,
+                killSignal: "SIGKILL",
+                maxBuffer: 4096,
+            }, (error, stdout) => resolve(error === null && stdout.trim() === "true"));
+        });
+    }
+    catch {
+        return false;
+    }
+}