pi-session-mcp 0.8.0 → 0.8.2

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

@@ -215,3 +215,14 @@ 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

@@ -71,7 +71,7 @@ The registry owns public UUIDs, lifecycle state, the turn read model, background
 
 ## 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, 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.
 

package/docs/client-setup-design.md

@@ -79,7 +79,12 @@ findings make the overall result `failed`, like any other finding.
 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 a SHA-256 over the sorted relative paths and contents.
+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:
 
@@ -97,20 +102,86 @@ alias `skill:pi-session-orchestration`. A project slot uses
 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. 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.
+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 temporary directory in the slot's parent (files `0644`, each file
+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, and deletes
-the backup only if it is still the exact old tree it moved. An unhealthy
-ownership fence retains staged and backup content for conservative recovery.
-The slot is never edited in place.
+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 only when its current contents are the
+  complete, unchanged replaced copy: its version 2 tree fingerprint equals the
+  replaced fingerprint in the pending record. A partial trash tree (for
+  example after an interruption during the entry-by-entry deletion, including
+  an empty one), a modified, added-to, foreign or otherwise unprovable tree,
+  and any trash when the record names no usable replaced fingerprint are
+  retained. A directory name, the transaction id or a structural check alone
+  never proves ownership of the contents. This deliberately replaces the
+  earlier automatic deletion of partial trash trees; continuing a partial
+  deletion would need additional durable evidence, and no journal is added
+  for it. The fingerprint covers the paths and contents of regular files, not
+  empty directories or file modes, so an empty directory or a mode change
+  inside an otherwise complete trash does not prevent its deletion; no file
+  content is lost that way.
+- 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, the trash directory included, stays and is
+  reported as `skill_recovery_retained` (divergent). The pending record and
+  the slot then stay unchanged, and nothing is reported as settled. A
+  retained trash stops recovery before any other intermediate is touched; a
+  retained backup or staging directory can follow the deletion of a proven
+  own trash. A failed update leaves its staging directory until the
+  next run settles it, and an unhealthy ownership fence retains intermediates
+  the same way.
+- Operator settlement of a retained trash directory: inspect the
+  `.pi-session-mcp-<skill>-<transactionId>.trash` directory next to the slot,
+  move any own content elsewhere, delete that directory, and rerun the same
+  setup command.
+- For a pending version 2 transaction, `--dry-run` reports
+  `skill_recovery_retained` (divergent, exit 1) whenever `--apply` would
+  retain an intermediate, using the same read-only classification as the
+  recovery, and otherwise `skill_recovery_planned`. A dry-run never writes.
+- 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:
@@ -118,6 +189,8 @@ The slot is never edited in place.
 - 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
@@ -171,11 +244,41 @@ status and a stable code. No skill content, fingerprint or path leaves setup.
 `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":1,"bases":{...}}`,
-strictly validated, at most 64 KiB, replaced atomically). The copy is staged 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. It cannot be combined
+`--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`.
@@ -184,38 +287,68 @@ skill name only if it is valid, else `invalid`.
 
 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.
 
+Verify evaluates one target in this order, and the first failure ends that
+target's verification:
+
+1. An unknown client: `client_unsupported`.
+2. Ownership: `ownership_unavailable`.
+3. Release binding: `release_binding_mismatch`.
+4. Doctor, under its own code. A failed Doctor ends the target's verify before
+   the registration is inspected and before any handshake.
+5. Inspection. A client the inspection reports as unsupported or not
+   discoverable, for example because its CLI is not on `PATH`, gives status
+   `unsupported` and code `unsupported`. An inspection that throws gives
+   `inspect_failed`. An absent registration, a divergent one, and an
+   equivalent one with another fingerprint give `registration_not_equivalent`.
+6. Only a truly equivalent registration runs the bounded handshake, which
+   reports `mcp_verified` or `mcp_<status>`.
+
+None of the failure cases mutates a registration or starts the handshake, and
+all exit with `1`. There is no separate client-unavailable code; the
+dry-run already separates these states the same way.
+
 ## Compatibility and reporting
 
 Codex and Claude Code are separate adapters with explicit supported scopes and documented capability fixtures. Unknown output fails closed with stable codes. Absolute paths are passed only to client commands where required and are never included in results, logs, or ownership metadata. Client command diagnostics must be reduced to stable codes before crossing this boundary.
 
-Human and JSON output derive from one `schemaVersion: 1` result. Exit code `0` is success, `1` is an operational or reconciliation failure, `64` is command-line misuse, and interrupted setup returns `130` for `SIGINT` or `143` for `SIGTERM` only after the guardian cleanup path has completed or retained the fence. Automatic replacement of a divergent registration is deliberately unsupported.
+Human and JSON output derive from one `schemaVersion: 1` result; this version is the setup report's own, not the package version or the MCP tool contract (see [Versions](tool-contracts.md#versions)). Exit code `0` is success, `1` is an operational or reconciliation failure, `64` is command-line misuse, and interrupted setup returns `130` for `SIGINT` or `143` for `SIGTERM` only after the guardian cleanup path has completed or retained the fence. Automatic replacement of a divergent registration is deliberately unsupported.
 
 Stable finding codes are grouped by responsibility:
 
 - input/prerequisites: `target_invalid`, `config_required`, `usage_invalid`,
   `platform_unsupported`, `operation_interrupted`,
   `doctor_failed`, `release_unavailable`, `client_unsupported`, `inspect_failed`;
-- planning/reconciliation: `absent`, `equivalent`, `divergent`,
+- planning/reconciliation: `absent`, `equivalent`, `divergent`, `unsupported`,
   `already_equivalent`, `divergence_requires_replacement`,
   `registration_fingerprint_mismatch`, `release_binding_mismatch`;
 - ownership/apply: `applied`, `pending_recovered`, `ownership_unavailable`,
   `apply_failed_recovery_pending`;
-- verification: `registration_not_equivalent`, `mcp_verified`,
-  `mcp_unsupported`, `mcp_timeout`, `mcp_failed`;
+- verification: `registration_not_equivalent` (absent, divergent or
+  differently fingerprinted registration), `mcp_verified`, `mcp_unsupported`,
+  `mcp_timeout`, `mcp_failed`; verify also reports `unsupported` (client not
+  discoverable) and `inspect_failed` (inspection threw), which belong to the
+  other groups;
 - rollback/removal: `rolled_back`, `removed`, `ownership_diverged`,
   `cleanup_failed`;
 - controller skill, dry-run: `skill_absent`, `skill_equivalent`, `skill_linked`,
-  `skill_update_planned`, `skill_divergent`, `skill_source_invalid`;
-- controller skill, apply: `skill_installed`, `skill_already_equivalent`, `skill_linked`,
-  `skill_updated`, `skill_divergent`, `skill_source_invalid`,
+  `skill_update_planned`, `skill_recovery_planned`,
+  `skill_recovery_retained`, `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_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_updated`,
-  `skill_not_shipped`, `skill_bases_corrupt`, `skill_override_invalid`,
+  `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`,

package/docs/client-setup.md

@@ -90,6 +90,25 @@ bounded direct MCP `initialize`, `tools/list`, and
 `pi_capabilities_get({})` check. It never starts a session or invokes
 a provider.
 
+### Verify diagnostics
+
+Verify checks one target in a fixed order and stops that target at the first
+failure. After an unknown client (`client_unsupported`), ownership
+(`ownership_unavailable`) and release binding (`release_binding_mismatch`),
+Doctor runs; if it fails, verify reports its code and neither inspects the
+registration nor runs the handshake. Then the client's registration is
+inspected:
+
+| Result | Status | Code | What it means |
+| --- | --- | --- | --- |
+| Client unsupported or not discoverable | `unsupported` | `unsupported` | Setup could not run or recognize the client CLI. Usually the CLI is not on `PATH`, for example in a non-interactive SSH shell. Put the client's directory on `PATH` and rerun; the registration itself may be fine. `--dry-run` reports the same state |
+| Inspection failed | `failed` | `inspect_failed` | Inspecting the registration threw an error. Rerun; if it persists, run the client's own `mcp` listing |
+| Registration absent, divergent, or equivalent with another fingerprint | `failed` | `registration_not_equivalent` | The registration is missing or differs from the one setup would create. Run `--dry-run` for the exact state |
+| Registration equivalent | `ok` or `failed` | `mcp_verified` or `mcp_<status>` | Only now does the bounded MCP handshake run |
+
+None of the failure rows changes a registration or starts the handshake, and
+each exits with `1`.
+
 ### Controller skill
 
 Besides the registration, `--apply` installs the controller skill
@@ -117,19 +136,26 @@ 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_divergent` (divergent),
+  `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_linked` (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_source_invalid`,
+  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_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
@@ -155,9 +181,14 @@ 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_updated` (ok),
-`skill_not_shipped`, `skill_bases_corrupt`, `skill_override_invalid` and
-`skill_customize_failed` (failed). An existing override is never overwritten.
+`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).
 

package/docs/doctor-design.md

@@ -43,7 +43,7 @@ Doctor reads extension manifests from Pi's user install location only; it never
 
 The skill checks run after the extension checks. They look only at file availability: Doctor never reads a skill's frontmatter, never parses or executes it, and the subject carries the catalog alias, never a path. Frontmatter, skill-name rules, name collisions and explicit-only flags (`disable-model-invocation`) are checked only at session start by the Pi SDK contract, so a clean Doctor run does not promise that a skill loads. Unknown or duplicate aliases and two selected aliases with one path are configuration errors and surface as `config_invalid`. See [Pi skills](skills.md).
 
-`skill_override_outdated` concerns the operator's skill overrides, not a profile. It is `ok` for a recorded base that still matches the shipped skill, and a warning (exit status 1, never blocking `setup`) when the shipped skill changed after the operator ran `pi-session-mcp-setup --customize-skill <name>`; its remediation names `pi-session-mcp-setup --apply --customize-skill <name>` to acknowledge a reviewed change. Only skills with a recorded base are compared, and a recorded name that is no longer shipped is skipped. A corrupt bases file yields a warning with the subject `skill:bases`. Doctor reads the bases file and the shipped skill files only; nothing is executed and the subject is a validated skill name, never a path. The check sorts after `skill_duplicate`.
+`skill_override_outdated` concerns the operator's skill overrides, not a profile. It is `ok` for a recorded base that still matches the shipped skill, and a warning (exit status 1, never blocking `setup`) when the shipped skill changed after the operator ran `pi-session-mcp-setup --customize-skill <name>`; its remediation names `pi-session-mcp-setup --apply --customize-skill <name>` to acknowledge a reviewed change. Only skills with a recorded base are compared, and a recorded name that is no longer shipped is skipped. A recorded base of 0.8.0 (a version 1 fingerprint) is compared through the version 2 value of the released 0.8.0 skill it names; a version 1 base that names no released skill cannot be confirmed and yields a warning that says so, with the same remediation. A corrupt bases file yields a warning with the subject `skill:bases`. Doctor reads the bases file and the shipped skill files only; nothing is executed and the subject is a validated skill name, never a path. The check sorts after `skill_duplicate`.
 
 The Doctor reuses `loadConfig`; it does not duplicate alias, profile, thinking
 level, or read-only-default rules. Workspace values are used only for local

package/docs/installation.md

@@ -20,7 +20,7 @@ An installation consists of these locations:
 | --- | --- | --- |
 | Package | the npm global prefix, or a dedicated directory per release such as `~/.local/share/pi-session-mcp/releases/<tag>` | The built server, `setup` and Doctor. |
 | Configuration | a file outside the package, for example `~/.config/pi-session-mcp/pi-session-mcp.json` | Operator-owned, mode `0600`, never committed. |
-| Skill overrides (optional) | the `skills/` directory next to the configuration file, for example `~/.config/pi-session-mcp/skills/` | Your own or customized skills, plus `.pi-session-mcp-bases.json`. Created by you or by `setup --customize-skill`. See [Pi skills](#pi-skills). |
+| Skill overrides (optional) | the `skills/` directory next to the configuration file, for example `~/.config/pi-session-mcp/skills/` | Your own or customized skills, plus `.pi-session-mcp-bases.json` and its lock file `.pi-session-mcp-bases.lock`. Created by you or by `setup --customize-skill`. See [Pi skills](#pi-skills). |
 | Controller skill | `~/.agents/skills/pi-session-orchestration` (Codex), `~/.claude/skills/pi-session-orchestration` or `<project>/.claude/skills/pi-session-orchestration` (Claude Code) | Written by `setup --apply`; see [Register a client](#4-register-a-client). |
 | Setup ownership state | `~/.local/state/pi-session-mcp/ownership.json` | Written by `setup` only. Path-free and secret-free. |
 
@@ -487,7 +487,8 @@ choose skills.
   create `<override dir>/<new-name>/SKILL.md` and reference it as
   `builtin:<new-name>`; no command is needed. After a package update, Doctor
   warns with `skill_override_outdated` when a shipped skill changed since you
-  copied it.
+  copied it. `--apply --customize-skill` takes a kernel lock on the override
+  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`.
 - An extension allowlist alone makes none of a package's skills available. If a
@@ -513,6 +514,11 @@ the new text. A package update that changes a shipped skill does not touch an
 override of yours; Doctor warns with `skill_override_outdated` so that you can
 review the change.
 
+After an upgrade from 0.8.0, run `setup` as a dry-run and then with `--apply`
+for your targets. Copies and records of 0.8.0 are proven before setup acts on
+them; one that cannot be proven is reported as `skill_legacy_unverified` and
+stays untouched. See [Upgrade from 0.8.0](skills.md#upgrade-from-080).
+
 ### npm installation
 
 An npm upgrade replaces the package in place. Close the client sessions that

package/docs/pi-extensions-design.md

@@ -263,6 +263,17 @@ and step 6 leaves no session to dispose.
 - **UI and flags.** No UI context is bound; extension UI calls return the
   SDK's no-op results. `extensionFlagValues` is empty, so extension flags keep
   their defaults.
+- **Turn liveness.** The `updatedAt` of a running turn follows the public SDK
+  events of the prompt: assistant message start, update and end, and tool
+  execution start, update and end. An extension provider with its own agent
+  loop, such as `pi-cursor-sdk`, therefore advances `updatedAt` whenever it
+  publishes streaming updates. Its internal steps that publish no public
+  event stay invisible, so an unchanged `updatedAt` is no proof of a hang, and
+  streaming is no evidence of finished or useful work. Only the event type and
+  the message role are inspected; no delta, thinking block, tool argument or
+  partial result is stored or projected, and the answer still comes only from
+  the final assistant message. See [Tool
+  contracts](tool-contracts.md).
 
 ### Lifecycle and close
 

package/docs/releasing.md

@@ -16,7 +16,13 @@ does not authorize any of them.
 - A change to the public contract needs a minor release and its own decision.
 
 The public contract is the set of eight tools with their fields, states and
-error codes, as defined in the [tool contracts](tool-contracts.md).
+error codes, as defined in the [tool contracts](tool-contracts.md). How the
+package version, the MCP tool contract and the setup report's `schemaVersion`
+differ is defined under [Versions](tool-contracts.md#versions).
+
+Wherever this document asks for the Level 1 checks, the test step is
+`NODE_OPTIONS=--unhandled-rejections=strict npm test`. CI uses the same
+setting, so an unhandled promise rejection fails the run locally and in CI.
 
 A release is distributed twice: as the GitHub release with its source archive,
 and as the npm package `pi-session-mcp`. The npm package contains the built
@@ -131,9 +137,15 @@ Patch transitive advisories in the lockfile only:
 
 ## Prepare a release
 
+A release travels in the pull request of the change it ships. That pull
+request also carries the version, the changelog heading and the pre-release
+acceptance record; there is no separate release pull request. Records that can
+only be made after publishing go into the pull request of the next change.
+
 Preconditions:
 
-- `main` contains every change of the release, and Level 1 is green on `main`.
+- The change pull request contains every change of the release, and Level 1
+  is green on its head.
 - `npm audit` reports 0 vulnerabilities.
 - The public contract is unchanged, or a minor release has been decided.
 - The acceptance that this release requires is recorded, or its absence is
@@ -141,8 +153,9 @@ Preconditions:
 
 Steps:
 
-1. Create a release branch from the current `main`. Never reuse a release branch
-   that predates later merges: its lockfile would undo later dependency patches.
+1. Bring the change branch up to date with `main` if `main` moved. Never reuse
+   a branch that predates later merges without that: its lockfile would undo
+   later dependency patches.
 2. Set the version:
 
    ```bash
@@ -159,11 +172,13 @@ Steps:
 5. Run the working-tree
    [Level 2 acceptance](acceptance.md#tooling) on the release candidate with
    `scripts/setup-acceptance.mjs`, unless the release notes state its absence.
-6. Open one pull request named `chore: prepare v<x.y.z> release`.
+6. Record the pre-release acceptance in the status section of
+   [Acceptance](acceptance.md) and push it to the change pull request. Name the
+   release in the pull request's title and description.
 
 ## Publish a release
 
-After the release pull request is merged and CI is green on the merge commit:
+After the change pull request is merged and CI is green on the merge commit:
 
 ```bash
 git switch main
@@ -217,9 +232,9 @@ After publishing:
 
 1. Run the published-release
    [Level 2 acceptance](acceptance.md#working-tree-and-published-release-variants)
-   from a fresh clone of the tag and from the published npm package, and
-   record it. `scripts/setup-acceptance.mjs` runs both
-   ([Tooling](acceptance.md#tooling)).
+   from a fresh clone of the tag and from the published npm package.
+   `scripts/setup-acceptance.mjs` runs both ([Tooling](acceptance.md#tooling)).
 2. Upgrade the installation as described in
    [Installation](installation.md#upgrade).
-3. Update the status section in [Acceptance](acceptance.md).
+3. Record both in the status section of [Acceptance](acceptance.md) with the
+   pull request of the next change, not in a pull request of their own.