pi-session-mcp 0.8.1 → 0.8.3

package/docs/adr/0003-post-mvp-maintenance.md

@@ -53,7 +53,7 @@ Changes that keep the public MCP contract (tools, fields, states, error codes) s
 
 ## Revisit triggers
 
-- **E (isolation research):** coding profiles are used on non-disposable repositories or with untrusted content, at the latest before a local writer runs on real repositories.
+- **E (isolation research):** coding profiles are used on non-disposable repositories or with untrusted content, at the latest before a local writer runs on real repositories. This trigger fired on 2026-10-15: coding profiles had written on non-disposable repositories. Sprint 4 authorizes the isolation decision as the one next investment, an options comparison in ADR 0008, not an implementation; see [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) and the [Sprint 4 decision](../sprints/2026-10-15-s4-decision.md).
 - **C (bounded wait):** clients routinely need more than about five polls per turn, or client tool-call limits or approval prompts make polling costly.
 - **D (persistence research):** a client or server restart loses useful work in practice.
 - **F (remote architecture):** a concrete remote or mobile use case that SSH or existing remote-development workflows cannot satisfy.

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Validated dependency baseline (2026-10-09)
 
-- [`@earendil-works/pi-coding-agent` 1.1.0](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) supplies the documented root exports used by this server, including `ModelRuntime` and `createAgentSession`. Since 0.99 the prompt preflight hook reports a dispatch disposition (`started`, `queued`, `handled`) and is not called on rejection; only `started` admits a public turn (`admitsTurn` in `src/sdk-pi-adapter.ts`). Model-visible tools are declared on transcript system messages rather than in the provider context. `test/sdk-contract.test.ts` pins both assumptions provider-free.
+- [`@earendil-works/pi-coding-agent` 1.2.0](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) supplies the documented root exports used by this server, including `ModelRuntime` and `createAgentSession`. Since 0.99 the prompt preflight hook reports a dispatch disposition (`started`, `queued`, `handled`) and is not called on rejection; only `started` admits a public turn (`admitsTurn` in `src/sdk-pi-adapter.ts`). Model-visible tools are declared on transcript system messages rather than in the provider context. `test/sdk-contract.test.ts` pins both assumptions provider-free.
 - [`@modelcontextprotocol/server` 2.3.1](https://www.npmjs.com/package/@modelcontextprotocol/server) supplies `McpServer`, structured tool output, and the stdio entry point.
 - [Zod 4.6.5](https://zod.dev/) validates strict configuration, tool input, and structured output.
 

package/docs/client-setup-design.md

@@ -128,9 +128,20 @@ trash, delete the trash entry by entry, owned record. `--apply`, `--remove` and
 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.
+- 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
@@ -138,10 +149,22 @@ copies:
 - `--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.
+- 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.
@@ -264,29 +287,53 @@ 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_recovery_planned`, `skill_divergent`,
-  `skill_legacy_unverified`, `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`,

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

package/docs/installation.md

@@ -81,9 +81,13 @@ run.
 
 npm resolves the package's transitive dependencies at install time within the
 ranges that the Pi SDK and the MCP SDK declare, because npm does not ship a
-lockfile inside a package. Direct dependencies are pinned exactly. If you need
-the exact dependency tree that the maintainers tested, install from a release
-tag instead.
+lockfile inside a package. Direct dependencies are pinned exactly, and so are
+the SDK's internal `@earendil-works` packages (`pi-ai`, `pi-mcp`, `pi-tui`,
+`pi-codemode`, `pi-agent-core` and `pi-telemetry`, the last one declared by
+`pi-ai`), so that the SDK's caret ranges resolve to the tested versions.
+CI smoke-tests an install of the packed package without a lockfile on every
+change, and a nightly job does the same for the published `latest` version. If you need the exact dependency tree that the maintainers
+tested, install from a release tag instead.
 
 ### From a release tag
 

package/docs/releasing.md

@@ -16,19 +16,41 @@ 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
 files, the executables, the operator documentation and the example
 configuration. It contains no implementation plans (`docs/superpowers/`), and
-no lockfile, because npm does not ship lockfiles inside packages.
+no lockfile, because npm does not ship lockfiles inside packages. A consumer
+install therefore resolves every transitive range afresh, which is why the Pi
+SDK's own packages are pinned directly (see [Update the Pi SDK](#update-the-pi-sdk)).
 
 ## Update the Pi SDK
 
-The Pi SDK is pinned exactly. A nightly canary
-(`.github/workflows/pi-sdk-canary.yml`) checks the unchanged sources against the
-newest published `@earendil-works/pi-coding-agent`: typecheck plus every test
+The Pi SDK is pinned exactly, together with the SDK's internal
+`@earendil-works` packages: `pi-ai`, `pi-mcp`, `pi-tui`, `pi-codemode` and
+`pi-agent-core`, which the SDK declares, and `pi-telemetry`, which `pi-ai`
+declares. They are declared with caret ranges, and npm does not ship our
+lockfile inside the package, so a consumer install resolves those ranges fresh.
+A newer family member can then break the pinned SDK, as in
+[#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78), where
+`pi-codemode` 1.2.0 removed an export that `pi-coding-agent` 1.1.0 imports. We
+do not import the family members; they are direct, exactly pinned dependencies
+only so that a fresh install resolves the SDK's ranges to the tested versions.
+The SDK and the six packages therefore always move together, each to the
+version the canary resolves from the declared ranges.
+
+A nightly canary (`.github/workflows/pi-sdk-canary.yml`) checks the unchanged
+sources against the newest published `@earendil-works/pi-coding-agent` together
+with the family versions that candidate declares, transitively (a package that
+another member declares, such as `pi-telemetry`, is followed too): typecheck plus every test
 that touches the SDK, provider-free. It reports each incompatible version once
 in an open issue labeled `pi-sdk-canary`. A green canary is a signal that an
 update is possible. It is not an update and not an acceptance.
@@ -42,7 +64,8 @@ update is possible. It is not an update and not an acceptance.
    ```
 
    Exit status `0` means compatible, `1` incompatible, and `2` invalid input or
-   a changed manifest.
+   a changed manifest. The script prints the candidate and the family versions it
+   resolved from the declared ranges.
 
 2. Read the upstream changelog between the pinned and the target version. It
    ships in the package as
@@ -53,23 +76,32 @@ update is possible. It is not an update and not an acceptance.
    `src/session-tools.ts`. That function is not a root export, so no test
    notices when the SDK reserves another name.
 
-3. Move the pin:
+3. Move the pins, the SDK and its six family packages in one command:
 
    ```bash
-   npm install --save-exact @earendil-works/pi-coding-agent@<version>
+   npm install --save-exact \
+     @earendil-works/pi-coding-agent@<version> @earendil-works/pi-ai@<ai> \
+     @earendil-works/pi-mcp@<mcp> @earendil-works/pi-tui@<tui> \
+     @earendil-works/pi-codemode@<codemode> @earendil-works/pi-agent-core@<core> \
+     @earendil-works/pi-telemetry@<telemetry>
    ```
 
-   `package.json` must change in exactly one line and keep an exact version
-   without a range prefix. Review the lockfile diff: only the SDK's own packages
-   and their dependencies should move, and earlier lockfile-only patches must
-   survive.
+   Use the versions the canary reported. `package.json` must change in exactly
+   seven lines, one per package, and keep an exact version without a range
+   prefix. Check with `npm ls` that exactly one copy of each family package
+   exists.
+   Review the lockfile diff: only the SDK family and their dependencies should
+   move, and earlier lockfile-only patches must survive.
 
 4. Update the documents that name the pinned version,
    [architecture](architecture.md) and [tool contracts](tool-contracts.md), and
    add a changelog entry. Record upstream changes that affect operators, for
    example a renamed provider key.
 
-5. Run the [Level 1 checks](acceptance.md#level-1-repository-checks).
+5. Run the [Level 1 checks](acceptance.md#level-1-repository-checks). Before
+   the release, the packed-tarball check under
+   [Prepare a release](#prepare-a-release) shows whether a consumer install of
+   the new pins works.
 
 Three guards protect the SDK boundary. `test/sdk-contract.test.ts` pins the prompt
 dispositions, the rejection path and the exact tools declared to the model for
@@ -166,7 +198,29 @@ 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. Record the pre-release acceptance in the status section of
+6. Run the packed-tarball Level 2 acceptance on the same candidate. Pack the
+   built package, install the tarball into a fresh prefix and point the harness
+   at the installed package:
+
+   ```bash
+   npm pack
+   PREFIX="$(mktemp -d "$HOME/.cache/pi-session-mcp-pack.XXXXXX")"
+   npm install -g --prefix "$PREFIX" ./pi-session-mcp-<x.y.z>.tgz
+   node scripts/setup-acceptance.mjs \
+     --setup "$PREFIX/bin/pi-session-mcp-setup" \
+     --build-dir "$PREFIX/lib/node_modules/pi-session-mcp" \
+     --label packed-<x.y.z> --out level2-result.json
+   rm -rf "$PREFIX" ./pi-session-mcp-<x.y.z>.tgz
+   ```
+
+   This is the only acceptance-level pre-release check that resolves
+   dependencies like a consumer: the working tree and the CI build use our
+   lockfile, which a published package does not carry (#78). The CI install
+   smoke also resolves fresh, but it is an early warning, not acceptance. Always
+   use a fresh prefix from `mktemp -d`, never a fixed or reused one, and never
+   install without `--prefix`. Remove the prefix and the tarball afterwards; the
+   tarball is not committed.
+7. 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.