pi-session-mcp 0.13.0 → 0.14.0

package/docs/roadmap.md

@@ -18,11 +18,29 @@ 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, released in
+  patch release 0.13.1:
+  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.
+- 2026-10-29: agent-driven execution-profile setup
+  ([#139](https://github.com/plagor44-ux/pi-session-mcp/issues/139)), released in
+  minor release 0.14.0 together with the refusal of controller skills as worker
+  skills ([#188](https://github.com/plagor44-ux/pi-session-mcp/issues/188)):
+  the offline model catalog `pi-session-mcp-setup --list-models`, the opt-in
+  provider probe `--probe-profile <alias> --apply` (one fixed PONG turn per
+  profile), and the shipped controller skill `pi-session-profiles`, with which a
+  controlling agent creates, changes or retires profiles without a guided
+  dialog. Recorded in [ADR 0014](adr/0014-profile-probe-and-model-catalog.md).
 
 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/skills.md

@@ -8,12 +8,12 @@ its system prompt. The model may read the file when a task matches the skill's
 description. Pi Session MCP lets the operator register skill files in a catalog
 and select them per execution profile. MCP callers never choose skills.
 
-The package ships three skills and keeps them in a skill library together with
-the operator's own overrides. `pi-session-mcp-setup --apply` also installs the
-controller skill into Claude Code and Codex. Nothing needs to be linked by hand.
+The package ships four skills and keeps them in a skill library together with
+the operator's own overrides. `pi-session-mcp-setup --apply` also installs both
+controller skills into Claude Code and Codex. Nothing needs to be linked by hand.
 Sections: [Configuration](#configuration), [The skill library](#the-skill-library),
 [Customize and add skills](#customize-and-add-skills), [Install the
-orchestration skill into Codex and Claude Code](#install-the-orchestration-skill-into-codex-and-claude-code)
+controller skills into Codex and Claude Code](#install-the-controller-skills-into-codex-and-claude-code)
 and [Upgrade from 0.8.0](#upgrade-from-080).
 
 ## Configuration
@@ -96,6 +96,11 @@ Doctor reports `config_invalid`. Stderr shows the stable startup code
   for example two aliases for `builtin:pi-session-review`;
 - a catalog value that violates the rules above (including a malformed
   `builtin:` name), or more than 64 entries;
+- a catalog value `builtin:pi-session-orchestration` or
+  `builtin:pi-session-profiles`, selected or not: the catalog serves Pi
+  workers, and the controller skills are for the controlling agent only. Doctor
+  reports `skill_controller_selected` for `configuration:skillCatalog.<alias>`
+  instead of `config_invalid`;
 - more than 16 selected aliases.
 
 ## The skill library
@@ -143,7 +148,7 @@ The shipped example configuration registers the two worker skills with
 
 ### Shipped skills
 
-The package ships three skills under `skills/`. Each has one canonical copy and
+The package ships four skills under `skills/`. Each has one canonical copy and
 frontmatter with only `name` and `description`.
 
 | Skill | For | Use |
@@ -151,6 +156,7 @@ frontmatter with only `name` and `description`.
 | `pi-session-implementation` | A Pi worker | One bounded implementation task and a fixed final report. Register it as `builtin:pi-session-implementation` and select it on coding profiles. |
 | `pi-session-review` | A Pi worker | A review of a fixed target with findings and evidence. Register it as `builtin:pi-session-review` and select it on read-only profiles. |
 | `pi-session-orchestration` | The controlling Claude Code or Codex agent | How to run Pi worker sessions through this server. `setup --apply` installs it into the clients. It is not a Pi worker skill: do not select it in a profile. |
+| `pi-session-profiles` | The controlling agent | Create, change, tune, rename or retire execution profiles and change container repository profile selections. Uses the offline model catalog and a bounded profile probe, preserves writer work, and reports evidence. `setup --apply` installs it into clients; do not select it in a Pi worker profile. |
 
 The worker skills ask for concise final reports: status, actual changed paths,
 checks with exit codes, failures, blockers, risks and repository-relative
@@ -287,18 +293,19 @@ equals a shipped skill replaces that skill instead of adding one.
 Where `setup` is unsupported, create an override by copying a shipped skill
 directory by hand. Doctor does not track a copy that has no recorded base.
 
-## Install the orchestration skill into Codex and Claude Code
+## Install the controller skills into Codex and Claude Code
 
-The orchestration skill is for the controlling agent, not for a Pi worker.
-`pi-session-mcp-setup --apply --target <target>` installs it after the
-registration, as a real copy of the effective skill: your override if you have
-one, else the shipped skill. Clients discover it without further steps.
+`pi-session-orchestration` and `pi-session-profiles` are for the controlling
+agent, not for a Pi worker. `pi-session-mcp-setup --apply --target <target>`
+installs both after the registration, as real copies of the effective skills:
+your per-skill override if present, else the shipped skill. Clients discover
+them without further steps.
 
-| Target | Skill directory |
+| Target | Skill directories |
 | --- | --- |
-| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
-| `claude-code:user:pi-session-mcp` and `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/pi-session-orchestration` and `~/.agents/skills/pi-session-profiles` |
+| `claude-code:user:pi-session-mcp` and `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` and `~/.claude/skills/pi-session-profiles` (shared by both scopes) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration` and `<project>/.claude/skills/pi-session-profiles`, where `<project>` is the directory in which `setup` runs |
 
 Claude Code reads personal skills in `~/.claude/skills/<name>/SKILL.md` and
 project skills in `.claude/skills/<name>/SKILL.md`
@@ -306,8 +313,9 @@ project skills in `.claude/skills/<name>/SKILL.md`
 skills in `~/.agents/skills`
 ([Codex skills](https://learn.chatgpt.com/docs/build-skills)).
 
-Every `setup` result has a second finding per target, with the same client and
-scope and the alias `pi-session-orchestration`. A skill problem never blocks
+Every eligible target has two skill findings in addition to its registration
+finding, with the same client and scope and aliases `pi-session-orchestration`
+and `pi-session-profiles`. A skill problem never blocks
 the registration, but a `divergent` or `failed` skill finding makes the overall
 status `failed` (exit 1), so it is not overlooked.
 
@@ -432,7 +440,7 @@ The directories of updates by 0.8.0 had random names. Setup never searches for
 or deletes them; you may delete them by hand. `--dry-run` and `--verify` do not
 report leftover intermediates.
 
-### Customize the controller skill
+### Customize the controller skills
 
 Never edit the installed copy: it becomes divergent. Instead:
 
@@ -441,13 +449,18 @@ Never edit the installed copy: it becomes divergent. Instead:
 3. `pi-session-mcp-setup --apply --target <target>` again. The unmodified
    installed copy is replaced (`skill_updated`).
 
+The same steps work for `pi-session-profiles`: use
+`pi-session-mcp-setup --customize-skill pi-session-profiles` to plan the copy,
+then add `--apply`, edit its override and reapply your client targets. Each
+skill has independent ownership, update, verification and removal behavior.
+
 To recover after editing the installed copy, move your edits into the override,
 delete the installed copy, and run `--apply` again.
 
 ### Scope of what setup installs
 
-Setup installs only `pi-session-orchestration` into clients. The worker skills
-are for Pi profiles and are used through `builtin:`. Controller skills of your
+Setup installs only `pi-session-orchestration` and `pi-session-profiles` into
+clients. The worker skills are for Pi profiles and are used through `builtin:`. Controller skills of your
 own belong in the clients' native skill directories; setup does not manage
 them.
 
@@ -457,8 +470,9 @@ Where `setup` does not run, copy the directory; do not link it. Copy
 `skills/pi-session-orchestration` from the installed package (in an npm
 installation `"$(npm root -g)/pi-session-mcp/skills/pi-session-orchestration"`)
 to `~/.claude/skills/` or `.claude/skills/` of a project for Claude Code, or to
-`~/.agents/skills/` for Codex. Repeat the copy after a package update; nothing
-keeps a manual copy current. Do not replace an existing skill of the same name
+`~/.agents/skills/` for Codex. Also copy `skills/pi-session-profiles` from the
+same package root into the same client skill directory. Repeat both copies
+after a package update; nothing keeps a manual copy current. Do not replace an existing skill of the same name
 without checking it first.
 
 Neither client needs a skill to call the Pi Session MCP tools; the skill only
@@ -471,8 +485,11 @@ setup](client-setup.md#run-codex-without-prompts) describes.
 
 Pi workers never discover skills on their own in Pi Session MCP. Register the
 worker skills with `builtin:` and select them on profiles, as described above.
-Do not select the orchestration skill for a Pi worker: a worker has only the
-tools of its profile and is not a controller of other Pi sessions.
+Neither controller skill can be selected for a Pi worker: a worker has only the
+tools of its profile and is not the controlling agent, so the configuration
+rejects `builtin:pi-session-orchestration` and `builtin:pi-session-profiles` as
+catalog values. A catalog entry with a plain path to a copy of a controller
+skill is not detected; do not add one.
 
 ## What happens at session start
 
@@ -583,8 +600,8 @@ to.
 Skills are operator-managed prompt content. The override directory and its
 bases file are operator-trusted configuration next to the configuration file,
 never a workspace; keep them out of every workspace and writable only by you.
-Setup copies the effective orchestration skill into the clients' skill
-directories, where it becomes instructions for the controlling agent, so review
+Setup copies the effective controller skills into the clients' skill
+directories, where they become instructions for the controlling agent, so review
 an override like code. In a `coding` profile a skill's
 instructions are executed with that profile's tools, so review a skill like
 code. A skill grants no rights: the tools of the permission profile stay the

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.14.0" },
   "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.14.0",
   "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.

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

@@ -0,0 +1,124 @@
+---
+name: pi-session-profiles
+description: Use when you, as the controlling agent, create, change, tune, rename or retire an execution profile, or change which profiles a container repository selects. Covers inventory, candidate validation, a bounded provider probe, safe writer replacement and reporting. Do not use inside a Pi worker session.
+---
+
+# Managing execution profiles
+
+Carry out the request on this machine without asking for approval at each step.
+A skill grants no rights. Use the documented configuration and writer rules,
+not guessed providers, models or workarounds.
+
+Find the installed package root as described in
+[docs/skills.md](../../docs/skills.md). Read the relevant package-relative
+documentation before changing anything:
+[docs/installation.md](../../docs/installation.md),
+[docs/skills.md](../../docs/skills.md),
+[docs/execution-modes.md](../../docs/execution-modes.md) and
+[docs/pi-extensions-design.md](../../docs/pi-extensions-design.md). Resolve these names from the package root, not from a client-installed skill
+copy. They define profile fields, skill selection, extensions, sandbox shell
+and container acceptance.
+
+## 1. Find the configuration
+
+Use `PI_SESSION_MCP_CONFIG` from the environment without printing its value.
+If unset, read that variable from the client's own registration of the
+`pi-session-mcp` server. If neither supplies it, ask the operator. Never guess
+the configuration path.
+
+## 2. Inventory
+
+Run `pi-session-mcp-doctor --json` and
+`pi-session-mcp-setup --list-models`. Read the configuration and the adjacent
+`execution-modes.json`. Call `pi_capabilities_get` if the MCP server is
+connected. Report unrelated Doctor errors; do not fix them as part of this task.
+
+Never read Pi credential or model files. Never print environment values.
+The offline catalog reports authentication presence, not credentials, and does
+not list providers registered only by extensions.
+
+## 3. Work out the change
+
+Translate the request into concrete profile entries and the intended profile
+selection of affected container repositories. Pick providers and models only
+from `--list-models` entries with configured authentication. Prefer the shape
+of an existing working profile of the same kind. Ask only if the request leaves
+an outcome-changing choice that the catalog and existing profiles do not settle;
+otherwise decide and state the decision in the report. Select only worker
+skills for a profile; the controller skills are never catalog entries, and
+Doctor refuses them with `skill_controller_selected`.
+
+Before deleting a profile, check every container repository's selection. If any
+still selects it, stop and ask. Deleting an unselected profile needs no stop.
+
+## 4. Build and check a candidate
+
+Write a distinctly named candidate beside the live configuration, in the same
+directory and with the same file mode. Edit only the candidate. This preserves
+relative-path resolution, the modes file and the skill override directory.
+Point `PI_SESSION_MCP_CONFIG` at the candidate without echoing it, then run
+`pi-session-mcp-doctor --json` and
+`pi-session-mcp-setup --probe-profile <aliases>` (dry run), naming the changed
+or new profiles. Fix and repeat. For affected container selections,
+`container_profile_refused` must be absent.
+
+Never hand-edit `execution-modes.json`; use the documented mode request.
+
+## 5. Probe the candidate
+
+With the configuration variable still pointing at the candidate, run
+`pi-session-mcp-setup --probe-profile <aliases> --apply`.
+Each changed or new profile gets at most one provider turn without asking.
+Failures with `providerTurn: false` cost nothing: fix them and re-probe.
+Count `providerTurn: true` even when the probe fails. Stop and ask before a
+second provider turn for the same profile, or any check costing money beyond
+one PONG probe per changed profile. Never run a quality evaluation yourself.
+Only `probe_passed` proves a profile works; never print the reply text.
+
+The probe proves the profile on the host, not its acceptance by a container
+writer. Doctor's container checks and provisioning still have to pass.
+
+## 6. Prepare writers
+
+For each container repository whose selected profiles or settings change,
+determine every writer's state using the documented read-only checks:
+Doctor's `writer_dirty` and `writer_uncollected_bundle`, and
+`pi-session-mcp-setup --writer <name> --collect` (dry run).
+If a writer to remove or re-provision has uncollected work or a dirty clone,
+stop and ask before anything goes live. Never run `--collect --apply` in this
+workflow, and never discard work to get past a refusal.
+
+Stop and report `writer_busy`, `podman_unavailable`, `registration_divergent`
+or any other refused writer step; do not work around it. For writers that
+hold no work, use `pi-session-mcp-setup --writer <name> --remove` before the
+live write. Do not run host Git inside a writer clone.
+
+## 7. Go live
+
+Back up the live configuration as a timestamped copy beside it, with the same
+file mode. Replace the live file atomically by renaming the candidate onto it.
+Point the configuration variable back at the live file and run
+`pi-session-mcp-doctor --json`.
+
+## 8. Provision
+
+For each affected container repository, repeat the mode request with the full
+intended settings, not just changed fields:
+`pi-session-mcp-setup --repo <alias> --mode container --profiles <aliases> --apply`.
+This writes `execution-modes.json` and provisions writers. Preserve all intended
+settings from the inventory as `docs/execution-modes.md` requires. Then run
+`pi-session-mcp-setup --writer <name> --verify` for each writer and the documented
+client-target verification for the host registration. Stop and report any
+refused writer step instead of bypassing it.
+
+## 9. Report
+
+Report changed profile aliases and field names, Doctor results, probe results,
+usage or `unknown`, the number of provider turns, writer actions and the
+backup's file name relative to the configuration directory. Include no secrets,
+absolute paths, environment values or complete prompts.
+
+Running controllers see the changes only after their MCP server restarts or an
+MCP reconnect starts a new server process. If the operator's own instructions
+require further steps beyond this machine, follow those instructions; do not
+invent multi-machine actions.