pi-session-mcp 0.12.1 → 0.13.1

package/.pi-session-mcp-cli/client-adapters/mcp-verifier.js

@@ -118,7 +118,7 @@ function validCapabilities(value) {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "grantedExtensionTools", "skills"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "grantedExtensionTools", "shell", "skills"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
@@ -130,6 +130,7 @@ function validCapabilities(value) {
             && 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
+            && (record.shell === "none" || record.shell === "sandboxed")
             && 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;

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

@@ -20,6 +20,7 @@ const profileSchema = z.object({
     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(),
+    shell: z.literal("sandboxed").optional(),
     skills: z.array(alias).max(MAX_PROFILE_SKILLS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
@@ -46,6 +47,18 @@ const profileSchema = z.object({
             context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "Extension tool grants must not name built-in tools" });
         }
     }
+    if (profile.shell !== undefined) {
+        // Granted extension tools may write, so the sandbox's read-only guarantee would not hold (ADR 0013).
+        if (profile.permissionProfile !== "read-only") {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell requires a read-only profile" });
+        }
+        if (profile.grantedExtensionTools !== undefined) {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell cannot be combined with granted extension tools" });
+        }
+        if (process.platform !== "linux") {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell requires Linux" });
+        }
+    }
     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" });
     }
@@ -59,12 +72,31 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    constructor(code, locations = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
     }
 }
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -138,7 +170,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // 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 new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues));
         }
         throw error;
     }
@@ -146,13 +178,14 @@ 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, grantedExtensionTools, skills, ...value }]) => {
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, grantedExtensionTools, shell, 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]) }),
+                ...(shell === undefined ? {} : { shell }),
                 ...(selection === undefined ? {} : { skills: selection }),
             })];
     }));

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

@@ -3,11 +3,12 @@ import { constants } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { createProcessRunner } from "./setup-process.js";
+import { probeSandbox, resolveWorktreeGitDir } from "./sandbox-shell.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 { ConfigError, loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
@@ -32,7 +33,7 @@ async function readPrefix(path, maxBytes) {
     }
 }
 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", "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"];
+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", "sandbox_unavailable", "workspace_git_unavailable", "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 }); }
@@ -148,6 +149,8 @@ async function hasGitfilePointer(fs, workspace) {
         return false;
     }
 }
+/** The trusted bubblewrap binary plus a probe run through the session's fixed arguments for the workspace, its worktree Git directory included. */
+const defaultSandboxProbe = (workspace) => probeSandbox(workspace);
 async function defaultRootInfo(path) {
     try {
         const info = await lstat(path);
@@ -420,8 +423,13 @@ export async function runDoctor(dependencies = {}) {
             checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
         else if (isUnreadable(error))
             checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
-        else
-            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+        else {
+            // Locations name the offending field; an error without one, or at the root, keeps the plain subject.
+            const locations = error instanceof ConfigError ? error.locations : [];
+            for (const location of locations.length ? locations : [""]) {
+                checks.push(failure("config_invalid", location ? `configuration:${location}` : "configuration", "fix configuration using the documented schema"));
+            }
+        }
     }
     if (config) {
         for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {
@@ -627,6 +635,46 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config) {
+        const sandboxed = [...config.executionProfiles].filter(([, profile]) => profile.shell === "sandboxed").map(([alias]) => alias).sort((a, b) => a.localeCompare(b));
+        if (sandboxed.length > 0) {
+            // The overlay depends on the workspace's filesystem, so each existing workspace directory is probed.
+            for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {
+                try {
+                    if (!(await fs.stat(path)).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                let usable = false;
+                try {
+                    usable = await (dependencies.sandboxProbe ?? defaultSandboxProbe)(path);
+                }
+                catch {
+                    usable = false;
+                }
+                checks.push(usable
+                    ? ok("sandbox_unavailable", alias)
+                    : failure("sandbox_unavailable", alias, "install a bubblewrap with --overlay-src, --tmp-overlay and --disable-userns support at /usr/bin/bwrap (root-owned, not group- or world-writable) and allow unprivileged user namespaces, and keep the workspace on a filesystem that can be an overlay lower layer; see docs/installation.md"));
+            }
+            // Without a usable worktree pointer Git commands fail inside the sandbox; the read tools are unaffected.
+            for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {
+                if (!(await hasGitfilePointer(fs, path)))
+                    continue;
+                let gitDir;
+                try {
+                    gitDir = await (dependencies.worktreeGitDir ?? resolveWorktreeGitDir)(path);
+                }
+                catch {
+                    gitDir = undefined;
+                }
+                checks.push(gitDir === undefined
+                    ? warning("workspace_git_unavailable", alias, "the workspace's gitfile does not point to a linked worktree whose main Git directory is intact, so Git commands fail inside the shell sandbox")
+                    : ok("workspace_git_unavailable", alias));
+            }
+        }
+    }
     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?.());

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

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { ConfigError } from "./config.js";
 import { ImmutableMap } from "./execution-profile.js";
 import { isSafeRefName } from "./writer-boundary.js";
+import { cpusSchema, cpuSharesSchema, memorySchema } from "./writer-limits.js";
 export const EXECUTION_MODES_FILE = "execution-modes.json";
 /** Writers per container workspace; capabilities report it and setup verify checks it. */
 export const MAX_WRITERS = 16;
@@ -28,9 +29,13 @@ const entrySchema = z.discriminatedUnion("mode", [
         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"),
+        cache: z.enum(["none", "go", "uv", "npm"]).default("none"),
         tags: z.enum(["none", "reachable"]).default("none"),
+        clean: z.enum(["untracked", "all"]).default("untracked"),
         base: z.string().refine(isShortBranchName).optional(),
+        cpus: cpusSchema.optional(),
+        cpuShares: cpuSharesSchema.optional(),
+        memory: memorySchema.optional(),
     }).strict(),
 ]);
 export const executionModesSchema = z.object({
@@ -52,10 +57,13 @@ export function resolveExecutionModes(raw, workspaceAliases, profiles) {
                     throw new ConfigError("invalid_execution_modes");
                 }
             }
-            const { mode, base, ...settings } = entry;
+            const { mode, base, cpus, cpuShares, memory, ...settings } = entry;
             entries.set(alias, Object.freeze({ mode, container: Object.freeze({
                     ...settings, profiles: Object.freeze([...settings.profiles]),
                     ...(base === undefined ? {} : { base }),
+                    ...(cpus === undefined ? {} : { cpus }),
+                    ...(cpuShares === undefined ? {} : { cpuShares }),
+                    ...(memory === undefined ? {} : { memory }),
                 }) }));
         }
         else {

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

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

package/.pi-session-mcp-cli/sandbox-shell.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { lstatSync, readlinkSync } from "node:fs";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isTrustedSystemBinary } from "./setup-platform.js";
+/** The only bubblewrap binary the shell uses: a fixed path, never a `PATH` lookup. */
+export const BWRAP_PATH = "/usr/bin/bwrap";
+export const SANDBOX_BASH_PATH = "/usr/bin/bash";
+const SANDBOX_TRUE_PATH = "/usr/bin/true";
+const SANDBOX_PATH = "/usr/local/bin:/usr/bin:/bin";
+const SANDBOX_HOME = "/tmp/home";
+/** Directories of a merged-`/usr` host that the sandbox recreates as symlinks or binds read-only. */
+const ROOT_ENTRIES = ["/bin", "/lib", "/lib64", "/sbin"];
+export const PROBE_TIMEOUT_MS = 5_000;
+/** Seconds a command may run when the tool call names no `timeout`. */
+export const DEFAULT_COMMAND_TIMEOUT_SECONDS = 600;
+/** Size limit of the sandbox's tmpfs `/tmp`, in bytes (512 MiB). */
+export const SANDBOX_TMP_BYTES = 536_870_912;
+export const SANDBOX_UNAVAILABLE_MESSAGE = "Read-only shell sandbox is not available";
+const GITFILE_LIMIT_BYTES = 4096;
+/** The complete, fixed bubblewrap argument list of ADR 0013. Pure: host facts come in as `rootEntries`. */
+export function sandboxArgs(input) {
+    const args = [
+        "--unshare-all", "--unshare-user", "--disable-userns", "--die-with-parent", "--new-session", "--clearenv",
+        "--setenv", "PATH", SANDBOX_PATH, "--setenv", "HOME", SANDBOX_HOME,
+        "--ro-bind", "/usr", "/usr",
+    ];
+    for (const entry of input.rootEntries) {
+        if (entry.kind === "symlink")
+            args.push("--symlink", entry.target, entry.path);
+        else
+            args.push("--ro-bind", entry.path, entry.path);
+    }
+    args.push("--ro-bind", "/etc", "/etc", "--dev", "/dev", "--proc", "/proc", "--size", String(SANDBOX_TMP_BYTES), "--tmpfs", "/tmp", "--dir", SANDBOX_HOME, "--overlay-src", input.workspace, "--tmp-overlay", input.workspace);
+    if (input.gitCommonDir !== undefined)
+        args.push("--overlay-src", input.gitCommonDir, "--tmp-overlay", input.gitCommonDir);
+    args.push("--chdir", input.cwd, "--", ...input.argv);
+    return args;
+}
+/** The host's `/bin`, `/lib`, `/lib64` and `/sbin`: a symlink is recreated, a directory bound, an absent entry skipped. */
+export function hostRootEntries() {
+    const entries = [];
+    for (const path of ROOT_ENTRIES) {
+        try {
+            const info = lstatSync(path);
+            if (info.isSymbolicLink())
+                entries.push({ path, kind: "symlink", target: readlinkSync(path) });
+            else if (info.isDirectory())
+                entries.push({ path, kind: "directory" });
+        }
+        catch { /* absent */ }
+    }
+    return entries;
+}
+const within = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+async function readSmall(path) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > GITFILE_LIMIT_BYTES)
+            return undefined;
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+const real = async (path) => { try {
+    return await realpath(path);
+}
+catch {
+    return undefined;
+} };
+const isDirectory = async (path) => { try {
+    return (await stat(path)).isDirectory();
+}
+catch {
+    return false;
+} };
+const isFile = async (path) => { try {
+    return (await stat(path)).isFile();
+}
+catch {
+    return false;
+} };
+/**
+ * The main repository's Git directory of a linked worktree, or `undefined`. Only a `.git` regular file
+ * whose `gitdir:` names `<common>/worktrees/<name>` is accepted, and only if that directory points
+ * back at this workspace's `.git`, its `commondir` resolves to `<common>`, and `<common>` holds `HEAD`,
+ * `objects` and `refs`. Never throws on bad content.
+ */
+export async function resolveWorktreeGitDir(workspace) {
+    try {
+        const gitFile = join(workspace, ".git");
+        const content = await readSmall(gitFile);
+        const match = content === undefined ? null : /^gitdir: (.+)$/.exec(content);
+        if (!match)
+            return undefined;
+        const gitdir = await real(resolve(workspace, match[1]));
+        if (gitdir === undefined || !(await isDirectory(gitdir)))
+            return undefined;
+        const worktrees = dirname(gitdir);
+        if (basename(worktrees) !== "worktrees")
+            return undefined;
+        const common = dirname(worktrees);
+        const back = await readSmall(join(gitdir, "gitdir"));
+        if (back === undefined || (await real(resolve(gitdir, back))) !== (await real(gitFile)))
+            return undefined;
+        const commondir = await readSmall(join(gitdir, "commondir"));
+        if (commondir === undefined || (await real(resolve(gitdir, commondir))) !== common)
+            return undefined;
+        if (!(await isFile(join(common, "HEAD"))) || !(await isDirectory(join(common, "objects"))) || !(await isDirectory(join(common, "refs"))))
+            return undefined;
+        return common;
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultSpawn = (file, args, options) => spawn(file, [...args], options);
+const defaultTrusted = () => isTrustedSystemBinary(BWRAP_PATH);
+/** Whether the fixed bubblewrap binary is a trusted system binary. */
+export function sandboxBinaryTrusted(dependencies = {}) {
+    try {
+        return (dependencies.trusted ?? defaultTrusted)();
+    }
+    catch {
+        return false;
+    }
+}
+/** The complete argument list for one run; refuses when the fixed binary is not trusted. */
+async function prepare(workspace, cwd, argv, dependencies) {
+    if (!sandboxBinaryTrusted(dependencies))
+        throw new Error(SANDBOX_UNAVAILABLE_MESSAGE);
+    const gitCommonDir = await (dependencies.gitCommonDir ?? resolveWorktreeGitDir)(workspace);
+    return sandboxArgs({ workspace, gitCommonDir, cwd, rootEntries: (dependencies.rootEntries ?? hostRootEntries)(), argv });
+}
+/** Spawns bubblewrap and attaches the termination listeners in the same tick, so no event is missed. */
+function start(args, dependencies) {
+    // An empty environment: neither the server's nor the tool's variables reach the sandbox.
+    const child = (dependencies.spawn ?? defaultSpawn)(BWRAP_PATH, args, { env: {}, stdio: ["ignore", "pipe", "pipe"] });
+    const closed = new Promise((resolvePromise, reject) => {
+        child.once("error", () => reject(new Error(SANDBOX_UNAVAILABLE_MESSAGE)));
+        child.once("close", (code, signal) => resolvePromise({ code, signal }));
+    });
+    closed.catch(() => undefined);
+    return { child, closed };
+}
+/**
+ * Runs `/usr/bin/true` through the same sandbox as a command, bounded by `PROBE_TIMEOUT_MS`.
+ * False for an untrusted binary, a spawn failure, a non-zero exit or a timeout.
+ */
+export async function probeSandbox(workspace, dependencies = {}, signal) {
+    let running;
+    let timer;
+    let onAbort;
+    try {
+        if (signal?.aborted)
+            return false;
+        const workspaceReal = await realpath(workspace);
+        running = start(await prepare(workspaceReal, workspaceReal, [SANDBOX_TRUE_PATH], dependencies), dependencies);
+        const { child, closed } = running;
+        child.stdout?.resume();
+        child.stderr?.resume();
+        const deadline = new Promise((resolvePromise) => {
+            timer = setTimeout(() => resolvePromise(null), PROBE_TIMEOUT_MS);
+            onAbort = () => resolvePromise(null);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                resolvePromise(null);
+        });
+        const outcome = await Promise.race([closed, deadline]);
+        if (outcome === null)
+            child.kill("SIGKILL");
+        return outcome !== null && outcome.code === 0 && signal?.aborted !== true;
+    }
+    catch {
+        try {
+            running?.child.kill("SIGKILL");
+        }
+        catch { /* already gone */ }
+        return false;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (onAbort)
+            signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * `BashOperations` that run each command as `bwrap <fixed arguments> -- bash -c <command>`. The passed
+ * `env` is ignored, a working directory outside the workspace is refused and there is no unsandboxed
+ * fallback: a sandbox that cannot start fails the command.
+ */
+export function createSandboxedBashOperations(workspace, dependencies = {}) {
+    return {
+        exec: async (command, cwd, { onData, signal, timeout }) => {
+            if (signal?.aborted)
+                throw new Error("aborted");
+            let workspaceReal;
+            let cwdReal;
+            try {
+                workspaceReal = await realpath(workspace);
+                cwdReal = await realpath(isAbsolute(cwd) ? cwd : resolve(workspaceReal, cwd));
+            }
+            catch {
+                throw new Error("Working directory is not available");
+            }
+            if (!within(cwdReal, workspaceReal))
+                throw new Error("Working directory is outside the workspace");
+            let timeoutMs = DEFAULT_COMMAND_TIMEOUT_SECONDS * 1000;
+            if (timeout !== undefined) {
+                if (!Number.isFinite(timeout) || timeout <= 0)
+                    throw new Error("Invalid timeout: must be a finite number of seconds");
+                timeoutMs = Math.min(timeout * 1000, 2_147_483_647);
+            }
+            let running;
+            try {
+                running = start(await prepare(workspaceReal, cwdReal, [SANDBOX_BASH_PATH, "-c", command], dependencies), dependencies);
+            }
+            catch {
+                throw new Error(SANDBOX_UNAVAILABLE_MESSAGE);
+            }
+            const { child, closed } = running;
+            child.stdout?.on("data", onData);
+            child.stderr?.on("data", onData);
+            let timedOut = false;
+            let timer;
+            const kill = () => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* already gone */ } };
+            const onAbort = () => kill();
+            try {
+                timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+                signal?.addEventListener("abort", onAbort, { once: true });
+                if (signal?.aborted)
+                    kill();
+                const outcome = await closed;
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                if (timedOut)
+                    throw new Error(`timeout:${timeout ?? DEFAULT_COMMAND_TIMEOUT_SECONDS}`);
+                return { exitCode: outcome.code ?? (outcome.signal ? 128 + (osConstants.signals[outcome.signal] ?? 0) : 1) };
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}

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

@@ -2,6 +2,10 @@ export const PROFILE_TOOLS = {
     "read-only": ["read", "grep", "find", "ls"],
     coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
 };
+/** The built-in tools of a profile: a read-only profile with a sandboxed shell also has `bash`. */
+export function profileTools(permissionProfile, shell) {
+    return permissionProfile === "read-only" && shell === "sandboxed" ? [...PROFILE_TOOLS["read-only"], "bash"] : PROFILE_TOOLS[permissionProfile];
+}
 export const MAX_GRANTED_EXTENSION_TOOLS = 32;
 /**
  * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
@@ -27,7 +31,7 @@ export function isAcceptableExtensionToolName(name) {
  * 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 = []) {
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = [], shell) {
     const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
     const extensionTools = [];
     for (const names of extensionToolNames) {
@@ -41,5 +45,5 @@ export function composeSessionTools(permissionProfile, mcpToolNames, extensionTo
     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)] };
+    return { ok: true, tools: [...profileTools(permissionProfile, shell), ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
 }

package/.pi-session-mcp-cli/writer-boundary.js

@@ -35,6 +35,12 @@ export function serveArgs(paths, state, command, releaseRoot, eventsDir, options
         "-e", "PI_CODING_AGENT_DIR=/pi/agent",
         "-e", "PI_SESSION_MCP_WRITER_GUARD=/pi/config/writer-guard.json",
     ];
+    if (state.limits?.cpus !== undefined)
+        args.push(`--cpus=${state.limits.cpus}`);
+    if (state.limits?.cpuShares !== undefined)
+        args.push(`--cpu-shares=${state.limits.cpuShares}`);
+    if (state.limits?.memory !== undefined)
+        args.push(`--memory=${state.limits.memory}`);
     if (options?.name !== undefined)
         args.push("--name", writerContainerName(options.name));
     if (eventsDir !== undefined)
@@ -43,6 +49,8 @@ export function serveArgs(paths, state, command, releaseRoot, eventsDir, options
         args.push("-v", `${paths.go}:/pi/go:rw`, "-e", "GOPATH=/pi/go", "-e", "GOCACHE=/pi/go/cache", "-e", "GOTOOLCHAIN=local");
     if (state.cache === "uv")
         args.push("-v", `${paths.uv}:/pi/uv:rw`, "-e", "UV_CACHE_DIR=/pi/uv/cache", "-e", "npm_config_cache=/pi/uv/npm");
+    if (state.cache === "npm")
+        args.push("-v", `${paths.npm}:/pi/npm:rw`, "-e", "npm_config_cache=/pi/npm/cache");
     return [...args, state.imageId, ...command];
 }
 export class EventsDirectoryError extends Error {
@@ -261,6 +269,25 @@ export async function podmanInfo(runner) {
         return { usable: false };
     }
 }
+/** A failed or malformed host probe provides no usable controllers. */
+export async function podmanCgroupControllers(runner) {
+    try {
+        const output = await podman(runner, ["info", "--format", "json"]);
+        if (output.exitCode !== 0)
+            return [];
+        const info = JSON.parse(output.stdout);
+        if (!info || typeof info !== "object" || !("host" in info))
+            return [];
+        const host = info.host;
+        if (!host || typeof host !== "object" || !("cgroupControllers" in host))
+            return [];
+        const controllers = host.cgroupControllers;
+        return Array.isArray(controllers) && controllers.every((value) => typeof value === "string") ? controllers : [];
+    }
+    catch {
+        return [];
+    }
+}
 export async function resolveImage(runner, image, pull) {
     if (image !== "node" && !/^[0-9a-f]{64}$/.test(image))
         throw new BoundaryError("image_unavailable");

package/.pi-session-mcp-cli/writer-lifecycle.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, mkdir, open, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { writerLimits } from "./writer-limits.js";
 import { configSchema } from "./config.js";
 import { renderWrapper } from "./writer-wrapper.js";
 import { builtinSkillName } from "./skill-catalog.js";
@@ -220,7 +221,7 @@ async function storedConfig(paths) {
 async function sameSettings(paths, existing, settings, now) {
     const stored = await storedConfig(paths);
     return stored !== undefined && existing.imageId === now.imageId && existing.lifecycle === settings.lifecycle
-        && existing.network === settings.network && existing.cache === settings.cache && existing.tags === settings.tags
+        && existing.network === settings.network && existing.cache === settings.cache && existing.tags === settings.tags && existing.clean === settings.clean
         && JSON.stringify(existing.profiles) === JSON.stringify(settings.profiles)
         && JSON.stringify(existing.providers) === JSON.stringify(now.providers) && canonical(withoutDeliveryOff(stored)) === canonical(withoutDeliveryOff(now.config));
 }
@@ -295,12 +296,13 @@ export async function provisionWriter(ctx, input) {
         // With spool delivery the spool directory exists from provisioning on: launch would otherwise add it to the
         // writer root, a host directory the acceptance harness digests around its own first launch.
         const spool = config.events?.delivery === "spool" ? [paths.events] : [];
-        const cache = settings.cache === "go" ? [paths.go] : settings.cache === "uv" ? [paths.uv] : [];
+        const cache = settings.cache === "none" ? [] : [paths[settings.cache]];
         for (const path of [paths.root, paths.clone, paths.config, paths.agent, paths.bundles, ...spool, ...cache])
             await privateDirectory(path);
         const state = {
             schemaVersion: 1, alias: ctx.alias, index, phase: "provisioning", lifecycle: settings.lifecycle,
-            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, tags: settings.tags, imageId,
+            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, tags: settings.tags, clean: settings.clean, imageId,
+            ...(writerLimits(settings) ? { limits: writerLimits(settings) } : {}),
             base: { ref: `refs/heads/${short}`, commit },
         };
         await writeWriterState(ctx.home, name, state);
@@ -511,7 +513,7 @@ ${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/heads | while read -r re
   if [ "$ref" != "refs/heads/$2" ]; then ${BOUNDARY_GIT} update-ref -d "$ref"; fi
 done
 ${BOUNDARY_GIT} stash clear
-${BOUNDARY_GIT} clean -fd
+${BOUNDARY_GIT} clean ${state.clean === "all" ? "-ffdx" : "-fd"}
 ${identityScript(4, 5)}`;
         const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "rw", bundles: true }, script, [base.ref, base.short, base.commit, ...await operatorIdentity(ctx)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
         if (result.exitCode !== 0)

package/.pi-session-mcp-cli/writer-limits.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const cpusSchema = z.number().positive().max(1024).multipleOf(0.01);
+export const cpuSharesSchema = z.number().int().min(2).max(262144);
+export const memorySchema = z.string().regex(/^[1-9][0-9]{0,6}[mg]$/);
+export const writerLimitsSchema = z.object({
+    cpus: cpusSchema.optional(),
+    cpuShares: cpuSharesSchema.optional(),
+    memory: memorySchema.optional(),
+}).strict();
+/** Omitted settings remove previous limits; never persist an empty limits object. */
+export function writerLimits(settings) {
+    const { cpus, cpuShares, memory } = settings;
+    if (cpus === undefined && cpuShares === undefined && memory === undefined)
+        return undefined;
+    return { ...(cpus === undefined ? {} : { cpus }), ...(cpuShares === undefined ? {} : { cpuShares }), ...(memory === undefined ? {} : { memory }) };
+}
+export function sameWriterLimits(left, right) {
+    return left?.cpus === right?.cpus && left?.cpuShares === right?.cpuShares && left?.memory === right?.memory;
+}