pi-session-mcp 0.13.1 → 0.14.1

package/docs/execution-modes.md

@@ -182,10 +182,24 @@ pi-session-mcp-setup --writer my-project-w1 --finish --apply
 
 Collection exports changed branches via a bundle into the operator's checkout as
 `refs/remotes/writer-<name>/<branch>`. Uncommitted/untracked work is captured as a
-synthetic `<branch>-wip` commit. These refs are **untrusted until reviewed**;
+synthetic `<branch>-wip` commit. A clean detached HEAD whose commit no branch in
+the clone reaches is exported as `<base>-detached` (for example `main-detached`,
+imported as `refs/remotes/writer-<name>/main-detached`); a dirty detached HEAD
+keeps the `<base>-wip` export. A `<base>-detached` or `<branch>-wip` name that
+an exported branch already takes, or that conflicts with an exported branch's
+path (such as a branch `main-detached/topic`), is refused and makes collection
+incomplete (`writer_collect_incomplete`); the other branches are still
+exported. Clone-side Git ignores replace refs. These refs are **untrusted until reviewed**;
 setup does not merge or cherry-pick them. Collection does not change the clone.
-Only a complete export records a digest authorizing later destructive cleanup;
-new work invalidates that authorization. Stashes are not exported as branches:
+Only a complete export records a digest authorizing later destructive cleanup,
+and the digest is recorded only when the clone's HEAD commit and every branch
+commit exist in the operator checkout; otherwise collection is incomplete
+(`writer_collect_incomplete`) and no digest is recorded. This includes the base
+commit: if the operator checkout no longer has it (for example after a deleted
+base branch and garbage collection), collect and finish fail this way even on a
+pristine writer, without refused names; fetch the base again or resolve with
+`--reset --discard --apply`. New work invalidates
+that authorization. Stashes are not exported as branches:
 resolve any needed stash inside the boundary before collection.
 
 `--finish` collects, then resets a persistent writer or recreates an ephemeral
@@ -234,6 +248,14 @@ reset updates admission without a server restart. A missing/unusable runtime or
 stale/unready writer launches a refusal MCP server: all eight tools return the
 sanitized refusal, with no host fallback. See [Tool contracts](tool-contracts.md).
 
+Before the relay starts an inner session it compares every public capability
+field of the writer's profile with the host profile: `permissionProfile`,
+`provider`, `model`, `thinkingLevel` and `shell` exactly, and `skills`,
+`extensions` and `grantedExtensionTools` as sets. A mismatch or a missing
+entry counts as `settingsChanged`, starts no inner session and moves on to the
+next writer; if no writer is admitted, the start fails with
+`writer_unavailable` and reason `none_admitted`.
+
 ## Reports and finding codes
 
 Reports use sanitized targets `modes/workspace/<alias>` or `writer/<alias>/<name>`

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

package/docs/isolation-setup.md

@@ -225,12 +225,18 @@ Git metadata can redirect reads to worker-controlled configuration. Setup checks
 clone layout and runs clone-side Git only in throwaway no-network containers.
 Collect with `--writer <name> --collect --apply`, then review
 `refs/remotes/writer-<name>/<branch>` in your own checkout, with dirty work at
-`<branch>-wip`. Imported refs are untrusted until reviewed.
+`<branch>-wip` and a clean detached HEAD at `<base>-detached` (for example
+`main-detached`). Imported refs are untrusted until reviewed.
 
 After taking over the result and closing its coding session, run
 `pi-session-mcp-setup --writer <name> --finish --apply` before another task.
 It collects then resets (persistent) or recreates (ephemeral). If any branch name
-was refused, collection is incomplete and finish stops. Rename inside the writer
+was refused, collection is incomplete and finish stops; a `<base>-detached` or
+`<branch>-wip` name that an exported branch takes or whose path it conflicts
+with is refused the same way. The release digest is
+recorded only when the clone's HEAD commit and every branch commit exist in the
+operator checkout, otherwise collection is `writer_collect_incomplete` and no
+digest is recorded. Rename inside the writer
 or have the operator explicitly resolve loss with `--reset --discard --apply`.
 Finish returns persistent and ephemeral writers to the workspace default base.
 No reconnect is needed after finish, reset or recreate: each session starts a

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,24 @@ 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).
+- 2026-10-30: [Sprint 12](sprints/2026-10-29-s12-audit-fixes.md) fixes three
+  audit findings on `9d9cf8c` in one pull request, released in patch release
+  0.14.1: read-only context files confined to the workspace
+  ([#192](https://github.com/plagor44-ux/pi-session-mcp/issues/192)), detached
+  `HEAD` collection and the release-digest gate
+  ([#193](https://github.com/plagor44-ux/pi-session-mcp/issues/193)) and the
+  full writer profile comparison in the relay
+  ([#194](https://github.com/plagor44-ux/pi-session-mcp/issues/194)). Levels 1
+  to 3 passed for the candidate. #120 still waits for a Pi SDK release.
 
 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/sprints/2026-10-24-s8-writer-migration.md

@@ -4,9 +4,11 @@ Planning basis: main `47b8d26` (Sprint 7 merged), installed release 0.11.2.
 Tracking: [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79),
 prerequisite [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121).
 
-Status: **planned**. The maintainer made the choices on 2026-10-25; see
-[Decisions](#decisions-2026-10-25). Nothing below has been changed on any
-machine yet.
+Status: **in progress** — steps 1–4 are done (pilot `pi-session-mcp`,
+`node-app`, the operator images, go-app) and steps 5–7 are open; see
+[Progress (2026-10-27)](#progress-2026-10-27) and the v0.11.6 and v0.11.8
+post-release evidence in [Acceptance](../acceptance.md). The maintainer made
+the choices on 2026-10-25; see [Decisions](#decisions-2026-10-25).
 
 ## Mandate
 

package/docs/sprints/2026-10-29-s12-audit-fixes.md

@@ -0,0 +1,172 @@
+# Sprint 12: audit findings F1–F3
+
+Planning basis: main `9d9cf8ca49e6e34dc16be6846b9324ad26ad92b9` (merge of PR
+#191), published 0.14.0, 2026-10-29. Entry: an external audit of that commit
+reported three defects with reproductions. This file plans the work and records
+it as it lands; it claims nothing that its progress log does not state with
+evidence.
+
+Branch: `fix/s12-audit-findings`, one pull request, no release.
+
+## Preflight (2026-10-29)
+
+- main and `origin/main` at `9d9cf8c`; open issues #79, #120, #144; no open
+  pull requests; clean operator checkout; no other worktree in use.
+- Doctor: no errors; only the known `workspace_gitfile` and
+  `workspace_mode_unset` warnings of the host worktree aliases.
+- Level 1 on `9d9cf8c` in a clean detached worktree on the workstation:
+  `npm ci`, `npm run typecheck`, `npm run build:cli`,
+  `NODE_OPTIONS=--unhandled-rejections=strict npm test` (527 files, 4005
+  passed, 14 skipped, 0 failed, no unhandled error) and `npm run build` all exit
+  0. The audit's cloud run of the same commit reported 70 failed tests and four
+  unhandled errors; they do not reproduce here, so they are not attributed to
+  the product. The audit environment is not available to separate them further.
+- Both `pi-session-mcp` writers were at `baseline` on an older main and were
+  reset without `--discard` to `9d9cf8c` (`writer_reset`).
+
+## Findings, re-checked on `9d9cf8c`
+
+| Id | Issue | Reproduction by the controller | Result |
+| --- | --- | --- | --- |
+| F1 | [#192](https://github.com/plagor44-ux/pi-session-mcp/issues/192) | Synthetic workspace whose `AGENTS.md` links to an outside marker file; `PI_CODING_AGENT_DIR` isolated; faux provider | Confined `read` refuses; `getAgentsFiles()` contains the marker; the real `SdkPiSessionAdapter` sends it as `project_instructions` to the faux provider. Confirmed. |
+| F2 | [#193](https://github.com/plagor44-ux/pi-session-mcp/issues/193) | Real Git; boundary scripts run by an injected runner | Detached `HEAD` commit, clean tree: remove before collect `writer_uncollected`; collect `nothing_to_collect`, 0 refs, digest stored; commit absent from the operator checkout; finish `writer_reset`; remove `writer_removed`. Feature-branch counterproof exports the commit. Confirmed; not yet a Podman result. |
+| F3 | [#194](https://github.com/plagor44-ux/pi-session-mcp/issues/194) | Real relay over stdio, fake writer server fixture | Identical profiles admitted; model drift refused with `settingsChanged`; host `skills: ["pi-session-implementation"]` against inner `skills: []` admitted. Confirmed. |
+
+## Decisions taken at planning
+
+- F1: for read-only profiles every resource loader keeps only context files
+  whose real path lies inside the workspace's real path. Context files of
+  ancestor directories above the workspace, including a main repository above a
+  linked worktree, are no longer loaded for read-only profiles: they are outside
+  the read roots of ADR 0013. Coding profiles keep the SDK's behaviour.
+- F2: smallest fix inside the existing collection contract; the export name for
+  a detached `HEAD` is a documented behaviour addition, no new public code.
+- F3: the relay compares every public capability field a writer reports, with
+  set semantics for skills, extensions and granted extension tools.
+- #120: still waiting for an SDK release (see below); no override, no
+  `npm audit fix --force`.
+- No release on this branch.
+
+## Roles and routing
+
+`pi_capabilities_get` and `--list-models` on 2026-10-29 settle which requested
+models exist as authenticated profiles:
+
+| Requested | Profile used | Status |
+| --- | --- | --- |
+| GPT 6.1 Sol | `code` (openai `gpt-6.1-sol`) | available |
+| GPT 6.1 Terra | none | unavailable: the catalog lists no `gpt-6.1-terra`; not substituted with another version |
+| DeepSeek | `code-deepseek` (`deepseek-flash`) | available |
+| GLM 5.3 | `review-glm`, `code-glm` (`zai-glm-5-3`) | available |
+| Mistral Large 4 | `code-mistral` (`mistral-large-4`) | available |
+| Sonnet 5.5 | no profile; provider `anthropic` authenticated | added only in an expendable test configuration (acceptance item D) |
+| Grok 4.7 | `review-grok` (xai `grok-4.7`) | available: the R2 turn completed |
+
+agy (Antigravity CLI, Gemini) plans the work packages, dependencies and review
+routing; Pi workers implement and review; the controller integrates, verifies
+and is the only editor of this file, the roadmap, `docs/acceptance.md` and the
+CHANGELOG.
+
+## Tasks
+
+| Id | Task | Route | Change area |
+| --- | --- | --- | --- |
+| P1 | Work packages, dependencies, review routing | agy | none |
+| P2 | Independent regression test plan | `review-glm` | none |
+| T1 | F1, #192 | `pi-session-mcp` writer, `code` | `src/sdk-pi-adapter.ts`, `src/confined-tools.ts`, tests |
+| T2 | F2, #193 | `pi-session-mcp` writer, `code-mistral` (agy's fallback for the unavailable Terra) | `src/writer-lifecycle.ts`, tests |
+| T3 | F3, #194 | `pi-session-mcp` writer, `code-deepseek` | `src/writer-relay.ts`, `src/capabilities.ts`, tests, relay fixture |
+| R1 | Security review of T1 and T3 | Sonnet 5.5, read-only | none |
+| R2 | Adversarial review of T2 and the Git lifecycle checks | `review-grok` | none |
+| D1 | Documentation and issue reconciliation (#120, ADR 0014 status, Sprint 8 status, #79, #144) | `pi-session-mcp` writer, `code-mistral`; controller as editor | `docs/`, `skills/pi-session-orchestration/SKILL.md` |
+| A | Live acceptance A–E | controller | evaluation record |
+
+## Progress log
+
+Recorded as work lands on the branch.
+
+- 2026-10-29: issues #192, #193 and #194 filed; this plan written before any
+  implementation.
+- P1: agy (`gemini-3.8-flash-high`, plan mode) proposed the packages,
+  `code-mistral` as the F2 author in place of Terra, Sonnet for R1 and Grok
+  with a fallback for R2, and at most three review rounds. Adopted.
+- P2: `review-glm` wrote the regression test plan; its edge cases (absent
+  against empty set fields, real-Git collection, a Podman case) went into the
+  task prompts.
+- T3 (`code-deepseek`, writer w2): collected as
+  `writer-pi-session-mcp-w2/fix/f3-relay-profile-drift`; the controller ran the
+  new tests against the old source (7 fail) and the fix (all pass); integrated
+  as `230e60e`, writer finished (`writer_reset`).
+- T1 (`code`, writer w1): collected as
+  `writer-pi-session-mcp-w1/fix/f1-context-files`; new tests against the old
+  source 9 of 12 fail, with the fix 148 of 148 pass; integrated as `a0a7d87`,
+  writer finished. The container-writer suite showed only the eight known
+  lock and hook timeouts (`override-lock`, `skill-customize-concurrency`,
+  `wake-hook`).
+- R1 (Sonnet 5.5, read-only, through the test configuration of item D):
+  `NON_BLOCKING_ONLY`. Fixed by the controller: kept context files are read
+  again from their verified real path (`79e8a7a`), the set comparison is
+  symmetric with a duplicated-entry test (`3e14279`); the shadowing case is
+  covered by a test and documented. Not changed: synchronous `realpathSync` in
+  the loader override (the SDK hook is synchronous) and the trust in the
+  writer's own capability report, which is the boundary the relay already
+  assumes.
+- T2 (`code-mistral`, writer w2): collected as
+  `writer-pi-session-mcp-w2/fix/f2-detached-collect`; the new real-Git tests
+  against the old source 3 of 8 fail, with the fix 8 of 8 pass, and the F2
+  reproduction now gets `writer_collected`; integrated as `236ca28`, writer
+  finished. The controller added the Podman case (`6ee7add`): with real
+  rootless Podman and the pinned Node image it passes, against the old source
+  it fails.
+- D1 (`code-mistral`, writer w1): collected as
+  `writer-pi-session-mcp-w1/docs/s12-reconcile`; split by issue into
+  `f5a9712`, `58e0e7b`, `17845ff` and `ebe3c52`. Controller edits: the
+  shadowing and re-read rule in the ADR 0013 amendment, and the relay wording
+  (a mismatch counts as `settingsChanged`; `writer_unavailable` with
+  `none_admitted` only when no writer is admitted). Writer finished.
+- R2 (`review-grok`, Grok 4.7, read-only): `NON_BLOCKING_ONLY`. Verified by
+  the controller and fixed in `1dfe4da`: a derived `-wip` or `-detached` name
+  that conflicts with an exported branch path aborted the export under
+  `set -eu` (reproduced with a branch `main-detached/topic`); a worker-made
+  `git replace --graft` made an unexported detached commit look reachable
+  (Grok's variant with a plain replacement did not reproduce, the graft did);
+  the reachability gate now also runs on `nothing_to_collect`. Recorded as
+  limits, not changed: an index-only staged change that the worktree reverted
+  (pre-existing), a base name of 192 to 200 characters (fails closed), and a
+  runner that reports a fetch it did not do (outside the threat model).
+- Final integration review (Sonnet 5.5, read-only, on `896e29d`):
+  `NON_BLOCKING_ONLY`. Fixed: the in-boundary guard probe now ignores replace
+  refs too (`9426682`, with a test that fails without it), the BOM pattern is an
+  escape (`5d9f15b`), and execution modes names the pruned-base case of the
+  digest gate. Not changed: `inspectWork.head` stays optional because required
+  would break type-checked mocks outside this change.
+- Acceptance: see
+  [Sprint 12 candidate acceptance](../acceptance.md#sprint-12-candidate-acceptance-2026-10-30).
+  Level 1 green on `9426682`; Level 2 green on the packed `896e29d`; live items
+  B, C and D passed on expendable configurations and were rolled back; the
+  Level 3 ten-task cycle 2 passed (10 of 10) after cycle 1 failed on fixture and
+  harness design (5 of 10, kept unchanged).
+
+## Results
+
+| Finding | Status | Commits | Evidence |
+| --- | --- | --- | --- |
+| F1 #192 | fixed | `a0a7d87`, `79e8a7a`, `5d9f15b`; docs `f5a9712` | `test/read-only-context-files.test.ts` (fails on `9d9cf8c`), faux-provider context check, R1 and final review |
+| F2 #193 | fixed | `236ca28`, `6ee7add`, `1dfe4da`, `9426682`; docs `58e0e7b`, `896e29d` | real-Git collect tests, Podman test, guard test (each fails on the source before), R2 and final review |
+| F3 #194 | fixed | `230e60e`, `3e14279`; docs `17845ff` | `test/writer-relay.test.ts` drift tests (fail on `9d9cf8c`), live refusal with `settingsChanged`, R1 and final review |
+
+Remaining risk: #120 is unchanged. `npm audit --omit=dev` on 2026-10-29 still
+reports `undici` 8.10.2 (high) through `@earendil-works/pi-coding-agent` 1.4.0
+(moderate), eight advisories fixed in `undici` >= 8.12.2; the only offered fix
+is a semver-major downgrade. No override and no `npm audit fix --force`.
+
+Kept open: #79 (Sprint 8 steps 5 to 7 are not done), #120 and #144 (no macOS
+claim). The sandbox resource limits of ADR 0013 are the follow-up issue
+[#195](https://github.com/plagor44-ux/pi-session-mcp/issues/195), not part of
+this sprint.
+
+Cleanup: all controller Pi sessions closed; both `pi-session-mcp` writers
+finished (`writer_reset`); the test writer `s12-probe-w1` removed; expendable
+configurations, the synthetic repository, the pack prefix and the
+controller's worktrees removed.
+

package/docs/threat-model.md

@@ -16,7 +16,16 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   (arguments the SDK would rewrite, such as a leading `@` or `~`, a `file:`
   URL, Unicode spaces or NUL, are refused so both resolve the same path), and
   the `*Operations` hooks of `read`, `grep` and `ls` check the absolute path
-  again. `rg` and `fd` do not follow symlinks during traversal. A profile with
+  again. `rg` and `fd` do not follow symlinks during traversal. For read-only
+  profiles the resource loader likewise keeps only Pi context files
+  (`AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD`)
+  whose real path lies inside the workspace's real path, on every reload and
+  before the first provider request: a symlinked context file that resolves
+  outside the workspace, a dangling one and the context files of ancestor
+  directories above the workspace (including a main repository above a linked
+  worktree) are not loaded, while the linked worktree's own file inside the
+  workspace is. Coding profiles keep the SDK behaviour (the working directory
+  and its ancestors). A profile with
   `shell: "sandboxed"` also gets `bash`, run as `/usr/bin/bwrap` (fixed path,
   root-owned and not group- or world-writable, no `PATH` lookup) with
   `--unshare-all`, `--disable-userns`, a cleared environment, no network, `/usr`

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.1" },
   "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.1",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [

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

@@ -122,7 +122,7 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 
 After taking over the result and closing its coding session, before the next task:
 
-1. Run `pi-session-mcp-setup --writer <name> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs/remotes/writer-<name>/<branch>`, with uncommitted work as `<branch>-wip`. They are untrusted until reviewed. Integrate only verified work yourself.
+1. Run `pi-session-mcp-setup --writer <name> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs/remotes/writer-<name>/<branch>`, with uncommitted work as `<branch>-wip` and a clean detached HEAD as `<base>-detached`. They are untrusted until reviewed. Integrate only verified work yourself.
 2. Run `pi-session-mcp-setup --writer <name> --finish --apply`. It collects again, then resets a persistent writer or recreates an ephemeral writer. Do not reuse it until this succeeds. A refused branch name makes collection incomplete and finish stops: ask the operator to resolve it by renaming inside the boundary or explicitly discarding with `--reset --discard --apply`. Finish returns it to the workspace default base. No reconnect is needed after reset, finish or recreate. A setup operation on a writer held by a session fails with `writer_busy` after a short wait; close the session and allow launcher cleanup to finish.
 3. A coding start needs the writer's clone at its baseline, even after a complete collection; otherwise it fails with the controller-action code for uncollected work in [references/start-errors.md](references/start-errors.md). To let a fresh session continue from collected work, for example after a failed turn or for a review fix round, create a local branch at the collected ref and run `pi-session-mcp-setup --writer <name> --reset --base <branch> --apply`, then call `pi_session_start` on `pi-session-mcp` with the coding profile and `base: "<branch>"`. Read `writer` from that result for collection. Default starts cannot use a writer moved to the fix branch.
 4. Never run Git inside the writer's clone as the host user, including direct fetch from that clone. Use setup's bundle collection and inspect the imported refs in your own checkout. Never discard unreviewed work just to admit the next task.