pi-session-mcp 0.12.1 → 0.13.1

package/dist/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/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,7 @@
 #!/usr/bin/env node
 import { stdoutGuard } from "./stdout-guard-install.js";
-import { isAbsolute } from "node:path";
+import { realpath } from "node:fs/promises";
+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 +48,14 @@ async function main() {
                 spool = TurnEventSpool.open(directory, { diagnostic: writeDiagnostic });
         }
         const events = spool;
-        const hostAdapter = new SdkPiSessionAdapter({ diagnosticSink: writeDiagnostic });
+        // The configuration directory must never become readable through a skill directory: the directory
+        // named by the variable and, for a symlinked configuration file, the directory of its target.
+        // loadConfig has read the file, so the variable is set and the path exists.
+        const configFile = resolve(process.env.PI_SESSION_MCP_CONFIG);
+        const hostAdapter = new SdkPiSessionAdapter({
+            diagnosticSink: writeDiagnostic,
+            protectedReadPaths: [dirname(configFile), dirname(await realpath(configFile))],
+        });
         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 {

package/dist/sandbox-shell.d.ts

@@ -0,0 +1,71 @@
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+/** The only bubblewrap binary the shell uses: a fixed path, never a `PATH` lookup. */
+export declare const BWRAP_PATH = "/usr/bin/bwrap";
+export declare const SANDBOX_BASH_PATH = "/usr/bin/bash";
+export declare const PROBE_TIMEOUT_MS = 5000;
+/** Seconds a command may run when the tool call names no `timeout`. */
+export declare const DEFAULT_COMMAND_TIMEOUT_SECONDS = 600;
+/** Size limit of the sandbox's tmpfs `/tmp`, in bytes (512 MiB). */
+export declare const SANDBOX_TMP_BYTES = 536870912;
+export declare const SANDBOX_UNAVAILABLE_MESSAGE = "Read-only shell sandbox is not available";
+export type RootEntry = {
+    readonly path: string;
+    readonly kind: "symlink";
+    readonly target: string;
+} | {
+    readonly path: string;
+    readonly kind: "directory";
+};
+export interface SandboxArgsInput {
+    /** Real path of the workspace, mounted at the same path as an overlay with a temporary upper layer. */
+    readonly workspace: string;
+    /** Real path of a linked worktree's main Git directory, mounted the same way. */
+    readonly gitCommonDir?: string | undefined;
+    readonly cwd: string;
+    readonly rootEntries: readonly RootEntry[];
+    /** The program and its arguments, run after `--`. */
+    readonly argv: readonly string[];
+}
+/** The complete, fixed bubblewrap argument list of ADR 0013. Pure: host facts come in as `rootEntries`. */
+export declare function sandboxArgs(input: SandboxArgsInput): string[];
+/** The host's `/bin`, `/lib`, `/lib64` and `/sbin`: a symlink is recreated, a directory bound, an absent entry skipped. */
+export declare function hostRootEntries(): RootEntry[];
+/**
+ * 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 declare function resolveWorktreeGitDir(workspace: string): Promise<string | undefined>;
+/** The part of a child process the sandbox uses; the default is `node:child_process`. */
+export interface SandboxChild {
+    readonly stdout: NodeJS.ReadableStream | null;
+    readonly stderr: NodeJS.ReadableStream | null;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    kill(signal?: NodeJS.Signals): unknown;
+}
+export type SandboxSpawn = (file: string, args: readonly string[], options: {
+    env: Record<string, never>;
+    stdio: ["ignore", "pipe", "pipe"];
+}) => SandboxChild;
+export interface SandboxDependencies {
+    readonly spawn?: SandboxSpawn;
+    /** Whether the fixed bubblewrap binary may be used; defaults to a trusted-system-binary check. */
+    readonly trusted?: () => boolean;
+    readonly rootEntries?: () => readonly RootEntry[];
+    readonly gitCommonDir?: (workspace: string) => Promise<string | undefined>;
+}
+/** Whether the fixed bubblewrap binary is a trusted system binary. */
+export declare function sandboxBinaryTrusted(dependencies?: SandboxDependencies): boolean;
+/**
+ * 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 declare function probeSandbox(workspace: string, dependencies?: SandboxDependencies, signal?: AbortSignal): Promise<boolean>;
+/**
+ * `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 declare function createSandboxedBashOperations(workspace: string, dependencies?: SandboxDependencies): BashOperations;

package/dist/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/dist/sdk-pi-adapter.d.ts

@@ -3,6 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
 import { type PiSessionAdapter, type PiSessionCreationErrorCode, type PiSessionHandle, type PiTurnOutcome } from "./pi-adapter.js";
+import { type SandboxDependencies } from "./sandbox-shell.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 type CreateSession = (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 export declare const AUTH_OPERATION_TIMEOUT_MS = 5000;
@@ -11,7 +12,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load" | "sandbox";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -39,6 +40,13 @@ export interface SdkPiSessionAdapterOptions {
     /** Resolves a pinned extension to its installed package directory. */
     readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
     readonly extensionSdk?: ExtensionSdk;
+    /** Host seams of the read-only shell sandbox; tests inject a fake runner. */
+    readonly sandbox?: SandboxDependencies;
+    /**
+     * Directories a skill directory must not expose through the read tools, in addition to the
+     * operator's home and the Pi agent directory (`~/.pi`). The server passes the configuration directory.
+     */
+    readonly protectedReadPaths?: readonly string[];
 }
 type SdkAssistantMessage = Extract<Extract<AgentSessionEvent, {
     type: "message_end";
@@ -78,6 +86,8 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
     private readonly mcpConnectionFactory;
     private readonly resolveExtension;
     private readonly extensionSdk;
+    private readonly sandbox;
+    private readonly protectedReadPaths;
     constructor(options?: SdkPiSessionAdapterOptions);
     create(input: {
         cwd: string;
@@ -85,6 +95,12 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
     private createWithExtensions;
+    /**
+     * The server's own tool definitions of a read-only session (ADR 0013); none for coding. The workspace
+     * root is the session directory: a root that cannot be resolved fails the start. With a sandboxed shell
+     * the sandbox is probed first, and a profile whose sandbox cannot start never gets a session.
+     */
+    private confinedTools;
     private loadSkills;
     private checkResources;
     /** Provider, model, authentication and availability, exactly as configured. */