pi-session-mcp 0.13.0 → 0.13.1

package/docs/acceptance.md

@@ -2457,6 +2457,136 @@ Not established for `0.11.6`:
   wrapper's periodic credential copy (#136);
 - the VS Code wake; macOS delivery.
 
+### v0.13.0 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.13.0`.
+
+Tag binding: a fresh clone of the annotated tag `v0.13.0` (tag object
+`8c2d513ccac17916fdf7cf3fc36b3ccd454138ed`) peels to the merge commit
+`d1c63dac3b996952976aab4b5ad11665e7108fa3` of #171, and
+`git describe --tags --exact-match` reports `v0.13.0`. CI on the merge commit
+(run 40757781881) and on the tag (run 40759098803) passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 21:01 to 21:03 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (125 files, 3936 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.13.0` and exited with `2` because no
+  configuration was set (`config_missing`).
+- `pi-session-mcp@0.13.0` on npm: 916 files, shasum
+  `866d0ecfa3b4e1a71462d291b1776897229f7827`, `gitHead` `4521d39` (the head of
+  #171, 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, 21:03 to 21:05 UTC:
+  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.13.0`.
+- The GitHub release `v0.13.0` was published the same day.
+
+Operator upgrade of the second machine (Linux) from `0.12.1` to `0.13.0` on
+2026-10-28 from 20:34 UTC, following
+[Installation](installation.md#container-writers), with Node.js `24.22.0`:
+
+- Both client targets were removed with `0.12.1`, then
+  `npm install -g pi-session-mcp@0.13.0`.
+- Four container repositories with 14 writers were migrated by repeating their
+  provisioning commands with unchanged settings and `--apply`: 2, 4, 4
+  (operator image, `--cache go`) and 4 (operator image) writers. Every writer
+  reported `writer_accepted`.
+- `--apply` and `--verify` of both client targets passed (`mcp_verified`), the
+  open point of the pre-release record, and `--writer <name> --verify` passed
+  for all 14 writers. Doctor reported no error.
+
+Operator upgrade of the workstation from `0.12.1` to `0.13.0` on 2026-10-28
+from 20:47 UTC, with the same steps: no writer container ran at the start;
+five container repositories with 18 writers (2, 4, 4 with `--cache go`, 4 with
+base `dev`, 4 with `--cache uv`, three of them with operator images) reported
+`writer_accepted`; client-target `--apply` and `--verify` passed for
+`claude-code:user` and `codex:user` (`mcp_verified`, `skill_verified`, and
+`hook_verified` for the wake hook); `--writer <name> --verify` passed for all
+18 writers. Doctor reported no error.
+
+Live check of `shell: "sandboxed"` on both machines, the open point of the
+pre-release record. Two read-only profiles were added to each configuration,
+copies of the existing review profiles with `"shell": "sandboxed"`, one per
+provider family. Doctor reported `sandbox_unavailable` and
+`workspace_git_unavailable` as `ok`. A stdio driver against the installed
+server started one session per profile on the pi-session-mcp workspace (a plain
+checkout, not a linked worktree) and sent one prompt with five steps. All four
+sessions completed with the same results:
+
+- `git log -1 --format=%h` through `bash` printed the checkout's head commit.
+- `touch sandbox-probe.txt && ls sandbox-probe.txt` succeeded in the sandbox;
+  afterwards the file did not exist on the host and `git status` of the host
+  checkout was clean.
+- `getent hosts example.com || echo NO_NETWORK` printed `NO_NETWORK`.
+- `echo HOME=$HOME` printed `HOME=/tmp/home`.
+- `read` of `/etc/hostname` returned `Path is outside the allowed read roots`.
+
+Finding from these checks: the first workstation edit left out the required
+profile field `default`. Doctor then reported only `config_invalid` with the
+generic remediation and did not name the profile or the field; parsing the file
+with the package's configuration schema named both. With `"default": false`
+added, Doctor reported no error.
+
+Not established for `0.13.0`: the sandbox on a host that restricts unprivileged
+user namespaces; Git inside the sandbox on a linked worktree in live use (the
+bubblewrap-gated tests cover it); the macOS upgrade; Level 3.
+
+### v0.13.1 pre-release acceptance
+
+`v0.13.1` was accepted on 2026-10-29 from 06:40 to 06:48 UTC on its release
+candidate `89a366e`, 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`. After the candidate, one lockfile-only
+commit moved the development-path `@hono/node-server` 2.1.1 → 2.1.5; Level 1
+was run again on it after `npm ci` (same counts). The packed package and the
+working-tree build that Level 2 used do not contain that package. Later commits
+on the release pull request change only this record.
+
+The patch release ships #173, #176, #177, #179 and #180 under an unchanged MCP
+contract. The setup report schema is unchanged; a broken kept writer now
+reports its own code on its target instead of `writer_reconcile_failed`.
+
+- 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
+    136 files, 3948 passed and 14 skipped, and no unhandled error.
+  - `npm audit --omit=dev` exited with `1` and names only the known `undici`
+    finding through `@earendil-works/pi-coding-agent` 1.4.0, now with eight
+    advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+    `npm audit` also named `@hono/node-server` 2.1.1 in the development path
+    (GHSA-rmxm-3fg6-px4f), patched in the lockfile afterwards as above.
+  - `npm pack` listed 922 files (tarball shasum
+    `93f9c5bc9e268af7e0be5e395d97558ec801668a`, 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 paths in this file and in the
+    six `docs/evaluation/extension-functions-2026-10-17/cursor/` evidence files
+    that earlier releases shipped unchanged.
+  - Doctor reported `packageVersion` `0.13.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 from another fresh prefix
+  reported `smoke_passed` with version `0.13.1`.
+- 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 (Podman `6.1.4`): 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: #179, #180 and #181 had an independent review (same model family as
+  the author) with no blocking findings; its follow-ups were fixed before the
+  merge of #184. The final test-file split commit was checked by comparing the
+  sorted test names before and after (464, identical).
+
+Not established for `0.13.1`: a live wake-hook race, a live reconcile with a
+broken writer, client-target `--verify` through the installed package, which
+follows the upgrade; Level 3.
+
 ### 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

package/docs/adr/0009-execution-modes.md

@@ -105,8 +105,9 @@ This decision does not itself bump the package version or authorize publication.
    it passes, then require contained provider-free acceptance bound to wrapper,
    package version, image ID, Podman version, network and cache.
 6. **Credential lifetime.** Launcher checks every 60 seconds. Only selected
-   OAuth tokens expired or within 2 minutes of expiry trigger host login
-   warmup (invalid/missing expiry also triggers it); measured warmup refreshes
+   OAuth tokens expired or within 2 minutes of expiry (raised to 10 minutes
+   in [#142](https://github.com/plagor44-ux/pi-session-mcp/issues/142), see
+   [Execution modes](../execution-modes.md)) trigger host login warmup (invalid/missing expiry also triggers it); measured warmup refreshes
    expired/almost expired tokens only. It then re-copies credentials, with
    OAuth refresh tokens emptied. Direct verify disables refresh with
    `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, makes no session/provider request and

package/docs/adr/0012-leased-writer-pool.md

@@ -1,8 +1,8 @@
 # ADR 0012: One registration with a leased writer pool
 
-**Status:** Accepted (2026-10-28, maintainer decision) for release 0.12.0;
-implementation tracked in
-[#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157). Amends
+**Status:** Accepted (2026-10-28, maintainer decision); implemented in
+[#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157) and released
+in 0.12.0. Amends
 [ADR 0002](0002-embedded-pi-sdk.md) (container sessions are relayed to a Pi
 session in a writer process; host sessions stay embedded),
 [ADR 0008](0008-coding-profile-isolation.md) (adopts its option 4 in container

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

@@ -1,6 +1,6 @@
 # ADR 0013: Hardened read-only profiles
 
-**Status:** Accepted (2026-10-28). Amends
+**Status:** Accepted (2026-10-28); released in 0.13.0. Amends
 [ADR 0006](0006-pi-extension-allowlist.md) and
 [ADR 0010](0010-read-only-extension-tools.md). Issue #169.
 
@@ -28,9 +28,11 @@ paths inside the allowed read roots:
 - 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.
+  (and, for a symlinked configuration file, its target's directory), `~/.pi`
+  or Pi's agent directory (`~/.pi/agent`, or `PI_CODING_AGENT_DIR`), only the
+  skill file itself is a root, so a catalog entry such as `./SKILL.md` next to
+  the configuration or Pi's credentials does not expose them. The real file of
+  a symlinked skill file is a root as well, so the model can read it.
 
 The server replaces the SDK's built-in definitions with definitions built from
 the root exports `createReadToolDefinition`, `createGrepToolDefinition`,

package/docs/architecture.md

@@ -47,7 +47,7 @@ reconciled only when the registration still matches that binding. A changed
 release fails closed and cannot silently inherit or replace another release's
 registration.
 
-`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, `configuration: { fingerprint, reloadPolicy: "restart-required" }` and `events: { delivery: "spool" | "off" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
+`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns workspace aliases with their execution `mode` (plus `writers` and `defaultBase` for container workspaces) and profile aliases with the configured permission/provider/model/thinking intent, the configured extension specs, `grantedExtensionTools`, `shell` (`none` or `sandboxed`) and the selected skill aliases, sorted by alias, `configuration: { fingerprint, reloadPolicy: "restart-required" }` and `events: { delivery: "spool" | "off" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
 
 ## Leased container writers
 

package/docs/client-setup.md

@@ -302,7 +302,7 @@ Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
 }
 ```
 
-Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers`, `extensions` and `skills` described in [Installation](installation.md) and [Pi skills](skills.md); aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. An optional top-level `events` field, exactly `{ "delivery": "spool" }` or `{ "delivery": "off" }`, controls turn-event delivery for the Claude Code wake (`spool` enables it; `off`, the default when the field is absent, writes nothing); any other shape fails startup with `invalid_event_delivery`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
+Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers`, `extensions`, `grantedExtensionTools`, `shell` and `skills` described in [Installation](installation.md), [Pi skills](skills.md) and [ADR 0013](adr/0013-hardened-read-only-profiles.md); aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. An optional top-level `events` field, exactly `{ "delivery": "spool" }` or `{ "delivery": "off" }`, controls turn-event delivery for the Claude Code wake (`spool` enables it; `off`, the default when the field is absent, writes nothing); any other shape fails startup with `invalid_event_delivery`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
 
 Use placeholders until a locally available provider/model pair is known. Do not put keys, tokens, credential objects, headers, base URLs, or authentication paths in this file.
 
@@ -373,8 +373,8 @@ Claude Code enforces each tool's declared JSON Schema (`additionalProperties: fa
 
 ## Expected flow and lifecycle deadlines
 
-1. Call `pi_capabilities_get` with `{}` and select explicit workspace and read-only execution-profile aliases from the returned config-derived lists.
-2. Call `pi_session_start` with those aliases. The server resolves the configured provider/model through its shared `ModelRuntime` (a profile with extensions gets a fresh runtime for each session), loads and validates the profile's selected skills, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
+1. Call `pi_capabilities_get` with `{}` and select a workspace alias and an execution-profile alias from the returned config-derived lists.
+2. Call `pi_session_start` with those aliases (without `executionProfile` the default profile is used; `base` applies only to a coding profile on a container workspace). The server resolves the configured provider/model through its shared `ModelRuntime` (a profile with extensions gets a fresh runtime for each session), loads and validates the profile's selected skills, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
 3. Call `pi_session_prompt` with the returned `sessionId` and a read-only prompt. It returns after accepted preflight with a `turnId` in `running` state.
 4. Poll `pi_turn_get` with that `sessionId` and `turnId` until `completed`, `failed`, or `aborted`, with a deadline no longer than three minutes. There is no `pi_turn_wait` tool. With event delivery active (`events.delivery` is `spool` in `pi_capabilities_get`) and the wake hook installed, a Claude Code controller waits for the wake instead and reads the turn once.
 5. Call `pi_session_close` when the session is no longer needed.

package/docs/doctor-design.md

@@ -27,7 +27,7 @@ and owners are:
 | `version_mismatch` | Package and lock versions differ; this is a warning and does not apply to an npm installation, which has no lockfile | `package version` |
 | `config_missing` | `PI_SESSION_MCP_CONFIG` is not set, or the file it names is absent | `configuration` |
 | `config_unreadable` | The supported configuration path cannot be read | `configuration` |
-| `config_invalid` | Production `loadConfig` rejects the configuration | `configuration` |
+| `config_invalid` | Production `loadConfig` rejects the configuration. One check per schema issue location, at most five, sorted | `configuration:<location>`, a dotted path of schema field names, aliases and array indexes such as `configuration:executionProfiles.review.default`; an unknown key that is not a schema field name, and any other key that is not a valid alias, is shown as `<key>`, because it could be a path or a secret. `configuration` when the error has no location |
 | `workspace_missing` | A resolved configured workspace does not exist | validated workspace alias |
 | `workspace_not_directory` | A resolved workspace is not a directory | validated workspace alias |
 | `workspace_unreadable` | A resolved workspace cannot be read | validated workspace alias |

package/docs/execution-modes.md

@@ -271,7 +271,7 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `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, 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_reconcile_failed` | Unexpected reconciliation failure of shared setup state (configuration, ownership); a failure of one kept writer is reported on that writer's target with its own code, and the other writers are still reconciled |
 | `writer_operation_failed` | Unclassified lifecycle/orchestrator failure |
 | `hook_install_failed` | The wake hook step of a writer failed unexpectedly; other `hook_*` and `settings_*` codes are in [Client setup](client-setup.md#wake-hook) |
 | `container_profile_unsupported` | Profile or selected skills cannot be rendered safely in boundary |

package/docs/roadmap.md

@@ -18,11 +18,19 @@ mean they are implemented or that their gates passed.
   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.
+  opt-in `--clean all` (#162) shipped in 0.13.0.
+- 2026-10-28: [ADR 0013](adr/0013-hardened-read-only-profiles.md) (#169):
+  workspace-confined read tools for every read-only profile and the opt-in
+  bubblewrap shell (`shell: "sandboxed"`), released in minor release 0.13.0
+  together with #162, #163, #165 and #166.
+- 2026-10-29: the post-0.13.0 review findings in one pull request, unreleased:
+  stale waiter-lock reclamation in the wake hook
+  ([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)), per-writer
+  reconcile failures ([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180))
+  and the split of `setup-writers.ts` and the largest test files
+  ([#181](https://github.com/plagor44-ux/pi-session-mcp/issues/181)). #120 still
+  waits for a Pi SDK release: 1.4.0 is the newest and still pins `undici` 8.10.2,
+  which `npm audit` now reports with eight advisories.
 
 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

@@ -146,9 +146,11 @@ files outside them through the model's read tools. Prefer query-style tools
 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.
+file's directory (or its symlink target's directory), `~/.pi` or Pi's agent
+directory (`~/.pi/agent` or `PI_CODING_AGENT_DIR`) is not a read root; only the
+skill file itself is, so a catalog entry such as `./SKILL.md` next to the
+configuration or Pi's credentials does not expose them. The real file of a
+symlinked skill file is a read root too, and only that file.
 
 Only local stdio tools are covered here. HTTP/SSE/OAuth transports, sampling,
 elicitation, roots negotiation, separate resource/prompt APIs and global extension

package/docs/threat-model.md

@@ -48,7 +48,8 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
     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
+    directory (or its symlink target's), `~/.pi` or Pi's agent directory
+    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

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.13.0" },
+  "server": { "name": "pi-session-mcp", "version": "0.13.1" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -201,14 +201,16 @@ Public MCP errors are stable and sanitized. Their messages do not include inputs
 | `base_not_applicable` | Controller action: remove `base` unless starting a coding profile on a container workspace. No session was created; do not switch profiles to bypass policy. |
 | `writer_not_ready` | The writer launcher cannot establish current readiness; operator must run repository setup/acceptance. All refusal-server tools return this error. |
 | `container_runtime_unavailable` | The writer launcher found no usable rootless Podman; all refusal-server tools refuse work, with no host fallback. |
+| `writer_fenced` | The writer launcher could not confirm that no container of the writer is still running; all refusal-server tools refuse work. Through the host relay a start reports this as `writer_unavailable` with reason `none_admitted`. |
 | `server_stopping` | Shutdown has begun, so a new session cannot be admitted. |
 
-Lifecycle errors include `unknown_workspace`, `unknown_session`, `session_running`, `prompt_rejected`, `prompt_timeout`, `abort_failed`, `abort_timeout`, and `turn_failed`. Timeout messages are stable: `Pi prompt preflight timed out` and `Pi abort timed out`.
+Lifecycle errors include `unknown_workspace`, `unknown_session`, `unknown_turn`, `session_running`, `prompt_rejected`, `prompt_timeout`, `abort_failed`, `abort_timeout`, and `turn_failed`. Timeout messages are stable: `Pi prompt preflight timed out` and `Pi abort timed out`.
 
 Invalid execution-profile configuration prevents startup, so it cannot be an MCP response. In that case stderr receives a structured, sanitized `startup_failed` diagnostic with one of these stable codes; it contains no raw parser message or configuration path.
 
 | Startup diagnostic code | Meaning |
 | --- | --- |
+| `config_path_required` | `PI_SESSION_MCP_CONFIG` is not set or empty; there is no default configuration file. |
 | `invalid_execution_profile_config` | The execution-profile configuration violates its invariants or strict shape, including `grantedExtensionTools` on a coding profile or a profile without extensions, more than 32 grants, duplicate, unsafe, MCP-reserved or built-in grant names, an unknown or duplicate selected skill alias, two selected skill aliases with the same path, or an invalid `skillCatalog` entry (including a malformed `builtin:` name). |
 | `invalid_thinking_level` | A configured thinking level is outside the supported enum. |
 | `invalid_execution_modes` | The execution modes file is invalid or unreadable, including an unknown alias, an unrecognized shape, or an invalid container profile selection. |

package/package.json

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

package/skills/pi-session-orchestration/SKILL.md

@@ -10,7 +10,7 @@ You control Pi worker sessions through the pi-session-mcp tools. You choose only
 ## 1. Discover first
 
 - Call `pi_capabilities_get` before anything else in a run. Use only the workspace and profile aliases it lists. Never invent an alias or pass a path.
-- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions`, `grantedExtensionTools` and `skills`. These are configuration intent only: grants name configured extension tools, not proven availability; `skills` names configured skill aliases, not proof that a session loaded the skill or that the model will read it.
+- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions`, `grantedExtensionTools`, `shell` (`sandboxed` gives a read-only profile a network-free sandbox shell, `none` no shell) and `skills`. These are configuration intent only: grants name configured extension tools, not proven availability; `skills` names configured skill aliases, not proof that a session loaded the skill or that the model will read it.
 - Capabilities do not prove that a provider or model is reachable. A successful `pi_session_start` shows that the session was created with the selected provider, model and thinking level, and that local authentication, the extensions, external MCP servers and selected skills passed their start checks. It does not prove that the provider accepts requests: credentials, quota and network show only when a turn runs.
 
 ## 2. Scope each task
@@ -110,7 +110,7 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 - `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Decide an observation and cleanup budget before you abort, for example a fixed number of polling rounds within a few minutes. Poll `pi_turn_get` until the turn is terminal or the budget is spent, then close the session with `pi_session_close`. If the close fails or does not finish, stop using that workspace, treat it as unverified and report it. Never wait without a bound.
 - If `pi_session_start` fails, classify the error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Read [references/start-errors.md](references/start-errors.md) only now; it lists each known code in exactly one class. Any code not listed there is Unknown. Until the code is classified, do not retry and do not switch profiles. If the reference cannot be read, do not retry at all: report the code and stop that task. Always report the code.
 - `writer_unavailable` is a capacity/state signal, not a reason to switch profiles. Wait for sessions/cleanup or collect and finish writers; use its structured reason and counts as described in the error reference. A lost writer session must be closed and its work inspected before a fresh start.
-- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`invalid_execution_profile_config`, `invalid_thinking_level`, `invalid_execution_modes`, `invalid_event_delivery` or `event_spool_unavailable`). No MCP server is available; the operator must fix the configuration.
+- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`config_path_required`, `invalid_execution_profile_config`, `invalid_thinking_level`, `invalid_execution_modes`, `invalid_event_delivery` or `event_spool_unavailable`). No MCP server is available; the operator must fix the configuration.
 
 ## 10. Close every session
 

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`, `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.
+- 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`, `writer_fenced`, `container_runtime_unavailable`, `server_stopping`. Writer readiness needs repository setup and acceptance; a fenced writer needs the operator to confirm that its container is gone; 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.