pi-session-mcp 0.13.1 → 0.14.0

package/docs/roadmap.md

@@ -23,7 +23,8 @@ mean they are implemented or that their gates passed.
   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:
+- 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))
@@ -31,6 +32,15 @@ mean they are implemented or that their gates passed.
   ([#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/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/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.1" },
+  "server": { "name": "pi-session-mcp", "version": "0.14.0" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"

package/package.json

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

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.