pi-session-mcp 0.13.0 → 0.14.0

package/docs/acceptance.md

@@ -112,7 +112,9 @@ env -i HOME="$DISPOSABLE_HOME" PATH="$PATH" PI_SESSION_MCP_CONFIG="$ACCEPTANCE_C
   `skill_already_equivalent`, `skill_verified`, `skill_removed`,
   `skill_installed`, `skill_verified`, `skill_removed`); the skill file exists
   after steps 3 and 7 and is gone after steps 6 and 9; a foreign skill placed
-  in the same skill directory stays unchanged throughout.
+  in the same skill directory stays unchanged throughout. From 0.14.0 on
+  (#139), that holds for both controller skills, `pi-session-orchestration`
+  and `pi-session-profiles`, each with its own finding in that order.
 - Steps 1 and 2 leave the client state unchanged.
 - After step 9 the `pi-session-mcp` registration is absent, the sentinel is still
   present, and the ownership record set is empty. The ownership directory has
@@ -2457,6 +2459,257 @@ 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 post-release evidence
+
+Recorded on 2026-10-29 for the published release `0.13.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.13.1` (tag object
+`57c0786f1db3f732db797c8204e338ce17cf7fb2`) peels to the merge commit
+`c25c7687ecb66043a001c689c64e77be3cd25952` of #185, and
+`git describe --tags --exact-match` reports `v0.13.1`. CI on the merge commit
+(run 40832546742) and on the tag (run 40833087074) passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 07:32 to 07:34 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (136 files, 3948 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.1` and exited with `2` because no
+  configuration was set (`config_missing`). The manifests were unchanged
+  afterwards.
+- `pi-session-mcp@0.13.1` on npm: 922 files, shasum
+  `e2e0e2652a2cab6bf891e61bcfa14754258eb59b`, `gitHead` `c25c768` (the merge
+  commit). It was staged and approved by the maintainer; `npm pack` of the tag
+  clone and the dry run of the publishing clone give the same shasum and file
+  count.
+- Published npm package, Level 2 from a fresh prefix, 07:34 to 07:36 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.1`.
+- The GitHub release `v0.13.1` was published the same day.
+
+Operator upgrade of the workstation from `0.13.0` to `0.13.1` on 2026-10-29
+from 09:35 UTC, following
+[Installation](installation.md#container-writers): no writer container ran at
+the start; controller sessions without a coding session stayed open and need a
+reconnect. Both client targets were removed with `0.13.0`, then
+`npm install -g pi-session-mcp@0.13.1`. Doctor reported only
+`writer_not_ready` for the 18 writers. A dry run of each provisioning command
+with unchanged settings reported `mode_unchanged` and `writer_planned`; with
+`--apply`, five container repositories with 18 writers (2 with
+`--tags reachable`, 4, 4 with `--cache go`, 4 with base `dev`, 4 with
+`--cache uv`, three of them with operator images) reported `writer_accepted`
+from 09:36 to 09:39 UTC. 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, only the known `workspace_gitfile` and
+`workspace_mode_unset` warnings of the worktree aliases.
+
+Operator upgrade of the second machine (Linux) from `0.13.0` to `0.13.1` on
+2026-10-29 from 09:47 UTC, with Node.js `24.22.0` and the same steps: no
+writer container and no server process of a client session ran at the start.
+Both client targets were removed with `0.13.0`, then
+`npm install -g pi-session-mcp@0.13.1`; Doctor reported only
+`writer_not_ready` for the 14 writers. The dry runs reported `mode_unchanged`
+and `writer_planned`; with `--apply`, four container repositories with 14
+writers (4, 2, 4 with an operator image and `--cache go`, 4 with an operator
+image) reported `writer_accepted` from 09:48 to 09:51 UTC. Client-target
+`--apply` and `--verify` passed for `claude-code:user` and `codex:user`
+(`mcp_verified`, `skill_verified`), and `--writer <name> --verify` passed for
+all 14 writers. Doctor reported no error, only `workspace_mode_unset` for one
+workspace without a mode.
+
+### v0.14.0 pre-release acceptance
+
+`v0.14.0` was accepted on 2026-10-29 from 17:56 to 18:01 UTC on its release
+candidate `6e18659`, 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 #139 ([ADR 0014](adr/0014-profile-probe-and-model-catalog.md))
+and #188. The MCP tool contract is unchanged. Setup gains `--list-models` and
+`--probe-profile`, installs a second controller skill (`pi-session-profiles`)
+and so reports one more skill finding per client target; Doctor gains the
+check `skill_controller_selected`.
+
+The first working-tree run on the earlier candidate `08fc620` failed 36 of 160
+checks: the Level 2 harness still expected one controller skill finding, so
+every step saw one finding too many. Setup itself reported the expected
+findings. The candidate `6e18659` teaches the harness both controller skills
+with the same number of checks; every result below is from that candidate.
+
+- 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
+    139 files, 4005 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` 8.10.2 finding through `@earendil-works/pi-coding-agent`
+    1.4.0, the latest SDK release, with eight advisories
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 932 files (tarball shasum
+    `4eb9b77c9484292a8533c6be0fda44ac18656787`, identical in three packs). A
+    scan of the unpacked files for private names, hosts and the maintainer's
+    home path found none.
+  - Doctor reported `packageVersion` `0.14.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.14.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 (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.
+- Live checks before the candidate, on the merged #139 code: `--list-models`
+  against a real local Pi installation reported authentication for the
+  configured providers, the probe dry run planned two profiles, and one
+  `--probe-profile <alias> --apply` returned `probe_passed` with one provider
+  turn.
+- Review: #139 had three cross-family reviews (author family OpenAI and
+  Anthropic, reviewer family GLM) and #188 one, each without blocking findings;
+  their findings were fixed or declined with a reason in #187 and #189. The
+  harness fix in this release was checked by its live run above.
+
+Not established for `0.14.0`: an agent-driven profile change end to end with
+the `pi-session-profiles` skill, a container writer acceptance of a newly
+created profile, client-target `--verify` through the installed package, which
+follows the 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/adr/0014-profile-probe-and-model-catalog.md

@@ -0,0 +1,89 @@
+# ADR 0014: Profile probe and offline model catalog
+
+**Status:** Accepted (2026-10-29); unreleased. Issue #139.
+
+## Context
+
+The running MCP server reads its configuration once at startup. A controlling
+agent cannot reconnect its own server to prove a changed execution profile.
+Asking for a manual reconnect prevents autonomous profile setup; starting a
+nested controller would add another agent without testing a different boundary.
+The agent also needs an authoritative offline catalog rather than guessing
+provider and model ids or inspecting credential files.
+
+## Decision
+
+### 1. Offline model catalog
+
+`pi-session-mcp-setup --list-models` reports provider ids, model ids and only
+whether authentication is configured. Package-root `ModelRuntime` access sits
+behind injectable `ModelCatalog`. Creation disables model network access and
+refresh (`allowModelNetwork: false`, `refreshOnCreate: false`); the catalog
+uses only `getProviders`, `getModels` and `checkAuth`. `checkAuth` reads the
+local auth configuration offline and returns only its source and kind; the
+catalog reduces that to a boolean and bounds each lookup. `hasConfiguredAuth`
+is not used because it reads a snapshot that only an online availability
+refresh fills, so offline it always reports no authentication. The catalog
+never calls `getAuth` or `getAvailable`. This is a second narrow exception
+next to the writer wrapper's credential refresh (#142), not general permission
+to bypass `PiSessionAdapter`.
+
+Providers registered only by extensions are not listed; every catalog report
+states this limitation. Invalid catalog ids are omitted, never echoed.
+
+### 2. Opt-in profile probe
+
+`--probe-profile review,code` runs Doctor and offline profile, provider, model
+and authentication-presence checks. Only adding `--apply` authorizes one fixed
+PONG turn per passing profile, sequentially, through `PiSessionAdapter`. The
+production dependency is `SdkPiSessionAdapter`, resolving the profile as the
+server does and protecting both the named and canonical configuration
+directories from read-root expansion through skills.
+
+Doctor blocks on global configuration/build/version errors and errors about
+the requested profiles. Other errors and warnings are reported by check id
+without blocking this request. Tests inject a fake catalog, adapter and Doctor;
+no provider credentials are needed.
+
+The session uses a private empty temporary directory, mode 0700, created
+internally and removed after bounded session cleanup. This is a narrow
+exception to the configured-workspace rule: the directory is not a workspace
+alias and is never supplied as a tool or CLI argument. It avoids exposing a
+real repository as the probe's working directory; it does not sandbox trusted
+extensions or change coding profiles' existing authority.
+
+Start, turn and cleanup deadlines are 60, 120 and 10 seconds respectively.
+Interrupts abort and dispose the current session and skip remaining profiles.
+The fixed prompt is not configurable, the reply text is never reported, usage
+is `unknown`, and each finding records whether a provider turn was accepted.
+No event spool is enabled.
+
+### 3. Guarded, lazy CLI entry
+
+Ordinary setup requests never import the probe entry or install its stdout
+guard. The catalog and probe load it dynamically after the platform gate;
+the catalog needs no configuration. Its first import installs the same stdout
+guard as the server before SDK evaluation. Only the guard's transport writer
+emits reports; foreign stdout, including extension `console.log`, is dropped.
+Adapter diagnostics are structured JSON on stderr without prompts or secrets.
+Operational exceptions produce fixed refusal codes rather than raw errors.
+
+## Contract change and versioning
+
+The new setup flags and report schemas are additive public CLI contract
+changes under [ADR 0003](0003-post-mvp-maintenance.md#versioning). This decision
+does not itself bump the version or authorize publication.
+
+## Consequences
+
+- Doctor and `--verify` remain provider-free. Only
+  `--probe-profile … --apply` uses a provider among setup operations.
+- Catalog and probe run on Linux and macOS without acquiring the setup lock
+  or changing registrations or configuration.
+- The probe proves the profile on the host using the host Pi agent directory.
+  Container acceptance remains Doctor's `container_profile_refused` check and
+  writer provisioning, not this probe.
+- A successful probe does not reload any running controller's configuration;
+  an MCP server restart or reconnect is still required.
+- Reports expose only sanitized findings, durations and provider-turn presence,
+  not paths, credential values, environment values, prompts or reply text.

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

@@ -53,6 +53,9 @@ npm run --silent setup -- --apply --target codex:user:pi-session-mcp
 npm run --silent setup -- --verify --target codex:user:pi-session-mcp
 npm run --silent setup -- --rollback --target codex:user:pi-session-mcp
 npm run --silent setup -- --remove --target codex:user:pi-session-mcp
+npm run --silent setup -- --list-models --json
+npm run --silent setup -- --probe-profile review,code --json
+npm run --silent setup -- --probe-profile review,code --apply --json
 ```
 
 Setup runs the previously built `dist/setup-main.js`. The dry-run operation
@@ -109,27 +112,30 @@ inspected:
 None of the failure rows changes a registration or starts the handshake, and
 each exits with `1`.
 
-### Controller skill
+### Controller skills
 
-Besides the registration, `--apply` installs the controller skill
-`pi-session-orchestration` for each target, as a real copy of the effective
-skill: your override in the skill library if you have one, else the skill
-shipped in the package ([Pi skills](skills.md)). Clients discover it without
-further steps.
+Besides the registration, `--apply` installs the controller skills
+`pi-session-orchestration` (delegating work to Pi workers) and
+`pi-session-profiles` (creating, changing and retiring execution profiles) for
+each target, each as a real copy of the effective skill: your override in the
+skill library if you have one, else the skill shipped in the package
+([Pi skills](skills.md)). Clients discover them without further steps.
 
-| Target | Where the skill goes |
+| Target | Where the skills go |
 | --- | --- |
-| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
-| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` (one shared directory) |
-| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration`, where `<project>` is the directory in which setup runs |
+| `codex:user:pi-session-mcp` | `~/.agents/skills/<skill>` |
+| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/<skill>` (one shared directory per skill) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/<skill>`, where `<project>` is the directory in which setup runs |
 
-Every result therefore has a second finding per target, with the same client
-and scope and the alias `pi-session-orchestration`:
+`<skill>` is `pi-session-orchestration` or `pi-session-profiles`. Every result
+therefore has one more finding per skill and target, with the same client and
+scope and the skill name as alias:
 
 ```text
 apply: ok
 claude-code/user/pi-session-mcp: ok (applied)
 claude-code/user/pi-session-orchestration: ok (skill_installed)
+claude-code/user/pi-session-profiles: ok (skill_installed)
 ```
 
 Skill findings per operation:
@@ -302,7 +308,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 +379,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,8 @@ 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 |
+| `skill_controller_selected` | Production `loadConfig` rejects the configuration because a `skillCatalog` value names a controller skill (`builtin:pi-session-orchestration` or `builtin:pi-session-profiles`). Reported instead of `config_invalid` for that location and blocks like it | `configuration:skillCatalog.<alias>` |
 | `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/installation.md

@@ -89,6 +89,89 @@ local user's existing Pi authentication and never prints it. Automated writers
 keep selected provider credentials in their private boundary agent copy; see
 [Execution modes](execution-modes.md#writer-storage-launch-and-readiness).
 
+## Check profiles: model catalog and probe
+
+List the providers and model ids Pi knows locally, with authentication presence
+only (never credential values):
+
+```bash
+pi-session-mcp-setup --list-models
+pi-session-mcp-setup --list-models --json
+```
+
+This is offline and read-only: no provider request, credential refresh, model
+network access or setup lock. It requires no `PI_SESSION_MCP_CONFIG`.
+Providers registered only by Pi extensions are not listed; the report includes
+that note. Invalid catalog ids are omitted and counted in `omittedIds`.
+Catalog creation failures report `catalog_unavailable`.
+
+With `PI_SESSION_MCP_CONFIG` already set to the configuration to check:
+
+```bash
+pi-session-mcp-setup --probe-profile review,code --json
+pi-session-mcp-setup --probe-profile review,code --apply --json
+```
+
+The first command is a dry run: Doctor runs offline, followed by profile,
+provider, model and authentication-presence checks. Only `--apply` sends a
+provider turn: one fixed PONG request per profile that passes the offline
+checks, sequentially. Duplicate aliases are checked once in request order.
+Point the variable at a candidate configuration to check it before going live;
+the commands do not write configuration or registrations. The running MCP
+server still needs a restart or reconnect to read changes.
+
+The Doctor gate blocks global configuration/build/version errors and errors
+whose subject is a requested profile. Unrelated errors and all warnings are
+listed by check id in `doctor.other`, without blocking. A blocked request
+reports `doctor_failed`; missing or unusable configuration reports
+`config_required` or `config_unusable`. Unexpected operational failures report
+`operation_failed`, and catalog creation failures report `catalog_unavailable`.
+No raw exception text is printed.
+
+Each applied probe starts the normal adapter with the resolved profile in a
+private empty temporary directory (mode 0700), not a real repository. This
+directory is created internally, never supplied as an argument or workspace
+alias, and removed after cleanup. Start and turn deadlines are 60 and 120
+seconds; session cleanup is bounded to 10 seconds. Interrupts abort and dispose
+the current session and skip the remaining profiles. Reports never include
+paths, credential values, environment values, the prompt or reply text.
+Foreign stdout from profiles/extensions is suppressed so JSON remains intact;
+sanitized structured diagnostics go to stderr. No turn event spool is used.
+
+| Code | Status | Meaning |
+| --- | --- | --- |
+| `probe_planned` | planned | Dry run: offline checks passed |
+| `probe_profile_unknown` | failed | Alias not in the configuration |
+| `probe_provider_unknown` | failed | Provider not in the catalog (offline) |
+| `probe_model_unknown` | failed | Model not in the provider's catalog (offline) |
+| `probe_auth_missing` | failed | Provider has no configured authentication (offline) |
+| `probe_passed` | ok | Session started, reply was `PONG` |
+| `probe_unexpected_reply` | failed | Turn completed with another reply |
+| `probe_turn_failed` | failed | Turn failed or was aborted |
+| `probe_start_failed` | failed | Session creation refused; carries the existing sanitized `PiSessionCreationErrorCode` |
+| `probe_timeout` | failed | Start or turn deadline passed; the session was aborted and disposed |
+
+A profile that fails an offline check is not started; the other profiles are
+still checked. Apply findings include `durationMs`. `providerTurn` records
+whether a provider turn was accepted, including turns that failed or timed out;
+a `false` finding did not spend a provider turn. Provider usage and monetary
+cost remain `unknown`.
+
+Exit codes: `0` for a successful catalog, a clean dry run (`planned`) or an
+apply where every profile passed; `1` for a failed check or refusal; `64` for
+invalid usage; `130` for SIGINT and `143` for SIGTERM during a probe (both
+report `operation_interrupted`). Both operations run on Linux and macOS and
+need no setup lock. Probe requests cannot be combined with `--target`,
+`--repo`, `--writer`, `--customize-skill`, `--list-models`, `--verify`,
+`--rollback` or `--remove`. `--list-models` is standalone apart from `--json` and the default `--dry-run`.
+Doctor and `--verify` remain provider-free.
+
+**Container repositories:** the probe proves the profile on the host, with
+the host's Pi agent directory. Writer acceptance stays with Doctor's
+`container_profile_refused` check and writer provisioning; a host probe does
+not prove a container writer. See [Execution modes](execution-modes.md) and
+[ADR 0014](adr/0014-profile-probe-and-model-catalog.md).
+
 ## 1. Install
 
 ### From npm
@@ -701,6 +784,10 @@ choose skills.
   directory, so concurrent runs cannot lose a recorded base.
 - A `builtin:` name with no override and no shipped skill makes Doctor report
   `skill_missing` and the session start fail with `skill_load_failed`.
+- The controller skills `pi-session-orchestration` and `pi-session-profiles`
+  are not worker skills: a `builtin:` catalog entry for either makes the
+  configuration invalid, and Doctor reports `skill_controller_selected` for
+  `configuration:skillCatalog.<alias>`.
 - An extension allowlist alone makes none of a package's skills available. If a
   profile relied on them, add a catalog entry with the absolute path of the
   package's `SKILL.md` and select it; see the migration section of [Pi