pi-session-mcp 0.12.0 → 0.13.0

package/docs/acceptance.md

@@ -2457,6 +2457,272 @@ Not established for `0.11.6`:
   wrapper's periodic credential copy (#136);
 - the VS Code wake; macOS delivery.
 
+### v0.13.0 pre-release acceptance
+
+`v0.13.0` was accepted on 2026-10-28 from 19:30 to 19:36 UTC on its release
+candidate `f7442b3`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.162.1` and Claude Code `2.1.312`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The minor release ships ADR 0013 (#169) and the writer settings changes #162,
+#163, #165 and #166. It changes the MCP contract (read-only confinement,
+profile field and capabilities field `shell`, start error
+`sandbox_unavailable`); the setup report schema is unchanged.
+
+- Level 1 in a clean worktree of the candidate after `npm ci`: every command
+  exited with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    125 files, 3936 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` finding through `@earendil-works/pi-coding-agent` 1.4.0
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 916 files (tarball shasum
+    `1259d57d2d59099ad72e796609ecab3d581e9b06`, identical in two packs). A scan
+    of the packed files for private names, hosts and paths found none; its only
+    matches for `/home/` are the already redacted
+    `<repo>/eval/results/.../home/.pi/...` paths of disposable evaluation homes
+    in six `docs/evaluation/extension-functions-2026-10-17/cursor/` evidence
+    files, which `0.12.1` shipped unchanged.
+  - Doctor reported `packageVersion` `0.13.0`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke from another fresh prefix
+  reported `smoke_passed` with version `0.13.0`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained, the leak check passed and the disposable directories were removed.
+- Podman-gated writer tests on the candidate: 7 of 7 passed.
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+- Review: #169 had an independent review of its full diff (same model family as
+  the author) that found no confinement or sandbox escape; its follow-ups were
+  fixed before the merge of #170.
+
+Not established for `0.13.0`: a live session with `shell: "sandboxed"` against
+a real provider, client-target `--verify` through the installed package, which
+follows the upgrade; Level 3.
+
+### v0.12.1 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.12.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.12.1` (tag object
+`eecd6dbf0c220ded997c697f281f6b984d9ebf4e`) peels to the merge commit
+`91799f2e84b514110f77c24986d59e72c5ed98e5` of #161, and
+`git describe --tags --exact-match` reports `v0.12.1`. CI on the merge commit
+and on the tag passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 14:43 to 14:47 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (120 files, 3708 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean.
+- `pi-session-mcp@0.12.1` on npm: 907 files, shasum
+  `58dc7235e0d54d4290d92934d877223e22eec03d`, `gitHead` `cc25693` (the head of
+  #161, whose tree equals the merge commit). `npm pack` of the tag clone gives
+  the same shasum and file count.
+- Published npm package, Level 2 from a fresh prefix: 160 of 160 with delivery
+  off and 228 of 228 with `--events spool`; real registrations and built files
+  unchanged, no process left, leak check passed. Clients: Codex CLI `0.162.1`
+  and Claude Code `2.1.312`. The install smoke on the published package
+  reported `smoke_passed` with version `0.12.1`.
+- The GitHub release `v0.12.1` was published the same day.
+
+Workstation, upgraded from `0.12.0` to `0.12.1` by the release session: Doctor
+reported no error, client-target `--verify` passed for `claude-code:user` and
+`codex:user` (`mcp_verified`, `skill_verified`, and `hook_verified` for the
+wake hook), the open point of the pre-release record, and
+`--writer <name> --verify` passed for all 18 writers (`mcp_verified`).
+
+Operator upgrade of the second machine (Linux) from `0.11.8` to `0.12.1` on
+2026-10-28 from 14:50 UTC, following
+[Installation](installation.md#container-writers), with Node.js `24.22.0`:
+
+- No pi-session-mcp server process and no writer container ran at the start.
+- Both client targets were removed with `0.11.8`, then
+  `npm install -g pi-session-mcp@0.12.1`. Doctor reported every writer
+  `writer_not_ready`, each container workspace `workspace_base_unset` and each
+  writer `writer_git_identity_missing`.
+- Four container repositories with 14 writers were migrated by repeating their
+  provisioning commands with unchanged settings, each first as a dry run
+  (`planned`), then with `--apply`: 2, 4, 4 (operator image, `--cache go`) and
+  4 (operator image) writers. Every writer reported `writer_accepted`.
+- `--finish --apply` of all 14 writers reported `writer_reset`; no work was
+  collected. Doctor then reported no writer or base finding.
+- `--apply` and `--verify` of both client targets passed (`mcp_verified`), and
+  `--writer <name> --verify` passed for all 14 writers. No writer registration
+  and no container remained.
+
+Live checks of #154 and #151 on the workstation, 15:02 to 15:04 UTC, with the
+coding profile `code-deepseek` through the one host registration and wake
+events from the host spool:
+
+- Settings change: a writer whose settings differ is refused with
+  `writer_settings_changed`. Both repositories' writers were collected
+  (`nothing_to_collect`), removed with `--writer <name> --remove` and
+  provisioned again with `--tags reachable` (2 writers) and `--cache uv`
+  (4 writers, operator image with uv `0.13.6`); every writer reported
+  `writer_accepted`.
+- Tags (#154): the writer with `--tags reachable` held 14 tags, the tags of
+  the operator checkout merged into `main`. In the session,
+  `git describe --tags` reported `v0.12.1` and
+  `git show v0.12.0:package.json` read the file at that tag. The writer without
+  the setting held no tags.
+- Identity (#154): an empty commit in the session, without `GIT_AUTHOR_*` or
+  `GIT_COMMITTER_*` and without `--author`, recorded the operator's name as
+  author and committer. `git config user.name` inside the writer failed with
+  exit `4` because `.git/config` is mounted read-only. The collected ref showed
+  the same identity. The test ref was removed afterwards.
+- uv cache (#151): three sessions on the same writer, with `--finish --apply`
+  between the second and the third. In the first, `UV_CACHE_DIR` was
+  `/pi/uv/cache` and empty; `uv sync --frozen` took 1.9 s and left 95,576 KiB
+  in 1,648 files. The second and third sessions found the same size and file
+  count before they ran anything, and `uv sync --frozen --offline` after
+  removing `.venv` took 0.07 s and 0.08 s.
+
+Findings from these checks:
+
+- Reset and finish keep Git-ignored files in the clone, as designed: `.venv`
+  from the first session was still present in the third, after the finish.
+  The opt-in `--clean all` removes them
+  ([#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162)); it is
+  not part of the released `0.12.1`.
+- A provisioning command with changed settings reported `mode_applied` and
+  recorded the new mode although every writer failed with
+  `writer_settings_changed`; Doctor reported no mismatch
+  ([#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163), open).
+
+Not established for `0.12.1`: a busy pool (`writer_unavailable`) and a `base`
+fix round in live use; Level 3; the macOS upgrade.
+
+### v0.12.1 pre-release acceptance
+
+`v0.12.1` was accepted on 2026-10-28 from 13:12 to 13:17 UTC on its release
+candidate `c6b472d`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.162.1` and Claude Code `2.1.312`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The patch ships #160 on top of 0.12.0. It does not change the MCP contract or
+the setup report schema.
+
+- Level 1 in a clean worktree of the candidate after `npm ci`: every command
+  exited with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    120 files, 3708 passed and 14 skipped, and no unhandled error. It ran on a
+    host with a real writer lease directory, which the Doctor mode-order test
+    no longer reads.
+  - `npm audit` exited with `1` and names only the known `undici` finding
+    through `@earendil-works/pi-coding-agent` 1.4.0
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 907 files (tarball shasum
+    `f206e0eb0818342fb9e6a36c2c147fb690c515ce`); a scan of the packed files for
+    private names, hosts and paths found none.
+  - Doctor reported `packageVersion` `0.12.1`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke reported `smoke_passed`
+  with version `0.12.1`.
+- In every Level 2 run the real client registrations and the built files were
+  unchanged, no process remained, and the leak check passed.
+- Podman-gated writer tests on the candidate: 4 of 4 passed.
+- The candidate's setup verifier against its own server with the operator's
+  real configuration, which has five container workspaces, reported
+  `verified`, with initialize, `tools/list` (eight tools) and
+  `pi_capabilities_get`. The same check with the installed 0.12.0 failed at
+  `pi_capabilities_get`.
+- Review: `review-glm` (another model family than the author) on the fix,
+  verdict `NON_BLOCKING_ONLY`; the shared writer bound and the real-server test
+  with container workspaces were added.
+
+Not established for `0.12.1`: client-target `--verify` through the installed
+package, which follows the upgrade; Level 3.
+
+### v0.12.0 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.12.0`.
+
+Tag binding: a fresh clone of the annotated tag `v0.12.0` (tag object
+`bb77dfd8a4e49849d5e9c7fd305fb00baf443044`) peels to the merge commit
+`dfbef8c5efce38eacc8704dbaf93c534cdad0ef8` of #159, and
+`git describe --tags --exact-match` reports `v0.12.0`. CI on the merge commit
+passed on Linux, macOS 15, macOS 26 and `verify` after one rerun: the first
+macOS 26 run hit a timeout in `test/extension-ablation-deps.test.ts`
+(5044 ms against 5000 ms), a git-heavy evaluation test that the release did not
+touch. CI on the tag passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`: typecheck, `build:cli`, the test
+  run (120 files, 3693 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean. Doctor
+  reported `packageVersion` `0.12.0`.
+- `pi-session-mcp@0.12.0` on npm: 907 files, shasum
+  `4699b05ef849e88c6d56f5ddae6b06984799cea6`, `gitHead` `1fb8a7e` (the head of
+  #159, whose tree equals the merge commit). A local `npm pack` of the merge
+  commit gives the same shasum. A scan of the published files for private
+  names, hosts and paths found none.
+- Published npm package, Level 2 from a fresh prefix: 160 of 160 with delivery
+  off and 228 of 228 with `--events spool`; the install smoke reported
+  `smoke_passed` with version `0.12.0`. Clients: Codex CLI `0.162.1` and Claude
+  Code `2.1.312`.
+- The GitHub release `v0.12.0` was published the same day.
+
+Operator upgrade of the workstation from `0.11.8` to `0.12.0` on 2026-10-28,
+following [Installation](installation.md#container-writers):
+
+- Coding sessions were closed and the two pi-session-mcp writer servers were
+  disabled in the controller; one idle controller of another repository still
+  had four writer containers running.
+- Both host client targets (`claude-code:user`, `codex:user`) were removed with
+  `0.11.8`, then `npm install -g pi-session-mcp@0.12.0`. Doctor reported
+  `packageVersion` `0.12.0` and, as expected, every writer `writer_not_ready`
+  and `writer_not_migrated`.
+- Five container repositories with 18 writers were migrated by repeating their
+  provisioning commands with unchanged settings, each first as a dry run
+  (`planned`), then with `--apply`: pi-session-mcp (2 writers), node-app (4),
+  go-app (4, operator image, `--cache go`), pynode-app (4, operator image,
+  base `dev`) and py-app (4, operator image). Every writer reported
+  `writer_accepted` and is `launch: "relay"`, `ready`, verdict `pass`. Each
+  repository recorded its shared default base (`main`, and `dev` for
+  pynode-app). All 36 owned writer registrations and their hook entries were
+  removed; the fence removed the four running legacy containers; no writer
+  container remained.
+- `--apply` of both client targets passed, but `--verify` failed with
+  `mcp_failed` on both:
+  [#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160). A direct
+  handshake with the installed server returned the eight tools and the
+  capabilities, including `writers` and `defaultBase` for each container
+  workspace; the 0.12.0 verifier rejected them. The fix, run with the real
+  configuration against the candidate's own server, reported `verified`.
+- `--writer <name> --verify` passed for all 18 writers over the relay path
+  (`mcp_verified`).
+- Live relayed coding session through the one host registration, after
+  reconnecting `pi-session-mcp`: `pi_capabilities_get` listed the container
+  workspaces with `writers` and `defaultBase`; `pi_session_start` with profile
+  `code` on the pi-session-mcp workspace leased `pi-session-mcp-w1` at
+  `refs/heads/main` and returned `writer` and `base`. The worker implemented
+  the #160 fix in two turns. Both turns woke the controller through the wake
+  hook from the host spool, without polling. Close, collect and finish
+  succeeded without a reconnect. A read-only `review-glm` session on the host
+  checkout reviewed the commit (`NON_BLOCKING_ONLY`).
+- The first turn could not commit: the migrated clones had no commit identity
+  (Doctor `writer_git_identity_missing` on all 18 writers), because migration
+  keeps the clone and only provisioning and reset copy the identity. After
+  `--finish` of the used writer and `--reset --apply` of the other 17, Doctor
+  reported no writer finding, and all 18 writers stayed `relay`, `ready` and
+  accepted. The upgrade runbook now names this step.
+
+Not established for `0.12.0`: the upgrade of the second machine; the live
+checks of #151 (`--cache uv`) and #154 (`--tags reachable`), which need a
+settings change of an existing writer; a busy-pool (`writer_unavailable`) and a
+`base` fix round in live use; Level 3.
+
 ### v0.12.0 pre-release acceptance
 
 `v0.12.0` was accepted on 2026-10-28 from 11:40 to 11:45 UTC on its release

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,
@@ -756,6 +780,15 @@ repository step between the install and the client targets:
 3. `--apply` and `--verify` the client targets, then `--writer <name> --verify`
    for each writer. Reconnect the host `pi-session-mcp` server after migration
    and client setup. Later reset, finish and recreate need no reconnect.
+   On 0.12.0, client-target verify fails with `mcp_failed` once a container
+   workspace exists
+   ([#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160)); 0.12.1
+   fixes it.
+4. Migration keeps each clone, so a writer migrated from a release before
+   0.12.0 has no commit identity yet, and Doctor reports
+   `writer_git_identity_missing`. Collect any work, then
+   `--writer <name> --reset --apply` (or `--finish --apply`) each writer;
+   reset copies the operator checkout's identity into the clone.
 
 The repository step does not count another repository's writers that are not
 ready yet, so the repositories can be accepted one after the other. Releases