pi-session-mcp 0.8.3 → 0.12.0

package/.pi-session-mcp-cli/doctor.js

@@ -1,14 +1,38 @@
-import { access, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { access, lstat, open, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { createProcessRunner } from "./setup-process.js";
+import { podmanInfo, isSafeRefName } from "./writer-boundary.js";
+import { containedBuiltinSkills, containedProfileRefused } from "./writer-lifecycle.js";
+import { readWriterState, writerAcceptanceCurrent, writerName, writerPaths } from "./writer-state.js";
+import { LEASE_DIRECTORY } from "./writer-lease.js";
 import { loadConfig } from "./config.js";
+import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
+import { claimsRoot, eventsRoot } from "./turn-events.js";
 import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
 import { readSkillBases, SkillBasesError } from "./skill-customize.js";
 import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory } from "./skill-library.js";
+/** Largest `.git` file Doctor inspects; a real gitfile is one short line. */
+const MAX_GITFILE_BYTES = 4096;
+/** Reads at most `maxBytes` from a regular file; a final symbolic link or a non-regular file is rejected. */
+async function readPrefix(path, maxBytes) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error("not a regular file");
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_base_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_lease_directory", "writer_not_ready", "writer_not_migrated", "writer_off_default_base", "writer_dirty", "writer_git_identity_missing", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -103,9 +127,223 @@ async function skillOverrideChecks(overrideDirectory, shippedDirectory, released
     }
     return checks;
 }
+/**
+ * True when `<workspace>/.git` is a regular file whose content starts with a `gitdir:` pointer.
+ * A gitfile does not prove a linked worktree: submodules and `git init --separate-git-dir` use
+ * one too, and telling them apart would need the pointer target, which is never followed.
+ * A symbolic link, an absent or unreadable entry, an oversized file, or any other content is not
+ * a match, so no error here can fail Doctor.
+ */
+async function hasGitfilePointer(fs, workspace) {
+    const entry = join(workspace, ".git");
+    try {
+        const info = await (fs.lstat ?? lstat)(entry);
+        if (info.isSymbolicLink() || !info.isFile() || (info.size ?? 0) > MAX_GITFILE_BYTES)
+            return false;
+        // One byte more than the cap proves the file grew after the size check.
+        const content = await (fs.readPrefix ?? readPrefix)(entry, MAX_GITFILE_BYTES + 1);
+        return Buffer.byteLength(content, "utf8") <= MAX_GITFILE_BYTES && /^gitdir:[ \t]*\S/.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultRootInfo(path) {
+    try {
+        const info = await lstat(path);
+        return { isDirectory: info.isDirectory(), uid: info.uid, mode: info.mode };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Offline check of the host-only writer lease directory. A missing directory is fine because the
+ * first lease creates it. An existing entry must be a real directory of the current user with mode
+ * 0700: the rule `acquireWriterLease` applies before it opens a lease file. Nothing is created,
+ * repaired or read, and no path or lease file name appears in the report.
+ */
+async function writerLeaseCheck(home, probe, uid) {
+    let info;
+    try {
+        info = await probe(join(home, ...LEASE_DIRECTORY));
+    }
+    catch {
+        return failure("writer_lease_directory", "writer lease", "grant access to the writer lease directory");
+    }
+    if (info === undefined)
+        return undefined;
+    // Lease files must keep their inodes: a moved or recreated directory would let a second holder in.
+    if (!info.isDirectory)
+        return failure("writer_lease_directory", "writer lease", "close every writer session and setup run, then replace the entry with a private directory owned by the current user");
+    if ((uid !== undefined && info.uid !== uid) || (info.mode & 0o7777) !== 0o700) {
+        return failure("writer_lease_directory", "writer lease", "repair the lease directory in place (owner and chmod 700); never move or delete it or its lock files");
+    }
+    return ok("writer_lease_directory", "writer lease");
+}
+/**
+ * Offline check of the event spool's runtime directories, run only when event delivery is enabled.
+ * Nothing is created or repaired, and no path appears in the report. A missing runtime directory
+ * variable is a warning because Doctor may run in a different environment than the server.
+ * The `pi-session-mcp` entry, its `events` root and its `claims` directory, when present, must be
+ * real directories of the current user without group or other access: the rule that
+ * `TurnEventSpool.open` applies to the events root and the wake hook to the claims directory.
+ * An absent entry is fine because the server creates it, so Doctor cannot be green where startup
+ * fails with `event_spool_unavailable` for these directories.
+ */
+async function eventSpoolCheck(env, probe, uid) {
+    const events = eventsRoot(env);
+    if (events === undefined)
+        return warning("event_spool_root", "event spool", "without an absolute XDG_RUNTIME_DIR in the server environment, delivery stays inactive: set it, or disable events.delivery");
+    const runtime = dirname(events);
+    const entries = [[runtime, "pi-session-mcp runtime"], [events, "events"], [claimsRoot(env) ?? join(runtime, "claims"), "claims"]];
+    for (const [path, label] of entries) {
+        let info;
+        try {
+            info = await probe(path);
+        }
+        catch {
+            return failure("event_spool_root", "event spool", `grant access to the ${label} directory`);
+        }
+        if (info === undefined) {
+            if (path === runtime)
+                break;
+            continue;
+        }
+        if (!info.isDirectory)
+            return failure("event_spool_root", "event spool", `replace the ${label} entry with a private directory owned by the current user`);
+        if (uid !== undefined && info.uid !== uid)
+            return failure("event_spool_root", "event spool", `the ${label} directory must be owned by the current user`);
+        if ((info.mode & 0o077) !== 0)
+            return failure("event_spool_root", "event spool", `remove group and other permissions from the ${label} directory (chmod 700)`);
+    }
+    return ok("event_spool_root", "event spool");
+}
+async function defaultWriterRuntime() {
+    const runner = createProcessRunner();
+    const info = await podmanInfo(runner);
+    return { ...(info.version ? { podmanVersion: info.version } : {}), imageExists: async (id) => {
+            try {
+                return (await runner.run("podman", ["image", "exists", id], AbortSignal.timeout(10_000))).exitCode === 0;
+            }
+            catch {
+                return false;
+            }
+        } };
+}
+async function writerGitIdentity(clone) {
+    try {
+        const handle = await open(join(clone, ".git", "config"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65_536)
+                return false;
+            const buffer = Buffer.alloc(65_536);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if ((await handle.stat()).size > 65_536)
+                return false;
+            let user = false, name = false, email = false;
+            for (const line of buffer.subarray(0, bytesRead).toString("utf8").split("\n")) {
+                const section = /^\s*\[([^\]]+)\]/.exec(line);
+                if (section) {
+                    user = section[1].trim().toLowerCase() === "user";
+                    continue;
+                }
+                if (!user)
+                    continue;
+                const key = /^\s*(name|email)\s*=\s*(.*?)\s*$/i.exec(line);
+                if (!key || !key[2] || /^(?:""|[#;])/.test(key[2]))
+                    continue;
+                if (key[1].toLowerCase() === "name")
+                    name = true;
+                else
+                    email = true;
+            }
+            return name && email;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+async function writerDirty(clone, state) {
+    try {
+        const git = join(clone, ".git");
+        if (!(await lstat(clone)).isDirectory() || !(await lstat(git)).isDirectory())
+            return true;
+        const bounded = async (path) => {
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const info = await handle.stat();
+                if (!info.isFile() || info.size > 65_536)
+                    throw new Error("unsafe metadata");
+                const buffer = Buffer.alloc(65_536);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if ((await handle.stat()).size > 65_536)
+                    throw new Error("oversized metadata");
+                return buffer.subarray(0, bytesRead).toString("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+        };
+        if (!isSafeRefName(state.base.ref) || !state.base.ref.startsWith("refs/heads/"))
+            return true;
+        if ((await bounded(join(git, "HEAD"))).trim() !== `ref: ${state.base.ref}`)
+            return true;
+        const refs = new Map();
+        try {
+            for (const line of (await bounded(join(git, "packed-refs"))).split("\n")) {
+                if (!line || line.startsWith("#") || line.startsWith("^"))
+                    continue;
+                const match = /^([0-9a-f]{40}|[0-9a-f]{64}) (refs\/\S+)$/.exec(line);
+                if (!match)
+                    return true;
+                if (match[2].startsWith("refs/heads/"))
+                    refs.set(match[2], match[1]);
+            }
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const walk = async (path, ref, depth = 0) => {
+            if (depth > 64 || !(await lstat(path)).isDirectory())
+                throw new Error("unsafe refs");
+            for (const entry of await readdir(path, { withFileTypes: true })) {
+                const child = join(path, entry.name), name = `${ref}/${entry.name}`;
+                if (entry.isDirectory())
+                    await walk(child, name, depth + 1);
+                else if (entry.isFile())
+                    refs.set(name, (await bounded(child)).trim());
+                else
+                    throw new Error("unsafe ref");
+            }
+        };
+        if (!(await lstat(join(git, "refs"))).isDirectory())
+            return true;
+        try {
+            await walk(join(git, "refs/heads"), "refs/heads");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        return refs.size !== 1 || refs.get(state.base.ref) !== state.base.commit;
+    }
+    catch {
+        return true;
+    }
+}
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
+    const home = dependencies.home ?? homedir();
     const checks = [];
     let metadata;
     try {
@@ -172,8 +410,9 @@ export async function runDoctor(dependencies = {}) {
             checks.push(ok("version_mismatch", "package version"));
     }
     let config;
+    const configPath = dependencies.configPath ?? process.env.PI_SESSION_MCP_CONFIG;
     try {
-        config = await (dependencies.loadConfig ?? (() => loadConfig()))();
+        config = await (dependencies.loadConfig ?? loadConfig)(configPath);
         checks.push(ok("config_invalid", "configuration"));
     }
     catch (error) {
@@ -209,6 +448,12 @@ export async function runDoctor(dependencies = {}) {
                             checks.push(failure("workspace_not_writable", alias, "grant coding workspace write access"));
                         }
                     }
+                    if (canWrite) {
+                        if (await hasGitfilePointer(fs, path))
+                            checks.push(warning("workspace_gitfile", alias, "the workspace has a gitfile pointer (possible linked worktree or Git metadata stored outside the workspace); hooks and config may be shared with another repository, so give coding workers a separate full clone"));
+                        else
+                            checks.push(ok("workspace_gitfile", alias));
+                    }
                 }
             }
             catch (error) {
@@ -217,11 +462,127 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config) {
+        const canWrite = [...config.executionProfiles.values()].some((profile) => profile.permissionProfile === "coding");
+        let runtimeUsable;
+        for (const alias of [...config.workspaces.keys()].sort((a, b) => a.localeCompare(b))) {
+            const mode = config.workspaceModes.get(alias)?.mode ?? "unset";
+            if (mode === "unset" && canWrite)
+                checks.push(warning("workspace_mode_unset", alias, "choose an explicit execution mode for the workspace"));
+            else if (mode === "host")
+                checks.push(ok("workspace_host_writes_accepted", alias));
+            else if (mode === "container") {
+                runtimeUsable ??= await (dependencies.containerRuntime ?? containerRuntimeUsable)();
+                checks.push(runtimeUsable
+                    ? ok("container_runtime_unavailable", alias)
+                    : failure("container_runtime_unavailable", alias, "make rootless Podman available or choose a different execution mode"));
+            }
+        }
+    }
+    if (config) {
+        let runtime;
+        let rawConfig, rawConfigLoaded = false, rawConfigReadable = false;
+        let availableBuiltinSkills = new Set();
+        const offDefaultBase = new Map();
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container)
+                continue;
+            checks.push(entry.container.base === undefined
+                ? warning("workspace_base_unset", alias, `record the workspace default base with pi-session-mcp-setup --repo ${alias} --base <branch> --apply`)
+                : ok("workspace_base_unset", alias));
+            if (!rawConfigLoaded) {
+                rawConfigLoaded = true;
+                try {
+                    rawConfig = await (dependencies.loadRawConfig ?? (async () => {
+                        if (!configPath)
+                            throw new Error("configuration path unavailable");
+                        return JSON.parse(await fs.readFile(configPath, "utf8"));
+                    }))();
+                    availableBuiltinSkills = containedBuiltinSkills(rawConfig, config.skillOverrideDirectory);
+                    rawConfigReadable = true;
+                }
+                catch { /* An unavailable raw configuration cannot establish profile acceptance. */ }
+            }
+            if (!rawConfigReadable) {
+                checks.push(failure("container_profile_refused", alias, "selected profiles could not be checked; restore configuration read access and rerun Doctor"));
+            }
+            else {
+                const refused = entry.container.profiles.filter((profile) => containedProfileRefused(rawConfig, profile, availableBuiltinSkills));
+                for (const profile of refused)
+                    checks.push(failure("container_profile_refused", `${alias}:${profile}`, "use a non-default coding profile without extensions or MCP grants and with only shipped, non-overridden builtin skills, or drop it from the repository's profiles"));
+                if (refused.length === 0)
+                    checks.push(ok("container_profile_refused", alias));
+            }
+            for (let index = 1; index <= entry.container.writers; index++) {
+                const name = writerName(alias, index), paths = writerPaths(home, name);
+                const remediation = `run pi-session-mcp-setup --repo ${alias} --apply, or --writer ${name} --recreate --apply`;
+                let state, ready = false;
+                try {
+                    state = await readWriterState(home, name);
+                    if (state?.phase === "ready" && state.acceptance) {
+                        runtime ??= await (dependencies.writerRuntime ?? defaultWriterRuntime)();
+                        ready = await writerAcceptanceCurrent(paths.wrapper, state, runtime);
+                    }
+                }
+                catch { /* Unreadable state or runtime is not ready. */ }
+                checks.push(ready ? ok("writer_not_ready", name) : failure("writer_not_ready", name, remediation));
+                if (!state)
+                    continue;
+                checks.push(state.launch === "relay" ? ok("writer_not_migrated", name)
+                    : warning("writer_not_migrated", name, `run pi-session-mcp-setup --repo ${alias} --apply to migrate the writer to the relay`));
+                if (entry.container.base !== undefined && ready && state.base.ref !== `refs/heads/${entry.container.base}`) {
+                    offDefaultBase.set(alias, (offDefaultBase.get(alias) ?? 0) + 1);
+                }
+                checks.push(await writerDirty(paths.clone, state)
+                    ? warning("writer_dirty", name, "collect writer work before resetting or recreating the writer") : ok("writer_dirty", name));
+                let bundles = false;
+                try {
+                    if (!(await lstat(paths.bundles)).isDirectory())
+                        bundles = true;
+                    else
+                        bundles = (await readdir(paths.bundles)).some((file) => file !== "base.bundle");
+                }
+                catch (error) {
+                    bundles = !isMissing(error);
+                }
+                checks.push(await writerGitIdentity(paths.clone) ? ok("writer_git_identity_missing", name)
+                    : warning("writer_git_identity_missing", name, "set user.name and user.email in the operator checkout, then reset the writer"));
+                checks.push(bundles ? warning("writer_uncollected_bundle", name, "collect or review outstanding writer bundles") : ok("writer_uncollected_bundle", name));
+            }
+        }
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container || entry.container.base === undefined)
+                continue;
+            const count = offDefaultBase.get(alias) ?? 0;
+            checks.push(count === 0 ? ok("writer_off_default_base", alias)
+                : warning("writer_off_default_base", alias, `${count} ${count === 1 ? "writer is" : "writers are"} off the workspace default base; finish each with pi-session-mcp-setup --writer <name> --finish --apply once its work is collected`));
+        }
+    }
+    if (config) {
+        // This advisory check needs positive evidence, like the gitfile check: unreadable or
+        // malformed optional settings are ignored, while installed-manifest checks still run.
+        const unpinned = new Set();
+        if ([...config.executionProfiles.values()].some((profile) => profile.extensions?.length)) {
+            try {
+                // Load the SDK only here, like the extension resolver, so a broken install cannot stop Doctor from loading.
+                const agentDir = dependencies.agentDir ?? (await import("@earendil-works/pi-coding-agent")).getAgentDir();
+                const settings = JSON.parse((await fs.readFile(join(agentDir, "settings.json"), "utf8")).replace(/^\uFEFF/, ""));
+                if (typeof settings === "object" && settings !== null && "packages" in settings && Array.isArray(settings.packages)) {
+                    for (const entry of settings.packages) {
+                        const source = typeof entry === "object" && entry !== null && "source" in entry ? entry.source : entry;
+                        if (typeof source === "string")
+                            unpinned.add(source);
+                    }
+                }
+            }
+            catch { /* Optional settings cannot establish an unpinned entry. */ }
+        }
         const resolveExtension = dependencies.resolveExtension
             ?? (async (extension) => (await import("./pi-extensions.js")).resolvePiExtension(extension));
         for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
             for (const extension of profile.extensions ?? []) {
                 const subject = `${alias}:${extension.name}`;
+                if (unpinned.has(`npm:${extension.name}`))
+                    checks.push(warning("extension_unpinned", subject, `pin it with pi install npm:${extension.name}@${extension.version}`));
                 try {
                     await resolveExtension(extension);
                     checks.push(ok("extension_missing", subject), ok("extension_version_mismatch", subject));
@@ -266,6 +627,11 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config?.eventDelivery === "spool")
+        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.()));
+    const lease = await writerLeaseCheck(home, dependencies.writerLeaseRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.());
+    if (lease)
+        checks.push(lease);
     if (config)
         checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));

package/.pi-session-mcp-cli/execution-modes.js

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { ConfigError } from "./config.js";
+import { ImmutableMap } from "./execution-profile.js";
+import { isSafeRefName } from "./writer-boundary.js";
+export const EXECUTION_MODES_FILE = "execution-modes.json";
+/** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
+export function isShortBranchName(value) {
+    return value.length <= 200
+        && isSafeRefName(value)
+        && value !== "HEAD"
+        && !value.startsWith("refs/")
+        && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
+}
+export function executionModesPath(configPath) {
+    return join(dirname(configPath), EXECUTION_MODES_FILE);
+}
+const entrySchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("host"), acceptHostWrites: z.literal(true) }).strict(),
+    z.object({ mode: z.literal("read-only") }).strict(),
+    z.object({
+        mode: z.literal("container"),
+        writers: z.number().int().min(1).max(16).default(1),
+        lifecycle: z.enum(["persistent", "ephemeral"]).default("persistent"),
+        profiles: z.array(z.string()).min(1),
+        image: z.union([z.literal("node"), z.string().regex(/^[0-9a-f]{64}$/)]).default("node"),
+        network: z.enum(["pasta", "none"]).default("pasta"),
+        cache: z.enum(["none", "go", "uv"]).default("none"),
+        tags: z.enum(["none", "reachable"]).default("none"),
+        base: z.string().refine(isShortBranchName).optional(),
+    }).strict(),
+]);
+export const executionModesSchema = z.object({
+    schemaVersion: z.literal(1),
+    workspaces: z.record(z.string(), entrySchema),
+}).strict();
+export function resolveExecutionModes(raw, workspaceAliases, profiles) {
+    const parsed = executionModesSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new ConfigError("invalid_execution_modes");
+    const entries = new Map();
+    for (const [alias, entry] of Object.entries(parsed.data.workspaces)) {
+        if (!workspaceAliases.has(alias))
+            throw new ConfigError("invalid_execution_modes");
+        if (entry.mode === "container") {
+            for (const profileAlias of entry.profiles) {
+                const profile = profiles.get(profileAlias);
+                if (profile?.permissionProfile !== "coding" || profile.provider === "cursor") {
+                    throw new ConfigError("invalid_execution_modes");
+                }
+            }
+            const { mode, base, ...settings } = entry;
+            entries.set(alias, Object.freeze({ mode, container: Object.freeze({
+                    ...settings, profiles: Object.freeze([...settings.profiles]),
+                    ...(base === undefined ? {} : { base }),
+                }) }));
+        }
+        else {
+            entries.set(alias, Object.freeze({ mode: entry.mode }));
+        }
+    }
+    return new ImmutableMap([...workspaceAliases].map((alias) => [alias, entries.get(alias) ?? Object.freeze({ mode: "unset" })]));
+}
+export async function loadExecutionModes(configPath, workspaceAliases, profiles) {
+    let raw;
+    try {
+        const bytes = await readFile(executionModesPath(configPath), "utf8");
+        raw = JSON.parse(bytes);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            raw = { schemaVersion: 1, workspaces: {} };
+        }
+        else {
+            throw new ConfigError("invalid_execution_modes");
+        }
+    }
+    return resolveExecutionModes(raw, workspaceAliases, profiles);
+}
+export function codingAllowed(entry, relay) {
+    return entry.mode === "unset" || entry.mode === "host" || (entry.mode === "container" && relay);
+}

package/.pi-session-mcp-cli/execution-profile.js

@@ -9,6 +9,7 @@ export function toResolvedExecutionProfile(profile) {
         thinkingLevel: profile.thinkingLevel,
         ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
         ...(profile.extensions === undefined ? {} : { extensions: profile.extensions }),
+        ...(profile.grantedExtensionTools === undefined ? {} : { grantedExtensionTools: Object.freeze([...profile.grantedExtensionTools]) }),
         ...(profile.skills === undefined ? {} : { skills: profile.skills }),
     });
 }

package/.pi-session-mcp-cli/override-lock.js

@@ -72,7 +72,7 @@ export async function acquireOverrideLock(overrideDirectory, options = {}) {
         },
     };
 }
-function flockBinary(options) {
+export function flockBinary(options) {
     const trusted = options.isTrustedBinary ?? ((path) => isTrustedSystemBinary(path));
     return (options.flockCandidates ?? FLOCK_CANDIDATES).find((candidate) => trusted(candidate));
 }
@@ -86,7 +86,7 @@ async function openLockFile(lockPath, platform, timeoutMs, signal) {
         throw new OverrideLockError(error.message === "ownership_lock_busy" ? "override_lock_busy" : "override_lock_unavailable");
     }
 }
-function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
+export function lockWithFlock(flockPath, lockFd, timeoutMs, signal, nonBlocking = false) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -97,7 +97,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             // flock parses fractional seconds with the locale's decimal separator, so only whole
             // seconds go on the command line. The exact bound is the timer below, which stops flock.
             const wholeSeconds = String(Math.max(1, Math.ceil(timeoutMs / 1_000)));
-            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), "-w", wholeSeconds, "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
+            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), ...(nonBlocking ? ["-n"] : ["-w", wholeSeconds]), "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
         }
         catch {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -111,7 +111,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             catch { /* already gone */ }
         } };
         const cleanup = () => { clearTimeout(bound); signal?.removeEventListener("abort", stop); };
-        const bound = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+        const bound = nonBlocking ? undefined : setTimeout(() => { expired = true; stop(); }, timeoutMs);
         signal?.addEventListener("abort", stop, { once: true });
         locker.once("error", () => { cleanup(); reject(new OverrideLockError("override_lock_unavailable")); });
         locker.once("close", (code) => {

package/.pi-session-mcp-cli/session-tools.js

@@ -0,0 +1,45 @@
+export const PROFILE_TOOLS = {
+    "read-only": ["read", "grep", "find", "ls"],
+    coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
+};
+export const MAX_GRANTED_EXTENSION_TOOLS = 32;
+/**
+ * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
+ * function-name limit `^[a-zA-Z0-9_-]{1,64}$`. The SDK reads `*` in an allowlist as a glob
+ * and a leading `+` or `-` as a modifier, so the first character may not be `-`.
+ */
+const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
+/**
+ * These mirror `isMcpToolName` of Pi SDK 1.4.0 (core/mcp-servers.js), which is not a root
+ * export. When the allowlist names no `mcp__` entry, the SDK's `_isAllowedTool` keeps such
+ * tools outside the allowlist for codemode and tool_search, so an extension tool with one
+ * of these names could be active without being granted. This server's own MCP bridge
+ * tools are named `mcp_<server>_<tool>` with a single underscore, so they never collide.
+ */
+const MCP_RESERVED_PREFIX = "mcp__";
+const MCP_RESERVED_NAMES = new Set(["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+export function isAcceptableExtensionToolName(name) {
+    return EXTENSION_TOOL_NAME.test(name) && !name.startsWith(MCP_RESERVED_PREFIX) && !MCP_RESERVED_NAMES.has(name);
+}
+/**
+ * The tool allowlist of a session. Read-only activates exactly the granted extension
+ * names; coding activates all registered extension tools. Conflicts are checked first
+ * in both profiles so an extension can never shadow a built-in or granted MCP tool.
+ * Unsafe names and names the SDK treats as MCP tools also fail closed.
+ */
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = []) {
+    const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
+    const extensionTools = [];
+    for (const names of extensionToolNames) {
+        for (const name of names) {
+            if (!isAcceptableExtensionToolName(name) || reserved.has(name))
+                return { ok: false, code: "extension_tool_conflict" };
+            reserved.add(name);
+            extensionTools.push(name);
+        }
+    }
+    if (permissionProfile === "read-only" && grantedExtensionTools.some((name) => !extensionTools.includes(name))) {
+        return { ok: false, code: "extension_tool_missing" };
+    }
+    return { ok: true, tools: [...PROFILE_TOOLS[permissionProfile], ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
+}