pi-session-mcp 0.12.1 → 0.13.0

package/docs/adr/0013-hardened-read-only-profiles.md

@@ -0,0 +1,182 @@
+# ADR 0013: Hardened read-only profiles
+
+**Status:** Accepted (2026-10-28). Amends
+[ADR 0006](0006-pi-extension-allowlist.md) and
+[ADR 0010](0010-read-only-extension-tools.md). Issue #169.
+
+## Context
+
+Read-only profiles have `read`, `grep`, `find` and `ls` and no shell. Review
+workers cannot run `git log`, `git blame`, a test file or a short script, and
+read more files instead.
+
+Read-only sessions run in the host server process. The SDK's read tools accept
+absolute paths, `..`, `~` and symlinks, so a read-only worker can read every
+file the operator can read, including Pi credentials outside the workspace.
+Today only the absence of a network path keeps that content local. A granted
+research tool with free-form input (search, documentation lookup) would give a
+prompt-injected worker a channel to send it out.
+
+## Decision
+
+### 1. Workspace-confined read tools for every read-only profile
+
+`read`, `grep`, `find` and `ls` of **every** read-only profile accept only
+paths inside the allowed read roots:
+
+- the session's workspace root, and
+- the directory of each selected skill file, because the model loads skills
+  with `read` and they live outside the workspace. If that directory equals or
+  contains the operator's home directory, the configuration file's directory
+  or the Pi agent directory (`~/.pi`), only the skill file itself is a root,
+  so a catalog entry such as `./SKILL.md` next to the configuration does not
+  expose the configuration.
+
+The server replaces the SDK's built-in definitions with definitions built from
+the root exports `createReadToolDefinition`, `createGrepToolDefinition`,
+`createFindToolDefinition` and `createLsToolDefinition`, registered under the
+same names as SDK custom tools. Two layers check each call:
+
+1. Before the SDK tool runs, the `path` argument is resolved against the
+   session directory and canonicalized with `realpath` (for a path that does
+   not exist yet, the nearest existing ancestor plus the remaining segments).
+   It must equal an allowed root or lie below one. Arguments the SDK would
+   rewrite before resolving (a leading `@` or `~`, a `file:` URL, Unicode
+   spaces, NUL) are refused, so this check and the SDK always resolve the
+   same path.
+2. The `*Operations` hooks of `read`, `grep` and `ls` check the absolute path
+   the SDK hands them again. This also covers `read`'s file-name variants and
+   symlinks met during reading.
+
+`grep` and `find` start `rg` and `fd` on the checked path. Neither follows
+symlinks during traversal by default, so a symlink below the workspace does not
+lead out of it. A refusal is an ordinary tool error,
+`Path is outside the allowed read roots`, without the path.
+
+At admission the server checks with `getToolDefinition` that each of these
+names resolves to the server's own definition; otherwise the start fails with
+`pi_session_creation_failed`.
+
+The confinement is always on; there is no configuration field. Reading outside
+the workspace has no review use, and a per-profile switch would invite the
+unconfined variant for exactly the profiles that get external tools.
+
+### 2. Sandboxed shell, opt-in per profile
+
+The optional profile field `shell` takes the single value `"sandboxed"`. It is
+allowed only on `read-only` profiles, not together with
+`grantedExtensionTools` (granted extension tools may write, so the shell's
+read-only guarantee would not hold), and only on Linux; any other combination
+fails config validation with `invalid_execution_profile_config`.
+
+Such a profile also gets `bash`, built with `createBashToolDefinition(cwd,
+{ operations, exposeSessionEnvironment: false })` and a custom
+`BashOperations.exec`. Each command runs as
+`/usr/bin/bwrap <fixed arguments> -- /usr/bin/bash -c <command>`:
+
+- `--unshare-all` (no network), `--unshare-user` (which bubblewrap requires
+  for `--disable-userns`), `--disable-userns`, `--die-with-parent`,
+  `--new-session`, `--clearenv` with
+  `PATH=/usr/local/bin:/usr/bin:/bin` and `HOME=/tmp/home`;
+- `/usr` and `/etc` read-only; `/bin`, `/lib`, `/lib64` and `/sbin` recreated
+  as the host's merged-`/usr` symlinks or bound read-only; `--dev /dev`,
+  `--proc /proc`, a tmpfs `/tmp` limited to 512 MiB; no other host path, so the operator's home
+  is not visible;
+- the workspace at its host path as an overlay with a temporary upper layer
+  (`--overlay-src <workspace> --tmp-overlay <workspace>`): writes succeed
+  inside the sandbox and vanish when the command ends;
+- for a linked worktree (a `.git` file instead of a directory), the main
+  repository's Git directory as a second temporary overlay at its host path,
+  so `git log` and `git blame` work. The server accepts the pointer only if
+  `gitdir:` names `<common>/worktrees/<name>`, that directory's `gitdir` file
+  points back to the workspace's `.git`, its `commondir` resolves to
+  `<common>`, and `<common>` holds `HEAD`, `objects` and `refs`. Otherwise
+  nothing extra is bound and Git commands fail inside the sandbox. The read
+  tools stay confined to the workspace either way.
+
+A command without a `timeout` argument gets a default of 600 seconds; on
+timeout or abort the server kills bubblewrap, and the PID namespace takes every
+process of the sandbox with it.
+
+The bubblewrap path is fixed and must be a trusted system binary (root-owned,
+not group- or world-writable); there is no `PATH` lookup. The tool's own
+environment, the controller's environment and `PI_*` session variables never
+reach the command.
+
+Fail closed: before a session with `shell: "sandboxed"` starts, the server runs
+`/usr/bin/true` through the same sandbox for the session's workspace, bounded
+and cancelled with the start request. If the binary is untrusted or the probe
+fails, `pi_session_start` fails with the new code `sandbox_unavailable`, class
+`needs_operator`. A command whose sandbox cannot start fails as that command;
+there is never an unsandboxed fallback.
+
+### 3. Research tools
+
+There is no new mechanism. Operators grant them through the existing
+per-profile `mcpServers` with `readOnly: true`. The documentation advises
+query-style tools over free URL fetching. Now that every read-only profile is
+confined, granting research tools to read-only profiles no longer exposes files
+outside the workspace and the skill directories.
+
+### Doctor and capabilities
+
+Doctor stays offline. When any profile has `shell: "sandboxed"`, it probes
+each configured workspace with the session's fixed arguments, including a
+linked worktree's main Git directory, and reports `sandbox_unavailable` as an
+error when the trusted bubblewrap binary is missing or a probe fails, for
+example because the installed version lacks the overlay options, unprivileged
+user namespaces are disabled or restricted by AppArmor (see
+[ADR 0008](0008-coding-profile-isolation.md)), or the workspace's filesystem
+cannot be an overlay lower layer. For each
+workspace with an unusable gitfile pointer, it warns with
+`workspace_git_unavailable` when any profile has a sandboxed shell.
+
+Capabilities expose `shell` (`"none"` or `"sandboxed"`) for every profile,
+directly after `grantedExtensionTools`. This is configured intent only.
+
+## Amendments
+
+- ADR 0006: read-only profiles have `read`, `grep`, `find` and `ls`, and
+  additionally `bash` with `shell: "sandboxed"`. The read tools are
+  workspace-confined.
+- ADR 0010: the active tools of a read-only profile are the above, the granted
+  MCP tools and the granted extension tools. A profile with granted extension
+  tools cannot have a sandboxed shell.
+
+## Contract change and versioning
+
+The capabilities field `shell`, the start error `sandbox_unavailable` and the
+confinement of existing read-only profiles change the public contract and need
+minor release **0.13.0** under
+[ADR 0003](0003-post-mvp-maintenance.md#versioning). The confinement breaks
+read-only workflows that read files outside the workspace. This decision does
+not itself bump the version or authorize publication.
+
+## Consequences
+
+- Read-only workers can run Git, tests and scripts without touching the host
+  tree or the network.
+- The sandbox shows only `/usr`, `/etc` and the workspace. Toolchains under the
+  home directory or `/opt` (nvm, `~/.local`) are not available; Node.js and Git
+  from the distribution are.
+- Lock-dependent tests that need a supported local filesystem can fail on the
+  overlay (seen with `test/setup-modes.test.ts` in the #169 probe).
+- The sandbox has no memory, process-count or overlay upper-layer limits.
+  A prompt-injected worker can exhaust memory or processes of the operator's
+  user until the command times out, as a host-mode coding session already
+  can. Limits through a cgroup scope are a possible follow-up.
+- When `bash` truncates long output, the SDK stores the full output in the
+  host's temporary directory and names that file. Confined `read` refuses it
+  and the sandbox's `/tmp` is a fresh tmpfs, so only the truncated output is
+  available; workers should narrow their commands instead.
+- `ls` omits entries that are symlinks pointing outside the read roots,
+  without a notice.
+- The confinement checks a path when the call starts. A concurrent writer in
+  the same workspace, for example a host-mode coding session, could swap a
+  checked directory for a symlink before `rg` or `fd` opens it. Read-only
+  workers cannot create such symlinks themselves.
+- Extension hooks and granted extension tools keep running in the server
+  process with the operator's rights (ADR 0006/0010); confinement covers the
+  built-in tools only.
+- macOS, a VM backend and network allowlists inside the sandbox are out of
+  scope. Coding profiles are unchanged (ADR 0008/0009).

package/docs/doctor-design.md

@@ -52,6 +52,8 @@ and owners are:
 | `skill_unreadable` | A selected skill path is not a regular file, is larger than 256 KiB, or cannot be read | `<profile>:<skill-alias>` |
 | `skill_duplicate` | Two selected skill aliases of one profile resolve to the same canonical file | `<profile>:<skill-alias>` |
 | `skill_override_outdated` | Warning. The current fingerprint of a shipped skill differs from the base recorded in the skill bases file next to the configuration file, or the bases file is corrupt | `skill:<name>`, or `skill:bases` for a corrupt file |
+| `sandbox_unavailable` | Only when some profile has `shell: "sandboxed"` ([ADR 0013](adr/0013-hardened-read-only-profiles.md)). Error: `/usr/bin/bwrap` is missing or not a trusted system binary (root-owned, not group- or world-writable), or a probe run of `/usr/bin/true` through the session's fixed sandbox arguments for a configured workspace (its real path, plus the main Git directory of a linked worktree) fails or exceeds 5 seconds, for example because the installed version lacks the overlay options, unprivileged user namespaces are disabled or restricted by AppArmor, or the workspace's filesystem cannot be an overlay lower layer. Reported once per workspace that exists as a directory, however many profiles select the shell | workspace alias |
+| `workspace_git_unavailable` | Only when some profile has `shell: "sandboxed"`. Warning: a workspace's `.git` is a regular file starting with `gitdir:` that is not a usable linked-worktree pointer (`<common>/worktrees/<name>` with a matching back-pointer and `commondir`, and `HEAD`, `objects` and `refs` in `<common>`), so Git commands fail inside the sandbox; the read tools are unaffected. `ok` for a usable pointer; absent for a workspace without a gitfile | workspace alias |
 | `event_spool_root` | Only when `events.delivery` is `spool`. Warning: no absolute `XDG_RUNTIME_DIR` is set in Doctor's environment; a server started that way runs with delivery inactive. Error: the `pi-session-mcp` entry in the runtime directory, or its `events` or `claims` entry, cannot be inspected, is not a directory (a link counts), belongs to another user, or has group or other permission bits. An absent entry is `ok`: the server creates it | `event spool` |
 
 `workspace_gitfile` is advice, not a boundary. A linked Git worktree shares `hooks/` and `config` with its main repository, so a coding worker could plant code that runs in the operator's later Git commands. A `.git` gitfile alone does not prove a linked worktree, however: submodules and `git init --separate-git-dir` use gitfiles too, and the content of the three is indistinguishable without following the pointer. Doctor therefore never follows, resolves, stats or reads the pointer target and never runs Git. It calls `lstat` on `<workspace>/.git` and, for a regular file of at most 4 KiB, reads at most that many bytes (without following a symbolic link) and checks for a `gitdir:` prefix followed by a non-blank value. Every such file warns, including submodule and separate-git-dir gitfiles, with a fixed path-free remediation that says "possible linked worktree or Git metadata stored outside the workspace" and recommends a separate full clone for coding workers. The check runs only when a coding profile exists and emits one entry per workspace alias: a warning, or `ok` when no gitfile pointer was found. A `.git` directory, an absent `.git`, an empty, oversized or malformed file, a symbolic link named `.git` (not followed, so nothing is known about its target), and any `lstat` or read error (for example `EACCES`) produce `ok`, never a failure and never a crash; an unreadable `.git` therefore means "not detected", not "verified clean". The warning cannot mask an error: the exit code stays 2 whenever any error exists.

package/docs/execution-modes.md

@@ -86,7 +86,11 @@ clone.
 | `--image <value>` | `node` (default, built-in digest pin) or an existing local 64-character lowercase hex image ID; no arbitrary tags |
 | `--network <value>` | `pasta` (default, not limited) or `none` |
 | `--tags <value>` | `none` (default), or `reachable` for the tags reachable from the selected base commit |
-| `--cache <value>` | `none` (default), `go` for the writer's Go module/build cache, or `uv` for its private uv and npm cache |
+| `--clean <untracked\|all>` | `untracked` (default) keeps ignored files; `all` also removes ignored files on reset and finish |
+| `--cpus <n>` | Hard CPU cap, > 0 through 1024, at most two decimals; `none` removes it; unlimited unless set |
+| `--cpu-shares <n>` | Relative CPU weight under contention, integer 2–262144; `none` removes it; Podman default 1024 |
+| `--memory <size>` | Hard memory cap, 1–9999999 plus lowercase `m` or `g`; `none` removes it; unlimited unless set |
+| `--cache <value>` | `none` (default), `go` for the writer's Go module/build cache, `uv` for its private uv and npm cache, or `npm` for its private npm-only cache |
 | `--base <ref>` | Named local or remote branch for provisioning; also supported by writer reset; not HEAD or a raw commit hash |
 | `--client codex` | No writer effect; coding uses the host registration for either client |
 | `--discard` | Explicitly allow loss of uncollected surplus writers on mode/count changes |
@@ -194,7 +198,7 @@ unexported work. Do not blindly retry or bypass a refusal by changing profiles.
 | Writer operation | Behavior |
 | --- | --- |
 | `--collect --apply` | Bundle export; retain clone |
-| `--reset --apply [--base <ref>]` | Reset to current source base branch, delete extra branches/stash and clean untracked files; falls back to recreation if post-reset verification fails |
+| `--reset --apply [--base <ref>]` | Reset to current source base branch, delete extra branches/stash and clean untracked files, and ignored files with `--clean all`; falls back to recreation if post-reset verification fails |
 | `--recreate --apply` | Rebuild clone and agent copy from the workspace default base, retaining image/settings |
 | `--finish --apply` | Collect, then reset persistent / recreate ephemeral on the workspace default base |
 | `--remove` | Explicit mutation: unregister owned registrations before removing writer state |
@@ -255,6 +259,9 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `usage_invalid` | Invalid writer name or argument combination |
 | `doctor_failed` | Relevant blocking Doctor checks failed; repository steps and mutating writer operations also report each blocking check as a separate failed finding with its Doctor check id and target `client: "doctor"`, `scope: "check"`, and as alias the profile or workspace alias that leads the check's subject (the part before `:`, and for a writer name its alias), or `"invalid"` for a global check or when that is not a valid alias |
 | `writer_planned` | Writer would be retained/provisioned |
+| `writer_limits_update_planned` | Existing writer limits would be updated without reprovisioning |
+| `writer_limits_updated` | Existing writer limits updated under its fence |
+| `cgroup_controller_unavailable` | Requested CPU or memory controller is unavailable; mode was not written |
 | `writer_remove_planned` | Surplus writer would be removed |
 | `writer_collect_planned` | Collection planned only |
 | `writer_reset_planned` | Reset planned only |
@@ -262,7 +269,7 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `writer_finish_planned` | Finish planned only |
 | `writer_provisioned` | Clone/config/wrapper prepared, not yet accepted |
 | `writer_unchanged` | Provisioned settings already match |
-| `writer_settings_changed` | Existing writer settings or its rendered configuration differ from the current ones; no silent replacement, no acceptance and no registration change ([Isolation setup](isolation-setup.md)) |
+| `writer_settings_changed` | Existing writer settings or its rendered configuration differ from the current ones; no silent replacement, no acceptance and no registration change, and an apply is refused before the mode is written ([Isolation setup](isolation-setup.md)) |
 | `registration_divergent` | Writer registration is foreign or differs from its ownership record; it is retained and the writer stays in legacy launch mode |
 | `writer_reconcile_failed` | Unexpected reconciliation failure |
 | `writer_operation_failed` | Unclassified lifecycle/orchestrator failure |
@@ -375,6 +382,43 @@ No other uv or npm variables are set, so download and network policy stay the
 image's. The directory is per writer: it is never shared between writers and
 never a host cache mount. Setup does not install uv or npm for you.
 
+### Resource limits
+
+Container writers are unlimited by default. Optional `--cpus <n>` sets a hard
+CPU cap (greater than 0, at most 1024, with at most two decimals).
+`--cpu-shares <n>` sets relative CPU weight under contention (integer 2–262144;
+Podman's default is 1024). The weight only counts against sibling cgroups:
+rootless writers run in the operator's user slice, so `--cpu-shares` makes a
+writer yield to the operator's other containers and processes, not to system
+services such as rootful Docker CI runners in `system.slice`. To protect such
+a service, use the `--cpus` hard cap.
+`--memory <size>` sets a hard memory cap: 1–9999999 followed by lowercase `m`
+or `g`, for example `--memory 512m`.
+
+These are fairness measures, not a security boundary. Setup checks that the
+Podman host exposes the `cpu` controller for either CPU option and the
+`memory` controller for memory; missing controllers refuse the mode change
+with `cgroup_controller_unavailable`, including dry-runs. Limits apply to the
+serving container, not throwaway clone/maintenance containers. They update
+existing writer state under its lease without reprovisioning or changing
+boundary acceptance, and take effect at the writer's next launch. Acceptance
+and `--writer <name> --verify` run the serving container under the same
+limits, so a very small cap can make them time out. Unlike the other
+settings, a later mode request that omits a limit flag keeps the recorded
+limit, because limits are outside the settings drift check and would
+otherwise vanish without an error, for example in an upgrade's repeated
+provisioning command. Pass `--cpus none`, `--cpu-shares none` or
+`--memory none` to remove a limit.
+
+### npm cache (opt-in)
+
+For a Node writer, pass `--cache npm` to mount a private per-writer directory
+at `/pi/npm` with `npm_config_cache=/pi/npm/cache`. This records `cache: "npm"`;
+no other npm variables are set and setup does not install npm. The directory
+is never shared between writers or mounted from a host package cache. It
+survives reset, finish and recreate, and is removed with the writer. Repeat
+`--cache npm` on later container mode requests to retain it.
+
 ### Base tags (opt-in)
 
 Container writers default to `tags: "none"`. Pass `--tags reachable` to bundle
@@ -384,5 +428,17 @@ importing the selected base tags; tags created by workers are never collected
 and do not change the collected-work digest. Changing the tag setting requires
 reprovisioning for settings drift, but does not change boundary acceptance.
 
+### Ignored files (opt-in)
+
+Container writers default to `clean: "untracked"`, keeping ignored files such as
+`.venv`, `node_modules`, `.env` and build output across reset and a persistent
+writer's finish (an ephemeral writer's finish recreates the clone). Pass
+`--clean all` on a container mode request to remove them with `git clean -ffdx`.
+Repeat this flag on later mode requests to retain it. Per-writer caches at
+`/pi/go`, `/pi/uv` and `/pi/npm` live outside the clone and stay untouched.
+Changing the setting requires reprovisioning for settings drift: collect work,
+run `--writer <name> --remove`, then run the provisioning command again with
+the desired `--clean` value. It does not change boundary acceptance.
+
 See [Isolation setup](isolation-setup.md) for boundary prerequisites and what
 setup automates, and the historical manual acceptance evidence linked there.

package/docs/installation.md

@@ -58,6 +58,20 @@ the same arguments.
   `~/.local/state/pi-session-mcp` on the same filesystem type as `/`, which is
   APFS. A home directory on HFS+, exFAT, a network volume or any other
   filesystem fails closed.
+- Optional, Linux only, for the sandboxed shell of a read-only profile
+  (`"shell": "sandboxed"`, [ADR 0013](adr/0013-hardened-read-only-profiles.md)):
+  [bubblewrap](https://github.com/containers/bubblewrap) at `/usr/bin/bwrap`,
+  root-owned and not group- or world-writable, with the options
+  `--overlay-src`, `--tmp-overlay` and `--disable-userns`. It runs unprivileged and
+  needs unprivileged user namespaces (kernel setting, and on some distributions an
+  AppArmor profile that allows the user namespace for `bwrap`; see
+  [ADR 0008](adr/0008-coding-profile-isolation.md)). Doctor probes every
+  configured workspace and reports `sandbox_unavailable` as an error per
+  workspace when it does not work (the workspace's filesystem must be able to be
+  an overlay lower layer). The sandbox shows only
+  `/usr`, `/etc` and the workspace: toolchains installed under the home
+  directory or `/opt` (nvm, `~/.local`) are not available, Node.js and Git from
+  the distribution are.
 - Codex CLI or Claude Code. `setup` does not pin client versions. It accepts a
   client whose public `mcp` command output matches the expected contract and
   reports `unsupported` otherwise. The contract was last recorded with Codex CLI
@@ -169,6 +183,15 @@ Rules:
   `azure`; a profile that names the old key must be changed.
 - A profile may grant tools from local stdio MCP servers through `mcpServers`.
   See [External MCP tools in embedded sessions](session-mcp.md).
+- A `read-only` profile may add `"shell": "sandboxed"` to get a `bash` tool
+  that runs every command in a bubblewrap sandbox without network, with the
+  workspace as a temporary overlay (see the requirements above). It is Linux
+  only and cannot be combined with `grantedExtensionTools`; the start fails
+  with `sandbox_unavailable` when the sandbox does not work. Without the field
+  the profile has no shell.
+- The `read`, `grep`, `find` and `ls` tools of every `read-only` profile accept
+  only paths inside the workspace and the directories of the profile's selected
+  skill files; there is no field to change that.
 - A profile may load Pi extensions that Pi has installed, through
   `extensions`: a list of at most 8 entries of the form
   `npm:<name>@<exact version>`, each package once. Ranges, tags, `git:`
@@ -747,7 +770,8 @@ repository step between the install and the client targets:
    more; both clients code through the one host `pi-session-mcp` registration.
    Use the same
    settings as before: a writer whose settings or coding profiles changed is
-   reported as `writer_settings_changed` and left as it is, and one whose
+   reported as `writer_settings_changed`, the apply is refused before the
+   mode is written and the writer is left as it is, and one whose
    coding profile selects an overridden or unshipped `builtin:` skill as
    `container_profile_unsupported`. Such a writer stays `writer_not_ready`
    until you change the profile or remove the override, or collect it,

package/docs/isolation-setup.md

@@ -31,6 +31,14 @@ clone tags, then imports the selected base tags when enabled. Worker-created
 tags are not collected work and do not affect the collected digest. The setting
 participates in settings drift, not the acceptance fingerprint.
 
+Ignored files in a persistent writer's clone survive reset and finish by
+default (`clean: "untracked"`); an ephemeral writer's finish recreates the
+clone. Add `--clean all` to a container mode request to remove
+them with `git clean -ffdx`; the per-writer `/pi/go`, `/pi/uv` and `/pi/npm` caches outside
+the clone stay untouched. Changing this setting requires collecting work,
+removing the writer with `--writer <name> --remove`, and provisioning again;
+it participates in settings drift, not the acceptance fingerprint.
+
 ## Prerequisites
 
 - Linux with usable **rootless** Podman, Node.js 22.19.0 or newer and Git.
@@ -60,7 +68,7 @@ participates in settings drift, not the acceptance fingerprint.
 | Workspace | Separate full clone per writer, created via a base bundle; no hardlinks or shared linked-worktree metadata |
 | Wrapper | Generated stdio-only launcher bound to the release and writer name; no daemon between client connections |
 | Boundary | Rootless keep-id, read-only root, capability drop, no-new-privileges, tmpfs home and /tmp; clone read-write with hooks/config overmounted read-only |
-| Mounts | Only clone, release read-only, contained config read-only, isolated writable agent directory, optional Go or uv/npm cache; no per-session writer spool mount ([below](#event-spool-mount)) |
+| Mounts | Only clone, release read-only, contained config read-only, isolated writable agent directory, optional Go, uv/npm or npm-only cache; no per-session writer spool mount ([below](#event-spool-mount)) |
 | Configuration | One workspace, selected coding profiles and a synthetic read-only default; internal acknowledged host mode permits writes only in the contained clone |
 | Credentials | Selected provider entries only; OAuth refresh token emptied, API keys retained; no host SSH/Git/client credentials intentionally mounted |
 | Acceptance | Explicit uncontained host control, then provider-free contained harness per writer; fingerprint gates readiness |
@@ -98,7 +106,13 @@ list and providers in its state, and the whole rendered writer configuration
 with each selected profile's model, thinking level and skills and the event
 delivery. A difference reports `writer_settings_changed` and leaves the writer
 as it is
-([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134)). The same
+([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134)). On
+apply the check runs before the mode is written, so a kept writer with a
+difference refuses the mode change itself: the modes file stays unchanged
+and no kept writer is changed; a surplus writer of a smaller count may already
+have been fenced
+([#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163));
+reconciliation repeats the check under each writer's lease. The same
 holds for the other findings of this check: `podman_unavailable` when Podman
 cannot be asked, `image_unavailable` when Podman answers but cannot resolve the
 image, and `container_profile_unsupported` when a selected coding profile is
@@ -254,5 +268,20 @@ or npm variables are set. The cache belongs to one writer: it is never shared
 between writers and never a host cache mount, and setup does not install uv
 or npm for you.
 
+Optional container settings `--cpus`, `--cpu-shares` and `--memory` bound the
+serving container's CPU or memory use. CPU shares are relative weight under
+contention against sibling cgroups in the operator's user slice only; CPU
+count and memory are hard caps. Setup requires the corresponding host cgroup
+controllers. A later mode request that omits a limit flag keeps the recorded
+limit; `--cpus none`, `--cpu-shares none` and `--memory none` remove it;
+changes update existing writer state without reprovisioning. See
+[Resource limits](execution-modes.md#resource-limits) for ranges and syntax.
+
+A Node writer can instead use `--cache npm`, recording `cache: "npm"` and
+mounting its private directory at `/pi/npm` with
+`npm_config_cache=/pi/npm/cache`. No other npm variables are set. Like the Go
+and uv caches, it survives reset, finish and recreate, and is removed with the
+writer. Repeat the cache flag on later mode requests.
+
 See [Execution modes](execution-modes.md#migration-from-manual-writers) for
 migration limitations and [Doctor](doctor-design.md) for offline writer checks.

package/docs/roadmap.md

@@ -17,6 +17,12 @@ mean they are implemented or that their gates passed.
   pool, base-aware allocation and host-spool events. Prepared as minor release
   0.12.0 together with #151 and #154, released the same day and installed with
   a live relayed coding session; 0.12.1 fixes client-target verify (#160).
+  Both machines run 0.12.1, and #151 and #154 passed their live checks. The
+  opt-in `--clean all` (#162) follows as an unreleased change.
+- 2026-10-28: [ADR 0013](adr/0013-hardened-read-only-profiles.md) (#169),
+  implemented and unreleased: workspace-confined read tools for every read-only
+  profile and the opt-in bubblewrap shell (`shell: "sandboxed"`). It changes the
+  public contract and needs minor release 0.13.0.
 
 The explicit 2026-10-17 user request adds a bounded development-only
 [token-footprint measurement](sprints/2026-10-17-token-footprint.md), following

package/docs/session-mcp.md

@@ -137,6 +137,19 @@ made safe by this configuration. Use dedicated credentials and external process
 isolation where stronger boundaries are required. Do not grant a generic tool that
 can dispatch arbitrary unreviewed operations and assume that its name is a boundary.
 
+Granting research tools (search, documentation lookup) to a read-only profile
+uses this same `mcpServers` mechanism with `readOnly: true`. Since every
+read-only profile is confined to its workspace and selected skill directories
+([ADR 0013](adr/0013-hardened-read-only-profiles.md)), such a tool cannot be fed
+files outside them through the model's read tools. Prefer query-style tools
+(search, documentation lookup) over tools that fetch free URLs: a fetch tool
+with free-form input is still a channel for whatever the workspace contains.
+The MCP server itself is trusted local code and is not confined.
+A skill directory that equals or contains the operator's home, the configuration
+file's directory or `~/.pi` is not a read root; only the skill file itself is,
+so a catalog entry such as `./SKILL.md` next to the configuration does not
+expose the configuration.
+
 Only local stdio tools are covered here. HTTP/SSE/OAuth transports, sampling,
 elicitation, roots negotiation, separate resource/prompt APIs and global extension
 loading are not added. MCP tool invocations are marked sequential within Pi's tool

package/docs/threat-model.md

@@ -6,6 +6,54 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
 
 ## Threats and mitigations
 
+- **Read-only file disclosure and the sandboxed shell ([ADR 0013](adr/0013-hardened-read-only-profiles.md)):**
+  read-only sessions run in the host server process. `read`, `grep`, `find` and
+  `ls` of every read-only profile therefore accept only paths inside the
+  workspace and the directories of the selected skill files, so Pi credentials
+  and other files the operator can read stay unreachable even for a
+  prompt-injected worker. Each call is checked twice: the `path` argument is
+  resolved and canonicalized with `realpath` before the SDK tool runs
+  (arguments the SDK would rewrite, such as a leading `@` or `~`, a `file:`
+  URL, Unicode spaces or NUL, are refused so both resolve the same path), and
+  the `*Operations` hooks of `read`, `grep` and `ls` check the absolute path
+  again. `rg` and `fd` do not follow symlinks during traversal. A profile with
+  `shell: "sandboxed"` also gets `bash`, run as `/usr/bin/bwrap` (fixed path,
+  root-owned and not group- or world-writable, no `PATH` lookup) with
+  `--unshare-all`, `--disable-userns`, a cleared environment, no network, `/usr`
+  and `/etc` read-only, a tmpfs `/tmp`, and the workspace (and, for a linked
+  worktree whose pointers are consistent, the main repository's Git directory)
+  as a temporary overlay whose writes vanish with the command. The operator's
+  home, `PI_*` variables and the server's environment never reach the command.
+  The shell fails closed: an untrusted binary or a failing probe is
+  `sandbox_unavailable`, and a command whose sandbox cannot start fails; there
+  is no unsandboxed fallback. It is not allowed together with granted extension
+  tools, which may write.
+  - **Residual:** the confinement checks a path when the call starts, so a
+    concurrent writer in the same workspace (for example a host-mode coding
+    session) could swap a checked directory for a symlink before `rg` or `fd`
+    opens it; read-only workers cannot create symlinks themselves. Extension
+    hooks and granted extension tools run in the server process with the
+    operator's rights and are not confined; the confinement covers the built-in
+    tools only. The sandbox exposes `/etc` and the distribution's `/usr` and an
+    overlay of the workspace and, for worktrees, of the repository's Git
+    directory, including their configuration. Lock-dependent tests that need a
+    supported local filesystem can fail on the overlay. macOS, a VM backend and
+    network allowlists inside the sandbox are out of scope. The sandbox has no
+    memory, process-count or overlay upper-layer limits (only `/tmp` is limited to
+    512 MiB and a command defaults to a 600 second timeout), so a prompt-injected
+    worker can exhaust memory or processes of the operator's user until the
+    command ends, as a host-mode coding session already can. When `bash`
+    truncates long output the SDK names a full-output file in the host's
+    temporary directory; confined `read` refuses it and the sandbox's `/tmp` is a
+    fresh tmpfs, so only the truncated output is available. `ls` omits entries
+    that are symlinks pointing outside the read roots, without a notice. A skill
+    directory that equals or contains the operator's home, the configuration
+    directory or `~/.pi` contributes only the skill file as a read root. On
+    timeout or abort the server kills bubblewrap and the PID namespace takes every
+    process of the sandbox with it. The start probe is cancelled with the start
+    request. A granted research
+    tool with free-form input (search, documentation lookup) is a possible
+    outbound channel for workspace content; prefer query-style tools.
 - **Unsafe diagnostics:** Doctor is a separate offline CLI with no MCP, Pi,
   provider, credential, or network dependency. Its human/JSON output is
   sanitized and its stable exit statuses are 0 (healthy), 1 (warning), 2
@@ -127,6 +175,8 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   - Setup edits a Claude Code settings file, which is operator configuration. It writes one `PostToolUse` entry under the same dry-run, ownership and divergence rules as a registration: a read-modify-write with a compare-and-swap on the file bytes (a changed file is read again once, a second change fails with `settings_changed`), an atomic rename that keeps the file mode, a pending-before-write ownership record and no replacement or deletion of an entry it does not own. In a project scope it never follows a link below the project root. The entry holds absolute paths of the Node executable and the package, which must be free of shell metacharacters (`hook_path_unsafe`). Ownership records hold a fingerprint, never a path or a command.
 
 - **Concurrent writer use and orphaned containers ([ADR 0012](adr/0012-leased-writer-pool.md)):** new assets are the host-only lease directory/files, stable wrappers, relay subprocess/transport and recorded workspace default base. The launcher holds `~/.local/state/pi-session-mcp/leases/<name>.lock`, not the host server. Files are never deleted, opened without following links and checked for type, owner and mode (0700 directory, 0600 file). Every mutating setup operation takes the same lease with a bounded wait (`writer_busy`), including collect and acceptance. Mutating host children inherit its descriptor; nested launchers validate/adopt it. Neither container nor Podman's monitor receives it, so worker code cannot unlock it. Fixed session name `pi-writer-<name>` and label `pi-session-mcp.writer=<name>` supplement the lock. Under the lease the holder confirms absence by label and clone mount, removes orphaned containers and fails closed if absence is uncertain, before any credential or clone change. Stdin end, SIGTERM and SIGHUP trigger refresh join and container cleanup while the launcher still holds the fence; a killed holder's leftovers are removed by the next holder. The trusted same-UID operator must not replace lease files or mutate writers outside setup.
+- **Writer resource fairness:** optional `--cpus` and `--memory` hard caps and `--cpu-shares` relative weight constrain serving containers when the Podman host exposes the required cgroup controllers. Caps are unlimited unless set, kept when a later mode request omits them, and removed only with `none`; maintenance containers are not limited. These are fairness measures for shared hosts, not a security boundary, and do not change acceptance or require reprovisioning.
+- **Ignored writer files:** by default, ignored files in a persistent writer's clone survive reset and finish and reach the next task leased on that writer, invisible to baseline checks and collect. Opt in to `--clean all` to remove them on reset and finish; per-writer Go (`/pi/go`), uv/npm (`/pi/uv`) and npm-only (`/pi/npm`) caches outside the clone remain. These private writable caches survive reset, finish and recreate and are removed with the writer; they are not shared between writers or mounted from host package caches.
 - **Untrusted relay replies and wrong-base work:** inner replies are schema-validated and size-bounded, never raw-frame passthrough. Host IDs, turn state and spool remain authoritative. Allocation matches the requested/default branch from host writer state, compares profile selection and rechecks placement after inner start; the inner guard still decides baseline admission. Transport loss fails the turn and makes further prompts refuse with `writer_session_lost`; get and close remain available. Branch matching is not commit freshness: results expose the selected base commit for review. Migration requires closed sessions/controllers, removes only owned registrations, rebinds wrappers and re-accepts provider-free; a divergent registration keeps the writer legacy rather than entering the pool.
 
 ## Residual risks

package/docs/tool-contracts.md

@@ -40,7 +40,7 @@ records name the package version and the build they ran on, see
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.12.1" },
+  "server": { "name": "pi-session-mcp", "version": "0.13.0" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -56,6 +56,7 @@ records name the package version and the build they ran on, see
     "thinkingLevel": "medium",
     "extensions": [],
     "grantedExtensionTools": [],
+    "shell": "none",
     "skills": []
   }]
 }
@@ -63,9 +64,9 @@ records name the package version and the build they ran on, see
 
 `events.delivery` is `spool` when the loaded configuration enables turn-event delivery (`"events": { "delivery": "spool" }`) and `off` otherwise. It reports configured intent, except that it is `off` when the server found no spool location at startup (no `PI_SESSION_MCP_EVENTS_DIR` and no absolute `XDG_RUNTIME_DIR`, as under Codex); it makes no claim that the spool directory is writable, and it carries no path.
 
-The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, the event delivery setting, configured aliases and workspace modes, and the nine documented profile fields. Each workspace has a required `mode`: `unset`, `host`, `container`, or `read-only`; a missing modes entry is reported as `unset`. Container entries also carry `writers` (configured count, not free capacity) and `defaultBase` (short branch name, or `null` if not yet recorded), not writer names or other writers' branches. `extensions` lists the configured extension specs (`npm:<name>@<version>`), empty when a profile loads none; it makes no claim that the package is installed. `grantedExtensionTools`, directly after `extensions`, lists the configured extension tool grants in configured order, `[]` when absent. It is configuration intent only, not proof of registration, activation or declaration to the model. `skills` lists the skill-catalog aliases that the profile selects, in configured order, `[]` when it selects none. It contains no paths, file names, contents or SDK diagnostics, and it is configuration intent only: it makes no claim that a skill file exists, loads, or will be read by the model. See [Pi skills](skills.md). It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
+The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, the event delivery setting, configured aliases and workspace modes, and the ten documented profile fields. Each workspace has a required `mode`: `unset`, `host`, `container`, or `read-only`; a missing modes entry is reported as `unset`. Container entries also carry `writers` (configured count, not free capacity) and `defaultBase` (short branch name, or `null` if not yet recorded), not writer names or other writers' branches. `extensions` lists the configured extension specs (`npm:<name>@<version>`), empty when a profile loads none; it makes no claim that the package is installed. `grantedExtensionTools`, directly after `extensions`, lists the configured extension tool grants in configured order, `[]` when absent. It is configuration intent only, not proof of registration, activation or declaration to the model. `shell`, directly after `grantedExtensionTools`, is `none` or `sandboxed` ([ADR 0013](adr/0013-hardened-read-only-profiles.md)). `sandboxed` means the profile is configured to get a `bash` tool that runs each command in a network-less bubblewrap sandbox; it is configuration intent only and no claim that the sandbox works on this host (a failing sandbox surfaces as `sandbox_unavailable` at session start, and Doctor checks it offline). `skills` lists the skill-catalog aliases that the profile selects, in configured order, `[]` when it selects none. It contains no paths, file names, contents or SDK diagnostics, and it is configuration intent only: it makes no claim that a skill file exists, loads, or will be read by the model. See [Pi skills](skills.md). It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
 
-Setup verify accepts and validates `grantedExtensionTools` in its bounded direct
+Setup verify accepts and validates `grantedExtensionTools` and `shell` in its bounded direct
 MCP capabilities check, without starting a session or using a provider.
 **Verifier limit:** at maximum field sizes (8 extension specs of 256 characters,
 32 grants of 64 characters, provider and model of 256 characters each), at most
@@ -111,6 +112,31 @@ tools: registered-but-inactive tools fail closed too. Lazy registration in
 decision: third-party tools may write, and workspace modes `container` and
 `read-only` do not restrict them. See [ADR 0010](adr/0010-read-only-extension-tools.md).
 
+### Read-only confinement and the sandboxed shell
+
+[ADR 0013](adr/0013-hardened-read-only-profiles.md) confines `read`, `grep`,
+`find` and `ls` of **every** read-only profile to the session's workspace and
+the directories of the profile's selected skill files. A `path` outside them
+(absolute, `..`, `~`, a symlink leading out, a leading `@`, a `file:` URL, a
+Unicode space or NUL) is an ordinary tool error to the model,
+`Path is outside the allowed read roots`, without the path. It is not a start
+or turn error and has no code. Files outside the workspace that earlier
+read-only sessions could read are no longer readable. Coding profiles are
+unchanged.
+
+The optional profile field `shell` takes the single value `"sandboxed"`. It is
+valid only on `read-only` profiles, not together with `grantedExtensionTools`,
+and only on Linux; any other combination prevents startup with
+`invalid_execution_profile_config`. Such a profile also has a `bash` tool. Each
+command runs under `/usr/bin/bwrap` with no network, the workspace as a
+temporary copy-on-write overlay (writes vanish when the command ends), `/usr`
+and `/etc` read-only and no other host path. Before the session starts the
+server runs a probe through the same sandbox; if the binary is untrusted or the
+probe fails, start fails with `sandbox_unavailable` and no session exists. There
+is no unsandboxed fallback. For a linked worktree the main repository's Git
+directory is mounted as a second temporary overlay when its pointers are
+consistent, so `git log` and `git blame` work. The sandbox's `/tmp` is limited to 512 MiB, and a command without a `timeout` argument is killed after 600 seconds.
+
 ## Automated writer boundary (Plan B)
 
 The host routes container coding through its relay adapter under
@@ -166,6 +192,7 @@ Public MCP errors are stable and sanitized. Their messages do not include inputs
 | `extension_tool_conflict` | An extension tool name collides with a built-in, MCP or other extension tool, or is unsafe: not 1 to 64 letters, digits, `_` or `-` (not starting with `-`), or reserved for MCP (`mcp__` prefix, `list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource`). |
 | `extension_tool_missing` | A granted extension tool is not registered at load or is not active and declared to the model at admission. Fixed message: `Granted Pi extension tool is not available`; class `needs_operator` (operator needed; do not retry or switch profiles). |
 | `skill_load_failed` | A skill that the profile selects could not be loaded: a missing (also a `builtin:` name that matches no override and no shipped skill), unreadable or oversized (over 256 KiB) file, an invalid skill, two selected files with the same Pi skill name, two aliases on the same canonical file, or a skill with `disable-model-invocation: true`. The message is the fixed `Configured Pi skill could not be loaded`; it never contains a path, skill name or SDK text. |
+| `sandbox_unavailable` | A profile with `shell: "sandboxed"` cannot start its shell sandbox: the bubblewrap binary is missing or untrusted, or the probe run for the session's workspace failed or was cancelled with the start request. Fixed message: `Read-only shell sandbox is not available`; class `needs_operator` (operator needed; do not retry or switch profiles). |
 | `pi_session_creation_failed` | Pi session construction failed without a more specific safe classification. |
 | `writer_uncollected` | The writer is not at its collected baseline, or its guard/Git state could not be verified; controller must collect and reset it. |
 | `writer_busy` | Controller action: a session or another operation holds the writer; wait for or close it. Setup waits briefly (10 seconds) for the lease, then fails with this code. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [

package/skills/pi-session-orchestration/references/start-errors.md

@@ -2,7 +2,7 @@
 
 Load this file only after a `pi_session_start` call has failed. Classify the error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Each code below is in exactly one class.
 
-- Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `workspace_mode_forbids_coding`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `extension_tool_missing`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `writer_not_ready`, `container_runtime_unavailable`, `server_stopping`. Writer readiness needs repository setup and acceptance; runtime unavailability needs usable rootless Podman. The last code means the server is shutting down: a new server process is needed, not a retry.
+- Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `workspace_mode_forbids_coding`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `sandbox_unavailable`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `extension_tool_missing`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `writer_not_ready`, `container_runtime_unavailable`, `server_stopping`. Writer readiness needs repository setup and acceptance; runtime unavailability needs usable rootless Podman. The last code means the server is shutting down: a new server process is needed, not a retry.
 - Controller action (do not blindly retry or switch profiles; collect and reset the writer for uncollected work, or wait for or close the open coding session for a busy writer; resolve pool state, lost sessions or inapplicable base before a fresh start): `writer_uncollected`, `writer_busy`, `writer_unavailable`, `writer_session_lost`, `base_not_applicable`.
 - Transient (retry at most once after a pause, then report): `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol), `extension_load_failed` (an invalid package, but also a start timeout), `local_authentication_unavailable` (local authentication could not be resolved within its deadline).
 - Unknown (report the code; at most one retry in a fresh session): `pi_session_creation_failed`. Any code not listed above is also unknown.