pi-session-mcp 0.7.1 → 0.8.1

package/docs/adr/0007-profile-skill-selection.md

@@ -0,0 +1,228 @@
+# ADR 0007: Execution profiles select Pi skills from an operator catalog
+
+**Status:** Accepted (2026-10-12). Issue #46. Guide: [Pi skills in execution
+profiles](../skills.md).
+
+## Context
+
+Embedded sessions are meant to run without skills. A controlling agent that
+delegates work to Pi workers needs a way to give a worker role-specific
+instructions, such as an implementation or review procedure, under the same
+rule as everything else: the operator decides, the MCP caller picks aliases.
+
+Verified behavior of Pi SDK 1.1.0:
+
+- `noSkills` does not stop skills that an allowlisted extension package
+  ships. Those skills reached the session although `noSkills` was set. The
+  same held for prompt templates and themes that packages ship. ADR 0006 did
+  not intend this and did not decide it.
+- `loadSkills` removes duplicate skill names before the SDK's `skillsOverride`
+  runs. An override alone therefore cannot report a collision between two
+  selected files, so the server has to check names itself.
+- Resources that extension hooks add later (`resources_discover`) pass through
+  the same override.
+
+ADR 0003 chose maintenance without a new feature phase and reserves public
+contract changes for a minor release with their own decision. ADR 0006 is the
+precedent for an owner-approved scope expansion. This ADR is such a decision
+for issue #46. It does not rewrite ADR 0006; that ADR records only a forward
+link.
+
+On 2026-10-12 the owner rejected installing the shipped skills by manual
+symlinking and asked for skills that can be installed at install time and
+adjusted and extended one by one. The decisions under "Skill library,
+installation and customization" below record that, in the same change.
+
+## Decision
+
+The operator may register skills in a catalog and select them per execution
+profile.
+
+- **Catalog.** An optional top-level `skillCatalog` maps a skill alias
+  (`^[a-z][a-z0-9_-]{0,63}$`, at most 64 entries) to the path of exactly one
+  `SKILL.md` (at most 4096 characters). Directories, globs, URLs,
+  scheme-prefixed sources, `~` and backslashes are invalid. The one accepted
+  scheme is `builtin:<name>` (see below). Relative paths resolve against the
+  configuration file's directory. A missing catalog is empty. A skill folder
+  needs no `package.json` and no extension.
+- **Selection.** An optional `executionProfiles.<alias>.skills` lists catalog
+  aliases (at most 16, no duplicates). Missing or empty means no skills. There
+  is no inheritance and no default skill. An unknown alias, a duplicate alias,
+  or two selected aliases that resolve to the same path is
+  `invalid_execution_profile_config`. All other profile fields are unchanged
+  and unknown fields are still rejected.
+- **MCP surface.** Callers still choose only workspace and profile aliases.
+  `pi_session_start` and `pi_session_prompt` get no skill input. No tool is
+  added.
+- **Loading.** At session start the server loads exactly the selected files
+  through the SDK's public `loadSkills`, with no default directories, and
+  validates them completely. `skillsOverride` returns exactly that set, also
+  after later resource additions by extension hooks.
+- **Failure.** A missing, unreadable or oversized (over 256 KiB) file, an
+  invalid skill (SDK diagnostics such as a missing description or invalid
+  name), two selected files with the same Pi skill name, two aliases on the
+  same canonical file (for example through a symlink), or
+  `disable-model-invocation: true` fail the start with the new error
+  `skill_load_failed` and the fixed message `Configured Pi skill could not be
+  loaded`. The message never contains a path, a skill name or SDK text. The
+  same Pi skill name in different sessions is fine.
+- **Explicit-only skills are incompatible in v1.** MCP prompts never run
+  `/skill:` commands, and Pi hides such skills from the model. The server does
+  not rewrite the flag.
+- **Names.** The catalog alias may differ from the skill's declared `name`.
+  Nothing is renamed.
+- **Capabilities.** Every execution profile in `pi_capabilities_get` gains
+  `skills: string[]`, the selected catalog aliases in configured order, `[]`
+  when none. No paths, file names, contents or SDK diagnostics. The setup
+  verifier accepts the field and still rejects unexpected fields.
+- **Doctor.** Offline, it never parses or executes a skill. New check IDs after
+  the extension checks, with the subject `<profile>:<skill-alias>`:
+  `skill_missing`, `skill_unreadable` (not a regular file, over 256 KiB, or not
+  readable) and `skill_duplicate`. Frontmatter, name rules, collisions and
+  explicit-only flags are checked only at session start. A further warning
+  check, `skill_override_outdated`, is described below.
+- **Diagnostics.** Stderr gets the new stage `skill_load` for a selected file
+  that fails validation, with an optional `skill` field holding the catalog
+  alias. A catalog that differs from the selection after construction reports
+  the existing stages `postcheck`, `extension_load` or `extension_bind`. No
+  diagnostic carries a path.
+- **Snapshot semantics.** Profile and skill selection are fixed per session.
+  The content is not snapshotted: the SDK keeps file paths and later reads may
+  see changed files. Operators manage skill files and companion files, do not
+  change them during active sessions, and close affected sessions before an
+  update. The configuration fingerprint covers configuration bytes, not skill
+  contents. There is no hot reload, watcher, copy store for sessions or
+  versioning.
+- **Shipped skills.** The package ships `pi-session-orchestration`,
+  `pi-session-implementation` and `pi-session-review` under `skills/`, one
+  canonical copy each. They are ordinary skill files. The two worker skills are
+  registered through the catalog like any operator skill, by `builtin:`. The
+  orchestration skill is for the controlling client agent and is not a Pi
+  worker skill.
+
+## Skill library, installation and customization
+
+Owner decision of 2026-10-12, same issue. The first design of this change had
+the operator register shipped skills by absolute path and link the
+orchestration skill into the clients by hand; the owner rejected that. Three
+decisions were taken:
+installation through `pi-session-mcp-setup --apply`, an override directory for
+customization, and `builtin:` references in the Pi skill catalog.
+
+- **Skill library.** Shipped skills live in the package's `skills/` directory.
+  The operator's override directory is `skills/` next to the configuration file
+  (for the default configuration `~/.config/pi-session-mcp/skills/<name>/SKILL.md`).
+  An override with the same name replaces the shipped skill; a new name adds a
+  skill. Names follow the Agent Skills rule: lowercase letters and digits in
+  hyphen-separated groups, 1 to 64 characters. Nothing else is searched.
+- **`builtin:<name>`.** A `skillCatalog` value resolves to the override if
+  `<override dir>/<name>/SKILL.md` exists, else to the shipped skill. A missing
+  skill keeps the shipped location, so Doctor reports `skill_missing` and the
+  session start fails with `skill_load_failed`. Resolution happens when the
+  server loads the configuration: adding or removing an override needs a
+  restart, like any configuration change. Edits to an existing skill file reach
+  new sessions under the snapshot semantics above. The example configuration
+  uses `builtin:pi-session-implementation` and `builtin:pi-session-review`, so a
+  copied example needs no path edits.
+- **Customization.** `pi-session-mcp-setup --customize-skill <name>` (a
+  dry-run) and `--apply --customize-skill <name>` copy a shipped skill into the
+  override directory as a starting point and record the shipped fingerprint in
+  `<override dir>/.pi-session-mcp-bases.json`. An existing override is never
+  overwritten. When the shipped skill changed after the copy, or no base is
+  recorded, the command reports `skill_override_outdated`; `--apply` then moves
+  only the recorded base (`skill_base_updated`) and never touches the
+  operator's files, which is how an operator acknowledges a reviewed change.
+  The finding target is `{ client: "skills", scope: "override", alias: <name> }`.
+  It works without `--target`, requires `PI_SESSION_MCP_CONFIG`, and follows
+  the platform rule of setup. A completely new skill needs no command: create
+  `<override dir>/<new-name>/SKILL.md` and reference it as `builtin:<new-name>`.
+- **Installation of the controller skill.** `setup --apply` installs
+  `pi-session-orchestration` for each target, after the registration, as a real
+  copy of the effective skill (override, else shipped). Codex `codex:user` goes
+  to `~/.agents/skills/`, Claude Code `user` and `local` share
+  `~/.claude/skills/`, and Claude Code `project` goes to
+  `<project>/.claude/skills/`, the directory setup runs in. Ownership records
+  hold only a content fingerprint and, while an update is pending, the
+  fingerprint it replaces; a project record is bound to an opaque project
+  identity, never a path. Setup never replaces or deletes a modified installed
+  copy, hidden operator entries inside it, a foreign skill of the same name or a
+  linked or non-directory entry; it reports `skill_divergent`, which does not
+  block the registration. A link to exactly the effective skill is the
+  operator's own equivalent setup (`skill_linked`) and is never owned. In the home directory the client's skills
+  directory may be the operator's own link and is followed. Inside a project,
+  which may be untrusted, any link below the project root makes the slot
+  divergent, so setup never writes outside the project. Setup installs only
+  `pi-session-orchestration` into clients; the worker skills are for Pi
+  profiles through `builtin:`, and controller skills of the operator's own
+  belong in the clients' native skill directories. The operator customizes the
+  controller skill through the override and runs `--apply` again, and never
+  edits the installed copy.
+- **Doctor.** The warning check `skill_override_outdated` has the subject
+  `skill:<name>` when a shipped skill's current fingerprint differs from the
+  recorded base, with a remediation that names the customize command. A
+  corrupt bases file reports the subject `skill:bases`. Doctor stays offline
+  and executes nothing.
+- **Fallback.** Where setup does not run, the operator copies the controller
+  skill directory into the client's documented skill directory. There is no
+  symlink instruction.
+
+## Compatibility change
+
+Previously, with Pi SDK 1.1.0, an allowlisted extension package's bundled
+skills, prompt templates and themes reached the session although `noSkills`
+was set. Now an extension allowlist alone makes none of its skills available.
+A skill is available only through the catalog plus the profile's explicit
+selection.
+
+Migration: add a catalog entry with the absolute path to the package's
+`SKILL.md` inside Pi's install (normally under
+`<Pi agent dir>/npm/node_modules/<package>/…`; `~` is not expanded) and select
+it in the profile. Prompt templates and themes that packages ship are now also
+closed through the SDK's public overrides. They were already never expanded
+for MCP prompts. This does not mean every previous profile behaves unchanged:
+a profile that used a package's skills needs the migration above.
+
+## Consequences
+
+- Skills are operator-managed prompt content. In `coding` profiles a skill's
+  instructions are executed with the profile's tools. A skill grants no rights.
+- Skill selection limits the regular skill catalog only. An allowlisted
+  extension stays trusted executable code and can still read files or inject
+  prompt text. This is no sandbox.
+- Three states stay distinct: configured (capabilities list the alias; intent
+  only), available in the SDK catalog (validated at session start and listed
+  to the model in its system prompt), and actually read by the model (the model
+  decides; not guaranteed). Task success is separate again.
+- Skill files can change under a running session. Operators carry that
+  discipline; the server does not enforce it.
+- Setup now writes into client skill directories, in the home directory and in
+  a project. It copies only from the package or the operator's override
+  directory, never follows a link inside a project, and never replaces what it
+  did not install or what the operator modified. The override directory and its
+  bases file are operator-trusted configuration, not a workspace. Installed
+  skill content becomes instructions for the controlling agent.
+- The server needs a name check of its own for selected files, because
+  `loadSkills` dedupes by name before `skillsOverride`.
+- Sessions of profiles with extensions each have their own model runtime
+  (ADR 0006). Skill loading does not change that.
+
+## Versioning
+
+ADR 0003 requires a minor release for a public contract change. The new
+`skills` capability field and the new `skill_load_failed` error code are such a
+change, and so are the new setup findings, the `--customize-skill` option and
+the controller skill that `setup --apply` installs, so the next release after
+0.7.1 is 0.8.0. The change is recorded under
+`## Unreleased` in the changelog. Implementing it does not itself release or
+bump the version.
+
+## Note of 2026-10-12: fingerprints, locking and recovery after 0.8.0
+
+The decisions above stand. Three details changed after 0.8.0 (issues #50, #51
+and #52): skill tree fingerprints are version 2 (`v2:` values; a 0.8.0 value
+counts only when a trusted reference proves it), `--apply --customize-skill`
+runs under a kernel lock on the override directory and writes the bases file as
+schema version 2, and an interrupted update of an installed copy is settled by
+the next `--apply`, `--remove` or `--rollback`. See [Pi
+skills](../skills.md#upgrade-from-080) and the [setup lifecycle
+design](../client-setup-design.md#skill-installation).

package/docs/architecture.md

@@ -47,13 +47,13 @@ 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, sorted by alias, and `configuration: { fingerprint, reloadPolicy: "restart-required" }`. 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 aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, and `configuration: { fingerprint, reloadPolicy: "restart-required" }`. 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.
 
 ## Deterministic Pi selection
 
-The SDK adapter owns one durable `ModelRuntime`. For the configured profile, it uses that same runtime to call `getProvider(providerId)`, `getModel(providerId, modelId)`, `checkAuth()`, `getAuth(model)`, and `getAvailable(providerId)`. It rejects an absent provider or model, missing or unavailable local authentication, and a model not present in the local available-model set before constructing a session. Authentication uses only Pi's existing local mechanism; auth objects are presence-checked and never retained, serialized, or logged.
+The SDK adapter owns one durable `ModelRuntime` for profiles without extensions. (A profile with `extensions` creates a fresh runtime for each session; see [Pi extensions design](pi-extensions-design.md).) For the configured profile, it uses that runtime to call `getProvider(providerId)`, `getModel(providerId, modelId)`, `checkAuth()`, `getAuth(model)`, and `getAvailable(providerId)`. It rejects an absent provider or model, missing or unavailable local authentication, and a model not present in the local available-model set before constructing a session. Authentication uses only Pi's existing local mechanism; auth objects are presence-checked and never retained, serialized, or logged.
 
-Only then does the adapter call `createAgentSession` with the same runtime and explicit `model`, `thinkingLevel`, and permission-derived `tools`. It never calls `resolveCliModel` or a fuzzy resolver, and does not depend on SDK settings or first-available fallback behavior. After construction it verifies `session.model.provider`, `session.model.id`, and effective `session.thinkingLevel`. A clamped thinking level or any selection mismatch fails closed. Any post-creation failure disposes the SDK session before a handle can enter the registry.
+Only then does the adapter call `createAgentSession` with that runtime and explicit `model`, `thinkingLevel`, and permission-derived `tools`. It never calls `resolveCliModel` or a fuzzy resolver, and does not depend on SDK settings or first-available fallback behavior. After construction it verifies `session.model.provider`, `session.model.id`, and effective `session.thinkingLevel`. A clamped thinking level or any selection mismatch fails closed. Any post-creation failure disposes the SDK session before a handle can enter the registry.
 
 These postchecks establish the selected provider, model, and effective Pi session
 thinking level. They do not inspect provider-side reasoning or enforce a
@@ -65,11 +65,15 @@ provider/engine behavior rather than inferred from the effective level.
 
 The registry owns public UUIDs, lifecycle state, the turn read model, background turn promises, abort, and disposal. A per-session operation queue serializes prompt admission and close; concurrent abort callers share one bounded abort attempt for the active turn. It registers a session only after adapter creation and postconditions complete. Once shutdown begins, starts fail with `server_stopping`; a handle created by an already-running start is disposed instead of admitted. The SDK session ID is never exposed.
 
+## Skills
+
+`skillCatalog` and each profile's `skills` are parsed by `loadConfig`. A path value resolves against the configuration file's directory, like a workspace; a `builtin:<name>` value resolves through the skill library to the operator's override in `skills/<name>` next to the configuration file, else to the skill shipped in the package. Setup, not the server, installs the controller skill into the clients' skill directories. A profile keeps its selected skills as a frozen list of `{alias, path}` pairs; the path never leaves the server. At session start the adapter loads exactly the selected files through the Pi SDK's public `loadSkills` with no default directories and validates them completely (SDK diagnostics, duplicate Pi skill names, aliases that share one canonical file, `disable-model-invocation: true`, files over 256 KiB). The SDK's skill override returns exactly that set, also after extension hooks add resources, so a package's bundled skills, prompt templates and themes no longer reach a session. Any failure is `skill_load_failed` with a fixed message. The model sees the loaded skills in its system prompt and decides itself whether to read one; the server neither guarantees that nor snapshots skill contents. Capability discovery projects only the selected aliases. See [Pi skills](skills.md) and [ADR 0007](adr/0007-profile-skill-selection.md).
+
 ## Lifecycle and public data
 
-`pi_session_prompt` creates a provisional turn identity, invokes Pi preflight, and only after accepted preflight publishes `{session, turn}`; rejected preflight leaves no orphan turn. Completion returns to `idle`; failure is generic. Each active session retains at most 20 turns. A turn is `running`, `completed`, `failed`, or `aborted`; its public view contains IDs, timestamps, and terminal `completedAt`. Completed text is normalized and capped at 64 KiB UTF-8 with Unicode-safe truncation. It can contain model-visible workspace data and remains potentially sensitive.
+`pi_session_prompt` creates a provisional turn identity, invokes Pi preflight, and only after accepted preflight publishes `{session, turn}`; rejected preflight leaves no orphan turn. Completion returns to `idle`; failure is generic. Each active session retains at most 20 turns. A turn is `running`, `completed`, `failed`, or `aborted`; its public view contains IDs, timestamps, and terminal `completedAt`. While a turn runs, its `updatedAt` is the time of the last observed public SDK activity (assistant message and tool execution events, content-free) and is a liveness lower bound only; see [Tool contracts](tool-contracts.md). Completed text is normalized and capped at 64 KiB UTF-8 with Unicode-safe truncation. It can contain model-visible workspace data and remains potentially sensitive.
 
-Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, and timestamps. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
+Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, and timestamps. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields, including the selected skill aliases. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
 
 Profile-specific authentication/catalog operations and session creation have fixed server-side deadlines of 5,000 ms and 10,000 ms. Prompt preflight, abort, close cleanup, registry shutdown, and process shutdown have fixed server-side deadlines of 5,000 ms, 5,000 ms, 5,000 ms, 12,000 ms, and 15,000 ms respectively. A preflight timeout returns `prompt_timeout` without publishing a turn. The unpublished operation remains quarantined until its prompt and abort cannot race with later work; late settlement can release that quarantine but never publish the turn. An abort timeout returns `abort_timeout` without falsely marking the turn aborted; a later normal outcome or successful SDK abort may still terminalize it exactly once. Close marks the session terminal, removes its public registry entry deterministically, and performs best-effort abort/dispose. Repeated close calls return a cached closed view while its tombstone is retained. Each SDK handle is disposed at most once. A late promise cannot revive a removed session or mutate a removed turn.
 
@@ -79,4 +83,4 @@ Public errors are stable and sanitized. They omit caller values, complete prompt
 
 ## Scope
 
-The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. Allowlisted Pi extensions may persist state of their own outside this boundary, and their input hooks see every client prompt as `rpc` input, never `interactive`; Pi Session MCP itself keeps no state beyond process memory. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.
+The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. Allowlisted Pi extensions may persist state of their own outside this boundary, and their input hooks see every client prompt as `rpc` input, never `interactive`; Pi Session MCP itself keeps no state beyond process memory. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Skill selection is part of that snapshot, but skill file contents are not: the SDK keeps file paths, so operators must not change a skill file while sessions that use it are active (see [Pi skills](skills.md)). Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.

package/docs/client-setup-design.md

@@ -10,6 +10,7 @@ The repository-local command shape is:
 
 ```text
 npm run --silent setup -- [--dry-run|--apply|--verify|--rollback|--remove] [--json] --target CLIENT:SCOPE:pi-session-mcp
+npm run --silent setup -- [--apply] [--json] --customize-skill NAME
 ```
 
 The script executes the already-built production entry point. Building is a
@@ -61,6 +62,204 @@ of descendant termination must assert zombie-or-absence without catching their
 own failed assertion; fence retention is checked separately with a live member
 and an indeterminate scan.
 
+## Skill installation
+
+Besides the registration, setup installs the controller skill
+`pi-session-orchestration` (`src/setup-skills.ts`). The skill step runs inside
+the same ownership transaction as the registration, per target and after it.
+`--dry-run` and `--verify` run it for every target. `--apply` runs it only for a
+registration finding of `ok` or `unchanged`, and `--rollback` and `--remove`
+only after the registration finding is `ok`. A skill finding therefore never
+blocks a registration, but `divergent`, `failed` and `unsupported` skill
+findings make the overall result `failed`, like any other finding.
+
+**Source.** The effective skill is the operator's override if
+`<override dir>/pi-session-orchestration/SKILL.md` exists, else the shipped skill
+(see [Pi skills](skills.md#the-skill-library)). Setup reads the tree with a
+bounded reader: regular files only, at most 32 files, 1 MiB and 8 levels, no
+links or special files inside the tree, entries whose name starts with `.`
+skipped. A missing or unusable source is `skill_source_invalid`. The fingerprint
+is version 2 (`src/skill-library.ts`): `v2:` and a SHA-256 over a domain and
+version tag, the file count, and per file in path byte order the length-prefixed
+UTF-8 path and the length-prefixed content. Version 1 (0.8.0) hashed
+`path NUL content NUL` per file and was ambiguous, because content may contain
+NUL bytes. A version 1 value never proves identity alone (see *Legacy records*
+below).
+
+**Slots.** A slot is the skill directory a client reads:
+
+| Target | Slot |
+| --- | --- |
+| `codex:user` | `~/.agents/skills/pi-session-orchestration` |
+| `claude-code:user`, `claude-code:local` | `~/.claude/skills/pi-session-orchestration` (one shared slot) |
+| `claude-code:project` | `<project>/.claude/skills/pi-session-orchestration` (the directory in which setup runs) |
+
+**Ownership records.** One record per client slot holds the target client,
+the scope kind (`project` or `user`, so Claude Code `user` and `local` share a
+record), the phase and a content fingerprint, plus `replaces` during an update (see below). A home slot uses the
+alias `skill:pi-session-orchestration`. A project slot uses
+`skill:pi-session-orchestration@<id>`, where `<id>` is the first 16 hex digits
+of a SHA-256 over the project's real path: an opaque identity, not a path, so a
+`--remove` in another project never touches this project's copy. The `pending`
+phase is written before the first filesystem change and promoted to `owned`
+after a post-install inspection. Skill records hold `v2:` values in
+`fingerprint` and `replaces`; registration records keep their 64-hex snapshot
+hash. During an update, the pending record also keeps the fingerprint of the
+copy it replaces (`replaces`), so an interrupted update leaves a copy that
+setup still recognizes as its own: the next `--apply` finishes the update and
+`--remove` deletes it. A later run that finds a `pending` record whose slot
+already equals the source promotes it.
+
+**Atomic copy.** Setup creates missing parent directories (mode `0755`), stages
+the tree in a staging directory in the slot's parent (files `0644`, each file
+and directory fsynced), and re-checks that the slot is unchanged
+(fingerprint, device and inode). It then renames the exact old tree to a backup
+name, renames the staged directory into place, inspects the result, verifies
+that the backup is still the exact old tree it moved, renames it to a trash
+name and deletes the trash entry by entry. The slot is never edited in place.
+
+**Intermediates and recovery.** The three intermediate directories are named
+after the pending record's transaction id, in the slot's parent:
+`.pi-session-mcp-<skill>-<transactionId>.staging`, `.backup` and `.trash`.
+Recovery derives them from the persisted record and never searches. The order
+is: pending record, staging, backup rename, install, verify backup, rename to
+trash, delete the trash entry by entry, owned record. `--apply`, `--remove` and
+`--rollback` settle a pending transaction first, inside the ownership
+transaction, and only when the slot is empty, a link, or one of setup's two
+copies:
+
+- A trash directory is deleted after a structural recheck: a real directory,
+  regular files and directories only, no hidden entries, within the tree
+  limits. It may be partial, because it was verified before the rename.
+- The backup must equal the replaced copy; the staging directory must equal
+  the target or be an interrupted write of it. A partially written staging
+  directory counts only when every file is a prefix-consistent part of the
+  current library tree and that tree is the record's target.
+- `--apply` with an empty slot finishes forward with a complete staging
+  directory, else moves the verified backup back. `--remove` and `--rollback`
+  delete the verified intermediates and leave the slot to the removal.
+- Anything modified or foreign stays and is reported as
+  `skill_recovery_retained` (divergent). A failed update leaves its staging
+  directory until the next run settles it, and an unhealthy ownership fence
+  retains intermediates the same way.
+- Random-name directories of 0.8.0 updates are never searched for or deleted;
+  an operator may remove them by hand.
+- `--dry-run` and `--verify` do not report leftover intermediates.
+
+**Legacy records.** A skill record whose `fingerprint` or `replaces` is a bare
+64-hex value was written by 0.8.0. It names the slot only if a trusted
+reference has that version 1 value and is byte-identical, by its version 2
+fingerprint, to the installed copy. The references are the shipped skills of
+0.8.0 (a fixed table in `src/skill-library.ts`) and the current library tree.
+When proven, `--apply` migrates the record to version 2 and then updates the
+copy as usual; `--remove` removes the proven copy. Otherwise `--dry-run`,
+`--apply`, `--remove` and `--rollback` report `skill_legacy_unverified`
+(divergent) and change neither the copy nor the record. The operator inspects
+the copy and, if it is unchanged setup content that is no longer needed,
+deletes it; an absent slot clears the record on the next operation. The
+intermediates of an interrupted 0.8.0 update cannot be derived and are not
+recovered.
+
+**Divergence rules.** Setup never replaces or deletes, and reports
+`skill_divergent` for:
+
+- an installed copy whose fingerprint differs from setup's own copy (the
+  owned fingerprint, or the one a pending update replaces), even if it happens
+  to equal the new source;
+- an installed copy that a 0.8.0 record names but no trusted reference proves
+  (`skill_legacy_unverified`);
+- a copy that differs from the source without a record (a foreign skill of the
+  same name);
+- any entry whose name starts with `.` inside the installed copy: setup never
+  writes such entries, so they are operator content that the fingerprint over
+  the visible files would not protect;
+- a link to anything other than the effective skill, a non-directory at the
+  skill entry, or a tree that cannot be read.
+
+A copy that equals the source stays unowned when no record exists
+(`skill_equivalent` or `skill_already_equivalent`). A link at the skill entry
+whose real path is exactly the effective library skill directory (your
+override, else the shipped skill) is the operator's own equivalent setup:
+`--dry-run` and `--apply` report `skill_linked` (unchanged), `--verify` reports
+`skill_verified`, and removal leaves it alone (`skill_not_owned`). An unmodified owned copy
+that differs from the source is replaced after a package update or a changed
+override (`skill_update_planned`, `skill_updated`).
+
+**Link rules.** The skill entry itself is never followed. In the home
+directory, the client's skills directory (`~/.claude/skills`, `~/.agents/skills`)
+may be the operator's own link, for example into a dotfiles checkout, and is
+resolved to its real path. A project may be untrusted: only the project root is
+canonicalized, and a link anywhere below it makes the slot divergent, so setup
+never writes outside the project. If a slot cannot be resolved at all, the
+finding is `skill_source_invalid` for `--dry-run`, `skill_install_failed` for
+`--apply`, `skill_missing` for `--verify` and `skill_divergent` for removal.
+
+**Shared slot.** For `--rollback` and `--remove`, the Claude Code `user` and
+`local` registrations share one slot. While the other registration is still
+`owned`, the skill stays and the finding is `skill_kept_shared`. The last
+removal deletes it (`skill_removed`; `skill_absent` if it is already gone;
+`skill_not_owned` if setup never owned it). A modified copy is left in place
+(`skill_divergent`) and its record stays, so a later run can finish after you
+removed the copy.
+
+**Remove retry.** Registration removal can finish before skill cleanup, for
+example after an interruption or a `skill_divergent`. When the registration
+record is gone but setup still owns the skill of that target, `--remove` and
+`--rollback` run once more for that target. They first prove that the
+registration is absent and then report the registration as removed and clean up
+the skill. They never run for a target whose skill setup does not own, nor for
+a Claude Code `user` or `local` target while the other one of the two is still
+registered, and an unowned live registration stays untouched
+(`ownership_unavailable`).
+
+Skill reports carry only client, scope, the alias `pi-session-orchestration`,
+status and a stable code. No skill content, fingerprint or path leaves setup.
+
+## Skill customization
+
+`setup --customize-skill <name>` (and `--apply --customize-skill <name>`,
+`src/skill-customize.ts`) does not touch clients and takes no ownership lock. It
+copies a shipped skill into the override directory `skills/` next to the
+configuration file and records the shipped fingerprint under the skill name in
+`<override dir>/.pi-session-mcp-bases.json`
+(`{"schemaVersion":2,"bases":{"<name>":"<fingerprint>"}}`, strictly validated,
+at most 64 KiB). A value is a `v2:` fingerprint or a legacy 64-hex value that
+could not be migrated. A version 1 file is still read. The copy is staged in
+a temporary directory and renamed into place; an existing override is never
+overwritten. A changed shipped skill is only reported (`skill_override_outdated`);
+`--apply` then moves the recorded base and nothing else.
+
+`--apply` is a cross-process transaction per override directory
+(`src/override-lock.ts`). It takes an exclusive kernel lock on the stable lock
+file `<override dir>/.pi-session-mcp-bases.lock` (mode `0600`, never deleted;
+on Linux the trusted util-linux `flock` at `/usr/bin/flock` or `/bin/flock`, on
+macOS `O_EXLOCK`; the same supported local filesystems as the ownership
+state). Under the lock it re-reads and validates the bases file, copies the
+skill if no override exists, merges the base and writes the file atomically: an
+fsynced temporary file, a rename and a directory fsync. The lock is released on
+every path. The wait is bounded at 30 seconds (`skill_customize_lock_busy`);
+a lock that cannot be taken is `skill_customize_lock_unavailable`. A killed
+holder releases the lock through the kernel and may leave a stale
+`.pi-session-mcp-bases.json.<hex>.tmp` or a temporary copy directory
+`.<skill>.<hex>.tmp`, which are harmless. The dry-run takes no
+lock and writes nothing: no directory, lock file or temporary file. Every write
+produces version 2 and migrates each legacy value that names a released 0.8.0
+shipped skill; other legacy values are kept as they are.
+
+Decisions for an existing legacy base: if it names the current shipped skill,
+the dry-run reports `skill_base_migration_planned` and `--apply` reports
+`skill_base_migrated`; if it names no released shipped skill, the dry-run
+reports `skill_base_unverified` and `--apply` acknowledges it as
+`skill_base_updated`; if it names another released skill, the result is
+`skill_override_outdated`. An existing override that equals the shipped skill
+but has no base completes a customization whose bases commit failed
+(`skill_customize_planned`, `skill_customized`). Of two concurrent applies for
+the same skill, one reports `skill_customized` and the other
+`skill_override_current`. Doctor stays offline, read-only and lock-free. It cannot be combined
+with `--target`, `--verify`, `--rollback` or `--remove`. The finding target is
+`{ client: "skills", scope: "override", alias: <name> }`; the alias is the
+skill name only if it is valid, else `invalid`.
+
 ## Verification boundary
 
 Production verification requires the offline Doctor, exact public client-CLI registration inspection, and a directly launched bounded MCP handshake. The verifier calls `pi_capabilities_get` with `{}` only; session start/prompt/turn and provider/model operations are forbidden. Its child process is terminated and awaited before success is reported.
@@ -84,7 +283,26 @@ Stable finding codes are grouped by responsibility:
 - verification: `registration_not_equivalent`, `mcp_verified`,
   `mcp_unsupported`, `mcp_timeout`, `mcp_failed`;
 - rollback/removal: `rolled_back`, `removed`, `ownership_diverged`,
-  `cleanup_failed`.
+  `cleanup_failed`;
+- controller skill, dry-run: `skill_absent`, `skill_equivalent`, `skill_linked`,
+  `skill_update_planned`, `skill_recovery_planned`, `skill_divergent`,
+  `skill_legacy_unverified`, `skill_source_invalid`;
+- controller skill, apply: `skill_installed`, `skill_already_equivalent`, `skill_recovered`, `skill_linked`,
+  `skill_updated`, `skill_divergent`, `skill_legacy_unverified`,
+  `skill_recovery_retained`, `skill_source_invalid`,
+  `skill_install_failed`;
+- controller skill, verify: `skill_verified`, `skill_missing`,
+  `skill_not_equivalent`;
+- controller skill, rollback/removal: `skill_removed`, `skill_kept_shared`,
+  `skill_not_owned`, `skill_absent`, `skill_divergent`,
+  `skill_legacy_unverified`, `skill_recovery_retained`;
+- skill customization: `skill_customize_planned`, `skill_customized`,
+  `skill_override_current`, `skill_override_outdated`,
+  `skill_base_migration_planned`, `skill_base_migrated`,
+  `skill_base_unverified`, `skill_base_updated`, `skill_not_shipped`,
+  `skill_bases_corrupt`, `skill_override_invalid`,
+  `skill_customize_lock_busy`, `skill_customize_lock_unavailable`,
+  `skill_customize_failed`.
 
 The public statuses are `planned`, `ok`, `unchanged`, `absent`, `divergent`,
 `unsupported`, and `failed`. Reports never contain command arguments, command

package/docs/client-setup.md

@@ -90,6 +90,89 @@ bounded direct MCP `initialize`, `tools/list`, and
 `pi_capabilities_get({})` check. It never starts a session or invokes
 a provider.
 
+### Controller skill
+
+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.
+
+| Target | Where the skill goes |
+| --- | --- |
+| `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 |
+
+Every result therefore has a second finding per target, with the same client
+and scope and the alias `pi-session-orchestration`:
+
+```text
+apply: ok
+claude-code/user/pi-session-mcp: ok (applied)
+claude-code/user/pi-session-orchestration: ok (skill_installed)
+```
+
+Skill findings per operation:
+
+- `--dry-run`: `skill_absent` (absent), `skill_equivalent` (unchanged),
+  `skill_linked` (unchanged; a link to exactly the effective skill),
+  `skill_update_planned` (planned), `skill_recovery_planned` (planned; the
+  ownership record is pending for an update that `--apply` would settle),
+  `skill_divergent` (divergent), `skill_legacy_unverified` (divergent),
+  `skill_source_invalid` (failed).
+- `--apply`: `skill_installed` (ok), `skill_already_equivalent` (unchanged),
+  `skill_recovered` (ok; `--apply` settled an interrupted update and needed no
+  further update), `skill_linked` (unchanged),
+  `skill_updated` (ok; setup replaced its own unmodified copy after a package
+  update or a changed override), `skill_divergent`, `skill_legacy_unverified`,
+  `skill_recovery_retained` (divergent), `skill_source_invalid`,
+  `skill_install_failed` (failed).
+- `--verify`: `skill_verified` (ok), `skill_missing` and
+  `skill_not_equivalent` (failed).
+- `--rollback` and `--remove`: `skill_removed` (ok), `skill_kept_shared`
+  (unchanged; the other Claude Code `user` or `local` registration still uses
+  the shared directory), `skill_not_owned` (unchanged), `skill_absent` (ok) and
+  `skill_divergent` (a modified copy stays in place), `skill_legacy_unverified`
+  (a record of 0.8.0 that no trusted reference proves; copy and record stay) and
+  `skill_recovery_retained` (a modified or foreign intermediate directory of an
+  interrupted update stays).
+
+Setup never replaces or deletes a modified installed copy, a skill of the same
+name that it did not install, or a link or non-directory at the skill entry; it
+reports `skill_divergent`. That does not block the registration, but it makes
+the overall status `failed` (exit 1). Never edit the installed copy. To
+customize the skill, run `--apply --customize-skill pi-session-orchestration`,
+edit the override, and run `--apply` for the target again. Design and trust
+rules: [setup lifecycle design](client-setup-design.md#skill-installation).
+
+Setup installs only `pi-session-orchestration` into clients. Worker skills are
+for Pi profiles and are selected through `builtin:` entries in `skillCatalog`.
+
+### Customize a shipped skill
+
+```bash
+npm run --silent setup -- --customize-skill pi-session-review
+npm run --silent setup -- --apply --customize-skill pi-session-review
+```
+
+This works without `--target` and needs `PI_SESSION_MCP_CONFIG`. It copies the
+shipped skill into the `skills/` directory next to the configuration file and
+records the fingerprint of the shipped skill in
+`.pi-session-mcp-bases.json` there. The finding target is
+`skills/override/<name>`; the codes are `skill_customize_planned` (planned),
+`skill_customized` (ok), `skill_override_current` (unchanged),
+`skill_override_outdated` (planned), `skill_base_migration_planned` (planned),
+`skill_base_unverified` (planned), `skill_base_migrated` (ok),
+`skill_base_updated` (ok), `skill_not_shipped`, `skill_bases_corrupt`,
+`skill_override_invalid`, `skill_customize_lock_busy`,
+`skill_customize_lock_unavailable` and `skill_customize_failed` (failed). An
+existing override is never overwritten. `--apply` runs under an exclusive lock
+on the override directory (`.pi-session-mcp-bases.lock`, 30 s wait); the dry-run
+takes no lock and writes nothing.
+After `skill_override_outdated`, `--apply` moves only the recorded base, which
+acknowledges a change you reviewed. Details: [Pi skills](skills.md#customize-and-add-skills).
+
 ## Local configuration
 
 Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
@@ -118,7 +201,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` and `extensions` described in [Installation](installation.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`. 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` 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`. 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.
 
@@ -190,7 +273,7 @@ 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 one `ModelRuntime`, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
+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.
 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.
 5. Call `pi_session_close` when the session is no longer needed.
@@ -246,7 +329,7 @@ Poll `pi_turn_get` for at most three minutes. If it does not become terminal, re
 
 ### A prompt fails immediately after a provider config or credential change
 
-`pi_session_prompt` reads the configured provider/model through one `ModelRuntime` that is created once and cached for the lifetime of the Pi Session MCP server process; the underlying SDK reads `~/.pi/agent/models.json` only at that creation. Editing that file (for example adding or fixing a provider API key) does not take effect in an already-running server process, and a resulting turn typically fails (`turn_failed`) within milliseconds rather than after a real provider round trip. Restart or reconnect the MCP server (which restarts the process) after any provider config or credential change, then retry.
+For profiles without extensions, `pi_session_prompt` reads the configured provider/model through one `ModelRuntime` that is created once and cached for the lifetime of the Pi Session MCP server process (a profile with extensions creates a fresh runtime when each session starts); the underlying SDK reads `~/.pi/agent/models.json` only at that creation. Editing that file (for example adding or fixing a provider API key) does not take effect in an already-running server process, and a resulting turn typically fails (`turn_failed`) within milliseconds rather than after a real provider round trip. Restart or reconnect the MCP server (which restarts the process) after any provider config or credential change, then retry.
 
 ### Session cleanup