pi-session-mcp 0.12.0 → 0.13.0

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

@@ -15,7 +15,14 @@ mean they are implemented or that their gates passed.
 - 2026-10-28: [ADR 0012](adr/0012-leased-writer-pool.md) was accepted and
   implemented in #157: one host registration with a leased container writer
   pool, base-aware allocation and host-spool events. Prepared as minor release
-  0.12.0 together with #151 and #154; no new live acceptance is claimed.
+  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.0" },
+  "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.0",
+  "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.