pi-session-mcp 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 ## Unreleased
 
+## 0.13.0 — 2026-10-28
+
+Minor release under ADR 0003 for
+[ADR 0013](docs/adr/0013-hardened-read-only-profiles.md)
+([#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)): hardened
+read-only profiles. The MCP contract changes: read-only tools are confined to
+the workspace and the selected skills' directories, profiles gain the optional
+`shell` field, capabilities report `shell`, and `pi_session_start` has the new
+error code `sandbox_unavailable`. It also ships the writer settings changes of
+[#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162),
+[#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163),
+[#165](https://github.com/plagor44-ux/pi-session-mcp/issues/165) and
+[#166](https://github.com/plagor44-ux/pi-session-mcp/issues/166). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading follows [Installation](docs/installation.md#upgrade); writers must be
+accepted again after the upgrade, as after every release.
+
+### Changed
+
+- **Breaking for read-only workflows:** `read`, `grep`, `find` and `ls` of every
+  read-only profile now accept only paths inside the session's workspace and the
+  directories of the profile's selected skill files. An absolute path, `..`, `~`
+  or a symlink leading outside is refused with the tool error `Path is outside
+  the allowed read roots`. Read-only workers that read files outside the
+  workspace, Pi credentials included, can no longer do so. Coding profiles are
+  unchanged ([ADR 0013](docs/adr/0013-hardened-read-only-profiles.md),
+  [#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)).
+
+### Added
+
+- Optional profile field `"shell": "sandboxed"` for read-only profiles: a `bash`
+  tool whose commands run in a bubblewrap sandbox without network and with the
+  workspace as a temporary overlay, so review workers can run `git log`,
+  `git blame`, tests and scripts without touching the host tree. Linux only,
+  not together with `grantedExtensionTools`. New start error
+  `sandbox_unavailable` (class `needs_operator`), new capabilities field
+  `shell` (`none` or `sandboxed`) after `grantedExtensionTools`, and the Doctor
+  checks `sandbox_unavailable` (error, probed for each configured workspace) and
+  `workspace_git_unavailable` (warning). The sandbox's `/tmp` is limited to
+  512 MiB, commands default to a 600 second timeout and are killed with all
+  their processes on timeout or abort; the start probe is cancelled with the
+  start request. A skill directory that equals or contains the operator's home,
+  the configuration directory or `~/.pi` is no longer a read root, only its
+  skill file is
+  ([#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)).
+
+- Optional container resource settings `--cpus`, `--cpu-shares` and `--memory`,
+  with host cgroup-controller preflight and fenced in-place writer updates
+  without reprovisioning. A later mode request that omits a limit keeps it;
+  `none` removes it
+  ([#166](https://github.com/plagor44-ux/pi-session-mcp/issues/166)).
+
+- `--cache npm` mounts a private per-writer npm cache at `/pi/npm` with
+  `npm_config_cache=/pi/npm/cache`, retained across reset, finish and recreate
+  and removed with the writer
+  ([#165](https://github.com/plagor44-ux/pi-session-mcp/issues/165)).
+
+- Opt-in container setting `--clean all` removes ignored files from writer
+  clones on reset and finish while preserving the default dependency-cache
+  behavior and per-writer caches outside the clone
+  ([#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162)).
+
+### Fixed
+
+- An apply of `pi-session-mcp-setup --repo <alias> --mode container ...` with
+  drifted settings is now refused before the mode is written: each kept writer
+  with a difference reports `writer_settings_changed`, the modes file stays
+  unchanged and no kept writer is changed (a surplus writer of a smaller count
+  may already have been fenced), so the recorded mode never drifts from
+  what the writers run
+  ([#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163)).
+
 ## 0.12.1 — 2026-10-28
 
 Patch release for

package/README.md

@@ -30,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.12.1**.
+The package version is **0.13.0**.
 
 [Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 
@@ -174,6 +174,7 @@ Contract and design:
 - [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
 - [ADR 0011: turn events and controller wake](docs/adr/0011-turn-events-and-controller-wake.md)
 - [ADR 0012: one registration with a leased writer pool](docs/adr/0012-leased-writer-pool.md)
+- [ADR 0013: hardened read-only profiles](docs/adr/0013-hardened-read-only-profiles.md)
 
 Maintain:
 

package/dist/capabilities.d.ts

@@ -30,6 +30,7 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
         extensions: string[];
         grantedExtensionTools: string[];
+        shell: "none" | "sandboxed";
         skills: string[];
     }[];
 };

package/dist/capabilities.js

@@ -18,7 +18,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
         }),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, skills }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, shell, skills }) => ({
             alias,
             default: isDefault,
             permissionProfile,
@@ -27,6 +27,8 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             thinkingLevel,
             extensions: (extensions ?? []).map((extension) => extension.spec),
             grantedExtensionTools: [...(grantedExtensionTools ?? [])],
+            // Configured intent only: whether the server's probe succeeds is a start-time fact.
+            shell: shell ?? "none",
             skills: (skills ?? []).map((skill) => skill.alias),
         })),
     };

package/dist/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/dist/config.d.ts

@@ -35,6 +35,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>>;
+        shell: z.ZodOptional<z.ZodLiteral<"sandboxed">>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/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" });
     }
@@ -146,13 +159,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/dist/confined-tools.d.ts

@@ -0,0 +1,29 @@
+import { type GrepOperations, type LsOperations, type ReadOperations, type Skill, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/** Fixed refusal text; it never names the refused path. */
+export declare const OUTSIDE_ROOTS_MESSAGE = "Path is outside the allowed read roots";
+/** The read-only built-ins whose definitions this server replaces with confined ones. */
+export declare const CONFINED_TOOL_NAMES: readonly string[];
+/**
+ * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
+ * A skill directory that equals or contains a protected path (the operator's home, the configuration
+ * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ */
+export declare function allowedReadRoots(workspace: string, skills: readonly Skill[], protectedPaths?: readonly string[]): Promise<string[]>;
+/**
+ * Resolves a tool `path` argument the way the SDK will and checks the canonical result against the
+ * roots. Arguments the SDK would rewrite before resolving are refused, so both resolve the same path.
+ * Returns the canonical path; a refusal throws a fixed message without the path.
+ */
+export declare function confineToolPath(input: unknown, cwd: string, roots: readonly string[]): Promise<string>;
+/** The `*Operations` hooks that re-check every absolute path the SDK hands them; exported for tests. */
+export declare function confinedOperations(roots: readonly string[]): {
+    read: ReadOperations;
+    grep: GrepOperations;
+    ls: LsOperations;
+};
+/**
+ * Definitions named `read`, `grep`, `find` and `ls` that accept only paths below `roots`. Registered as
+ * SDK custom tools they replace the built-ins of the same name. `find` has no operations hook that
+ * would still cover `fd`, so it relies on the execute wrapper alone.
+ */
+export declare function createConfinedReadOnlyTools(cwd: string, roots: readonly string[]): ToolDefinition[];

package/dist/confined-tools.js

@@ -0,0 +1,118 @@
+import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, detectSupportedImageMimeTypeFromFile, } from "@earendil-works/pi-coding-agent";
+/** Fixed refusal text; it never names the refused path. */
+export const OUTSIDE_ROOTS_MESSAGE = "Path is outside the allowed read roots";
+/** The read-only built-ins whose definitions this server replaces with confined ones. */
+export const CONFINED_TOOL_NAMES = ["read", "grep", "find", "ls"];
+/** What the SDK's `normalizePath` would rewrite before resolving (core/tools/path-utils.js, utils/paths.js). */
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/;
+/** Real path of an existing path, or the nearest existing ancestor's real path plus the missing rest. */
+async function canonical(path) {
+    let current = resolve(path);
+    const rest = [];
+    for (;;) {
+        try {
+            return join(await realpath(current), ...rest.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            rest.push(basename(current));
+            current = parent;
+        }
+    }
+}
+function isWithin(path, root) {
+    return path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+/**
+ * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
+ * A skill directory that equals or contains a protected path (the operator's home, the configuration
+ * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ */
+export async function allowedReadRoots(workspace, skills, protectedPaths = []) {
+    const roots = new Set([await realpath(workspace)]);
+    const protectedReal = await Promise.all(protectedPaths.map((path) => canonical(path)));
+    for (const skill of skills) {
+        const directory = await realpath(dirname(skill.filePath));
+        roots.add(protectedReal.some((path) => isWithin(path, directory)) ? await realpath(skill.filePath) : directory);
+    }
+    return [...roots];
+}
+/**
+ * Resolves a tool `path` argument the way the SDK will and checks the canonical result against the
+ * roots. Arguments the SDK would rewrite before resolving are refused, so both resolve the same path.
+ * Returns the canonical path; a refusal throws a fixed message without the path.
+ */
+export async function confineToolPath(input, cwd, roots) {
+    const value = input === undefined || input === "" ? "." : input;
+    if (typeof value !== "string"
+        || value.startsWith("@") || value.startsWith("~") || value.startsWith("file:")
+        || value.includes("\0") || UNICODE_SPACES.test(value)) {
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+    }
+    const real = await canonical(resolve(cwd, value));
+    if (!roots.some((root) => isWithin(real, root)))
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+    return real;
+}
+/** The second layer: the absolute path the SDK hands to an operations hook. */
+async function checkAbsolute(path, roots) {
+    const real = await canonical(path);
+    if (!roots.some((root) => isWithin(real, root)))
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+}
+/** The `*Operations` hooks that re-check every absolute path the SDK hands them; exported for tests. */
+export function confinedOperations(roots) {
+    const guard = async (path, run) => { await checkAbsolute(path, roots); return run(); };
+    return {
+        read: {
+            access: (path) => guard(path, () => access(path, constants.R_OK)),
+            readFile: (path) => guard(path, () => readFile(path)),
+            detectImageMimeType: (path) => guard(path, () => detectSupportedImageMimeTypeFromFile(path)),
+        },
+        grep: {
+            isDirectory: (path) => guard(path, async () => (await stat(path)).isDirectory()),
+            readFile: (path) => guard(path, () => readFile(path, "utf-8")),
+        },
+        ls: {
+            exists: (path) => guard(path, async () => { try {
+                await access(path, constants.F_OK);
+                return true;
+            }
+            catch {
+                return false;
+            } }),
+            stat: (path) => guard(path, () => stat(path)),
+            readdir: (path) => guard(path, () => readdir(path)),
+        },
+    };
+}
+/** Runs the root check on `params.path` before the SDK tool executes. */
+function confine(definition, cwd, roots) {
+    return {
+        ...definition,
+        execute: async (toolCallId, params, signal, onUpdate, context) => {
+            // The SDK resolves against `ctx.cwd || cwd`; resolve the same way.
+            await confineToolPath(params.path, context?.cwd || cwd, roots);
+            return definition.execute(toolCallId, params, signal, onUpdate, context);
+        },
+    };
+}
+/**
+ * Definitions named `read`, `grep`, `find` and `ls` that accept only paths below `roots`. Registered as
+ * SDK custom tools they replace the built-ins of the same name. `find` has no operations hook that
+ * would still cover `fd`, so it relies on the execute wrapper alone.
+ */
+export function createConfinedReadOnlyTools(cwd, roots) {
+    const operations = confinedOperations(roots);
+    return [
+        confine(createReadToolDefinition(cwd, { operations: operations.read }), cwd, roots),
+        confine(createGrepToolDefinition(cwd, { operations: operations.grep }), cwd, roots),
+        confine(createFindToolDefinition(cwd), cwd, roots),
+        confine(createLsToolDefinition(cwd, { operations: operations.ls }), cwd, roots),
+    ];
+}

package/dist/doctor.d.ts

@@ -3,7 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "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";
+export type DoctorCheckId = "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";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -76,6 +76,10 @@ export interface DoctorDependencies {
     readonly writerLeaseRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
     /** Effective user id of the current process; defaults to the real one. */
     readonly uid?: number;
+    /** Probes the read-only shell sandbox with the session's fixed arguments for one workspace; called only when a profile selects it. */
+    readonly sandboxProbe?: (workspace: string) => Promise<boolean>;
+    /** The main Git directory of a linked worktree workspace, or `undefined` when the pointer is unusable. */
+    readonly worktreeGitDir?: (workspace: string) => Promise<string | undefined>;
 }
 export interface EventSpoolRootInfo {
     readonly isDirectory: boolean;

package/dist/doctor.js

@@ -3,6 +3,7 @@ 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";
@@ -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);
@@ -627,6 +630,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/dist/execution-modes.d.ts

@@ -6,9 +6,13 @@ export interface ContainerSettings {
     readonly profiles: readonly string[];
     readonly image: string;
     readonly network: "pasta" | "none";
-    readonly cache: "none" | "go" | "uv";
+    readonly cache: "none" | "go" | "uv" | "npm";
     readonly tags: "none" | "reachable";
+    readonly clean: "untracked" | "all";
     readonly base?: string;
+    readonly cpus?: number;
+    readonly cpuShares?: number;
+    readonly memory?: string;
 }
 export interface WorkspaceModeEntry {
     readonly mode: WorkspaceMode;
@@ -43,13 +47,21 @@ export declare const executionModesSchema: z.ZodObject<{
         cache: z.ZodDefault<z.ZodEnum<{
             go: "go";
             none: "none";
+            npm: "npm";
             uv: "uv";
         }>>;
         tags: z.ZodDefault<z.ZodEnum<{
             none: "none";
             reachable: "reachable";
         }>>;
+        clean: z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            untracked: "untracked";
+        }>>;
         base: z.ZodOptional<z.ZodString>;
+        cpus: z.ZodOptional<z.ZodNumber>;
+        cpuShares: z.ZodOptional<z.ZodNumber>;
+        memory: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "mode">>;
 }, z.core.$strict>;
 type ModeProfile = {

package/dist/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/dist/execution-profile.d.ts

@@ -3,6 +3,7 @@ import { type McpServers } from "./mcp-config.js";
 import type { SkillSelection } from "./skill-catalog.js";
 export declare const ALIAS_PATTERN: RegExp;
 export type PermissionProfile = "read-only" | "coding";
+export type ShellMode = "sandboxed";
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 /** A profile as it appears in the strictly validated application config. */
 export interface ConfiguredExecutionProfile {
@@ -15,6 +16,8 @@ export interface ConfiguredExecutionProfile {
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
     readonly grantedExtensionTools?: readonly string[];
+    /** `sandboxed` adds a bubblewrap-confined `bash` to a read-only profile (ADR 0013); absent means no shell. */
+    readonly shell?: ShellMode;
     /** The selected catalog skills in configured order; absent when the profile selects none. */
     readonly skills?: readonly SkillSelection[];
 }
@@ -28,6 +31,7 @@ export interface ResolvedExecutionProfile {
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
     readonly grantedExtensionTools?: readonly string[];
+    readonly shell?: ShellMode;
     readonly skills?: readonly SkillSelection[];
 }
 export declare function toResolvedExecutionProfile(profile: ConfiguredExecutionProfile): ResolvedExecutionProfile;

package/dist/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/dist/main.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { stdoutGuard } from "./stdout-guard-install.js";
-import { isAbsolute } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
 import { RoutingPiSessionAdapter, WriterRelayAdapter } from "./writer-relay.js";
 import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -47,7 +47,11 @@ async function main() {
                 spool = TurnEventSpool.open(directory, { diagnostic: writeDiagnostic });
         }
         const events = spool;
-        const hostAdapter = new SdkPiSessionAdapter({ diagnosticSink: writeDiagnostic });
+        const hostAdapter = new SdkPiSessionAdapter({
+            diagnosticSink: writeDiagnostic,
+            // The configuration directory must never become readable through a skill directory.
+            ...(process.env.PI_SESSION_MCP_CONFIG === undefined || process.env.PI_SESSION_MCP_CONFIG === "" ? {} : { protectedReadPaths: [dirname(resolve(process.env.PI_SESSION_MCP_CONFIG))] }),
+        });
         const relay = guardPath === undefined;
         const adapter = relay ? new RoutingPiSessionAdapter(hostAdapter, new WriterRelayAdapter({
             home: homedir(), workspaceModes: config.workspaceModes, executionProfiles: config.executionProfiles,

package/dist/pi-adapter.d.ts

@@ -14,7 +14,7 @@ export interface PiAppliedSelection {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
 }
-export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "extension_tool_missing" | "skill_load_failed" | "pi_session_creation_failed";
+export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "extension_tool_missing" | "skill_load_failed" | "sandbox_unavailable" | "pi_session_creation_failed";
 export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);

package/dist/pi-adapter.js

@@ -16,6 +16,7 @@ const PI_SESSION_CREATION_MESSAGES = {
     extension_tool_conflict: "Configured Pi extension tools conflict",
     extension_tool_missing: "Granted Pi extension tool is not available",
     skill_load_failed: "Configured Pi skill could not be loaded",
+    sandbox_unavailable: "Read-only shell sandbox is not available",
     pi_session_creation_failed: "Pi session creation failed",
 };
 export class PiSessionCreationError extends Error {