pi-session-mcp 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 0.8.3 — 2026-10-15
+
+- Fixed: a fresh `npm install -g pi-session-mcp@0.8.2` produced a server that
+  exited at startup. `@earendil-works/pi-coding-agent` 1.1.0 imports
+  `MCP_TYPESCRIPT_PREAMBLE` from `@earendil-works/pi-codemode` but declares it
+  as `^1.1.0`, and `pi-codemode` 1.2.0 removed that export. Consumers do not
+  receive our lockfile, so npm resolved the new version, while CI and the
+  acceptance runs used `npm ci` and never saw it. The SDK's internal
+  `@earendil-works` packages, including those declared by other family members
+  (`pi-telemetry` comes from `pi-ai`), are now direct, exactly pinned
+  dependencies. Issue #78.
+- Changed: Pi SDK 1.2.0 (was 1.1.0) with `@earendil-works/pi-ai`, `pi-mcp`,
+  `pi-tui`, `pi-codemode`, `pi-agent-core` and `pi-telemetry` pinned to 1.2.0.
+  The SDK no longer depends on `@earendil-works/chord`, so `esbuild` leaves the install.
+  Upstream changes that matter to operators: print mode (`pi -p`) now exits 1
+  with a warning when the final response was cut off at the output token limit;
+  Mistral streams are no longer aborted mid-generation after the request
+  timeout; "The upstream provider returned an error" is retried as a transient
+  provider error; and an OpenRouter key now lists only the models it may use.
+  For extensions, `before_agent_start` now also fires for runs started by
+  `pi.sendMessage(..., { triggerTurn: true })`, and its event became a union on
+  `messageType`; the allowlisted `pi-cursor-sdk` 0.5.3 registers that event and
+  the provider-free checks do not test it against SDK 1.2.0.
+  The tools declared to the model, the stop-reason mapping and the reserved MCP
+  tool names are unchanged. The Pi SDK canary now tests a candidate SDK together
+  with the family versions that candidate declares, resolved transitively.
+- Added: an install smoke (`scripts/install-smoke.mjs`) that starts an installed
+  server, checks its handshake, name, version and the eight tools, and requires
+  it to exit by itself with status 0 on stdin EOF. CI runs it on every change against the packed package
+  installed without a lockfile; a nightly workflow
+  (`.github/workflows/install-smoke.yml`) runs it against the published
+  `latest` and reports a failure in an issue labeled `install-smoke`.
+- Added: documentation of the packed-tarball Level 2 check, the only
+  acceptance-level pre-release check that resolves dependencies like a consumer
+  install. The CI install smoke also resolves fresh, but it is an early warning,
+  not acceptance. See
+  [releasing](docs/releasing.md#prepare-a-release) and
+  [acceptance](docs/acceptance.md#tooling).
+
 ## 0.8.2 — 2026-10-13
 
 - Fixed: recovery of an interrupted skill update no longer deletes operator

package/README.md

@@ -30,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.8.2**.
+The package version is **0.8.3**.
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.

package/dist/session-tools.js

@@ -9,7 +9,7 @@ export const PROFILE_TOOLS = {
  */
 const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
 /**
- * These mirror `isMcpToolName` of Pi SDK 1.1.0 (core/mcp-servers.js), which is not a root
+ * These mirror `isMcpToolName` of Pi SDK 1.2.0 (core/mcp-servers.js), which is not a root
  * export. When the allowlist names no `mcp__` entry, the SDK's `_isAllowedTool` keeps such
  * tools outside the allowlist for codemode and tool_search, so an extension tool with one
  * of these names could be active without being granted. This server's own MCP bridge

package/docs/acceptance.md

@@ -132,6 +132,17 @@ prefix (`npm install -g --prefix <dir> pi-session-mcp@<version>`) and runs the
 lifecycle through the installed `pi-session-mcp-setup`, which also proves the
 executables and the entry-point detection through npm's symlinks.
 
+A packed-tarball run installs the tarball of the release candidate, before it is
+published, into a fresh temporary prefix (`npm pack`, then
+`npm install -g --prefix <dir> ./pi-session-mcp-<version>.tgz`, with `<dir>`
+created by `mktemp -d` and removed afterwards) and runs the lifecycle through
+the installed `pi-session-mcp-setup`. It is the only acceptance-level
+pre-release check that resolves dependencies like a consumer install does,
+without our lockfile, before publication. The working-tree run and the CI build
+cannot prove that, because they install from the lockfile; the CI install smoke
+also resolves fresh, but it is an early warning, not acceptance. The packed
+tarball run is the pre-release counterpart of the published-package run.
+
 A published-release run uses a fresh clone of the published tag instead of an
 existing branch or local tag. It additionally records the tag object and the
 peeled commit, confirms `git describe --tags --exact-match`, passes Level 1 on
@@ -179,6 +190,35 @@ node scripts/setup-acceptance.mjs \
   --label npm-<version> --out level2-result.json
 ```
 
+Packed tarball: pack the built candidate and install the tarball into a fresh
+temporary prefix outside `/tmp`, then pass the installed executable and package
+directory as for the published package. Create the prefix with `mktemp -d`,
+never reuse a fixed one, and remove it and the tarball afterwards.
+
+```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
+```
+
+The CI job and a nightly workflow (`.github/workflows/install-smoke.yml`) run
+`scripts/install-smoke.mjs` against a lockfile-free install: CI against the
+packed tarball of the commit, the nightly job against the published
+`pi-session-mcp@latest`. The smoke starts the installed server, checks the
+handshake, its name and version and the eight tools, and requires it to exit by
+itself with status 0 after stdin EOF. It starts no session and uses no provider.
+It reports one JSON line whose code is `smoke_passed` or one of
+`package_invalid`, `server_exited`, `initialize_invalid`, `tools_invalid`,
+`stdout_invalid`, `shutdown_timeout`, `shutdown_failed` or `timeout`. On any
+failure it kills the server's whole process group. Both are early warnings for
+a broken fresh install, not acceptance and not a replacement for the
+packed-tarball run.
+
 Tag clone: build a fresh clone of the tag (`npm ci`, `npm run build`,
 `npm run build:cli`) and use it like the working tree, with `--setup` and
 `--build-dir` pointing at the clone.
@@ -1429,6 +1469,122 @@ release candidate `bdbdf00` on Linux (`x64`), with Node.js `26.11.1`, Codex CLI
   [Sprint 3 live acceptance](#sprint-3-live-acceptance-2026-10-13) ran, including
   the accepted ten-task Level 3 cycle.
 
+### v0.8.2 post-release evidence
+
+The published-release acceptance of `v0.8.2` ran on 2026-10-15 from 15:36 UTC
+on Linux (`x64`) with Node.js `26.11.1`, npm `12.2.0`, Codex CLI `0.162.1` and
+Claude Code `2.1.299`. It **failed** for the installed npm package; the tag
+passed. The failure is recorded as it happened and is tracked as
+[#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78).
+
+Tag binding: a fresh clone of the annotated tag `v0.8.2` (tag object
+`d068067539a5cf86917e0be08014c9535dce0cc2`) peels to
+`bdfb95de9a46defa64d2eb382d58d454f97fc8fb`, the merge of #76, and
+`git describe --tags --exact-match` reports `v0.8.2`.
+
+Provider-free (Level 1), on that clone. Every command exited with `0`:
+- 54 test files: 1409 passed and 6 skipped, with strict unhandled rejections
+  and no unhandled error.
+- `npm audit` and `npm audit --omit=dev`: 0 vulnerabilities.
+- `git diff --check` and `git status --short` printed nothing.
+- Offline Doctor with the example configuration: `packageVersion` `0.8.2`;
+  its only finding was the placeholder workspace (`workspace_missing`).
+
+`package.json`, `package-lock.json`, `dist/main.js` and the whole `dist` tree
+(84 files) were byte-identical before and after the client cycles.
+`dist/main.js` has the SHA-256 of the release build
+(`47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`).
+
+Real clients without a model (Level 2), with `scripts/setup-acceptance.mjs`:
+- Tag clone: 160 of 160 checks passed; all nine steps passed on all four
+  targets. The real client registrations were unchanged, no process
+  remained, and the build stayed byte-identical.
+- npm package, installed with `npm install -g --prefix` into a temporary
+  prefix: the installed version is `0.8.2`, the registry shasum is
+  `1ab640909d8c513f3dbaad3c3691f7ce1f267945` and `dist/main.js` has the same
+  SHA-256 as above. **151 of 160 checks passed.** `--verify` (steps 5 and 8)
+  reported `mcp_unsupported` instead of `mcp_verified` on all four targets;
+  every other step passed, no process remained and the package stayed
+  byte-identical. `realRegistrationsUnchanged` was `false` (see below).
+
+Cause of the verify failure (#78): the prefix resolved
+`@earendil-works/pi-codemode` `1.2.0`, while the lockfile pins `1.1.0`. The
+pinned Pi SDK `1.1.0` declares it as `^1.1.0`, and `1.2.0` no longer exports
+`MCP_TYPESCRIPT_PREAMBLE`, which the SDK imports. Started directly, the
+installed `dist/main.js` exits with `1` and a `SyntaxError` before its first
+MCP frame; the tag clone's server answers `initialize`. Verify reports a
+server that exits before `initialize` as `mcp_unsupported`. The published
+bytes are correct; a fresh install of them is not. Installations made before
+`pi-codemode` `1.2.0` was published (2026-10-12, 23:00 UTC) keep `1.1.0` and
+start.
+
+`realRegistrationsUnchanged` `false`: the cause was not determined. Another
+process wrote the real Codex configuration file during the npm run (15:39:09
+UTC). Afterwards no real registration referenced the run's directories, the
+real setup ownership records were unchanged since 2026-10-13, and the real
+Claude Code registration still targeted the installed `0.8.1`. A live client
+that changes its registrations during a run is a known source of a false
+failure (see [Tooling](#tooling)); the check is not counted as passed.
+
+A run against the published release on 2026-10-14 was reported with exit `0`,
+but neither its variant nor its check counts were saved; it is not evidence.
+
+Result: `v0.8.2` is accepted as a release source (tag clone), not as an
+installed npm package. Fresh npm installs of `0.8.2`, and probably of every
+version that pins the Pi SDK `1.1.0`, crash at startup.
+
+### v0.8.3 pre-release acceptance
+
+Before its release, `v0.8.3` passed Level 1, the working-tree Level 2 and the
+new packed-tarball Level 2 on its release candidate `35091eb` on Linux
+(`x64`), with Node.js `26.11.1`, npm `12.2.0`, Codex CLI `0.162.1` and Claude
+Code `2.1.299`, on 2026-10-15:
+- Level 1 on the release branch: every command exited with `0`.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    55 files, 1425 passed and 6 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 136 files, including the three
+    skills, and no acceptance harness, sources, tests, lockfile or
+    implementation plan.
+  - Doctor reported `packageVersion` `0.8.3`. With the example configuration
+    its only finding was the placeholder workspace.
+- Level 2 through `scripts/setup-acceptance.mjs` on the candidate's working
+  tree: 160 of 160 checks passed. All nine steps passed on all four targets.
+  The real client registrations were unchanged, no process remained, and the
+  built files were unchanged.
+- Packed-tarball Level 2 (#78): the candidate's tarball, installed with
+  `npm install -g --prefix` into a fresh prefix without the lockfile, resolved
+  every `@earendil-works` package to `1.2.0` with a single copy each. The install
+  smoke reported `smoke_passed`, and Level 2 against the installed package
+  passed 160 of 160 checks, with the same unchanged registrations, process
+  and build results.
+
+Targeted live multi-session acceptance on the new Pi SDK `1.2.0`, with
+`scripts/multi-session-acceptance.mjs` (harness SHA-256 prefix `bb1620ad`) on a
+clean detached checkout of `16b2374`, the candidate before the review fixes:
+`dist/main.js` SHA-256 `47875d38…`, build digest `c5e91f70…`. Between `16b2374`
+and `35091eb` no runtime source changed; the lockfile gained only the root
+entry that pins `@earendil-works/pi-telemetry` at the `1.2.0` it already
+resolved. Strictly sequential runs on 2026-10-15 from 18:19 UTC, with
+synthetic fixtures and the worker profiles copied from the operator profiles
+without their external MCP grant:
+
+| Profile source | Extension | Controller | Scenario | Result | Duration |
+| --- | --- | --- | --- | --- | --- |
+| DeepSeek `deepseek-flash`, `high` | none | Codex `0.162.1` | `abort` | passed, no failure | 101 s |
+| DeepSeek `deepseek-flash`, `high` | none | Claude Code `2.1.299` | `parallel` | passed, no failure | 66 s |
+| Cursor `grok-4.7@256k:fast`, `high` | `pi-cursor-sdk` `0.5.3` | Claude Code `2.1.299` | `abort` | passed, no failure | 156 s |
+| Cursor `grok-4.7@256k:fast`, `high` | `pi-cursor-sdk` `0.5.3` | Codex `0.162.1` | `parallel` | passed, no failure | 146 s |
+
+Every run kept its scope, closed its sessions and left no residual process.
+The Cursor runs load the allowlisted `pi-cursor-sdk` `0.5.3`, which registers
+`before_agent_start`, whose semantics changed in SDK `1.2.0`; both passed.
+
+Not established for `0.8.3`: the ten-task Level 3 cycle on SDK `1.2.0`, the
+`trio` scenario, the operator profiles' external MCP grant, macOS on real
+hardware (R10, R11), and other providers and models. The published-release
+acceptance follows after publication.
+
 ## Sprint 1 correctness checks (2026-10-13)
 
 These checks belong to [#59](https://github.com/plagor44-ux/pi-session-mcp/issues/59)

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/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

@@ -28,13 +28,29 @@ 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.
@@ -48,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
@@ -59,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
@@ -172,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.
 

package/docs/roadmap.md

@@ -12,8 +12,8 @@ mean they are implemented or that their gates passed.
 
 ## Current state
 
-Updated 2026-10-13. Base main `0aae6390c539e1d70138f1efaf297e6193a2b497`
-(the merge of Sprint 2).
+Updated 2026-10-15. Base main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb`
+(the merge of the 0.8.2 release).
 
 - R21 (this roadmap) was delivered as documentation by
   [#58](https://github.com/plagor44-ux/pi-session-mcp/pull/58), which closed
@@ -39,17 +39,30 @@ Updated 2026-10-13. Base main `0aae6390c539e1d70138f1efaf297e6193a2b497`
   ([#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74)). R10 and R11
   are blocked on the work Mac, with a runbook. See the
   [Sprint 3 file](sprints/2026-10-13-s3-live-usage.md).
-- Release 0.8.2 is prepared in its own pull request: it carries #59, #56, #60
-  and the #62 skill change to npm under an unchanged MCP contract. Merge, tag
-  and publication are maintainer decisions.
+- Release 0.8.2 was merged in [#76](https://github.com/plagor44-ux/pi-session-mcp/pull/76)
+  and published on 2026-10-14. It carries #59, #56, #60 and the #62 skill
+  change under an unchanged MCP contract. Its published-release acceptance on
+  2026-10-15 found that a fresh npm install crashes at startup
+  ([#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78)); the fix
+  ships as 0.8.3.
 - Sprint 4 decision inputs for the conditional items R12, R15, R17 and R18 are recorded in the [Sprint 4 decision inputs](sprints/2026-10-13-s4-decision-inputs.md) ([#72](https://github.com/plagor44-ux/pi-session-mcp/issues/72)): R12, R15 and R17 not met, R18 not determinable as of 2026-10-13; this is input, not the Sprint 4 decision.
+- Sprint 4 is closed with its [decision](sprints/2026-10-15-s4-decision.md)
+  ([#77](https://github.com/plagor44-ux/pi-session-mcp/issues/77)), taken on
+  2026-10-15 before the macOS gate by maintainer decision. ADR 0003's isolation
+  trigger fired, because coding profiles had written on non-disposable
+  repositories. The one next investment is the isolation decision
+  ([#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79), ADR 0008
+  Proposed), with interim operating rules until it is accepted. R12, R15 and
+  R17 stay deferred (not met), R18 stays deferred (not determinable), and
+  [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) is closed as
+  not planned. R10, R11 and R22 stay open.
 
 ### Sprint 3 task status
 
 | Task | Issue | Status |
 | --- | --- | --- |
 | Harness tests time out on macOS | [#70](https://github.com/plagor44-ux/pi-session-mcp/issues/70) | verified: CI green on macOS 15 and 26, also on main |
-| R08 three sessions with a read-only reviewer | [#71](https://github.com/plagor44-ux/pi-session-mcp/issues/71) | partially verified: Codex passed, Claude Code failed on timing only; follow-up [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) |
+| R08 three sessions with a read-only reviewer | [#71](https://github.com/plagor44-ux/pi-session-mcp/issues/71) | partially verified: Codex passed, Claude Code failed on timing only; follow-up [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) closed as not planned in Sprint 4 |
 | R05 / R09 ten-task Level 3 cycle | None (acceptance) | verified: accepted, 10 of 10 tasks |
 | R06 new Codex abort run | None (acceptance) | verified |
 | R07 Codex discovery of the setup-installed skill | None (acceptance) | verified |
@@ -58,8 +71,8 @@ Updated 2026-10-13. Base main `0aae6390c539e1d70138f1efaf297e6193a2b497`
 
 Status words: planned, in progress, implemented (code exists), verified (named
 criteria met with evidence), blocked, failed (ran and missed its criteria; kept
-on record). Sprint 3 is closed; Sprint 4 decides the next investment
-from the evidence of Sprints 1 to 3 and the decision inputs.
+on record). Sprints 1 to 4 are closed; the next investment is the isolation
+decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79).
 
 ## Sprints and exit gates
 
@@ -111,7 +124,7 @@ in-memory state and one trusted local peer.
 
 | Topic | Entry condition |
 | --- | --- |
-| OS isolation | Decide before coding on non-disposable repositories or with untrusted content; profiles/skills are not an OS sandbox |
+| OS isolation | Trigger fired on 2026-10-15 (coding profiles wrote on non-disposable repositories); decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) and ADR 0008, interim rules in the [Sprint 4 decision](sprints/2026-10-15-s4-decision.md#interim-operating-rules); profiles/skills are not an OS sandbox |
 | pi_turn_wait | Measured high polling cost per turn with pauses or tool/approval cost; 5–7 polls per invocation is insufficient evidence |
 | Persistence/resume | Actual loss of useful work on restart |
 | HTTP/remote/mobile | Concrete need existing SSH/remote development cannot meet; separate ADR/security decision |
@@ -121,7 +134,7 @@ in-memory state and one trusted local peer.
 | Former pi-control #31/#32 | Closed as not_planned; no automatic migration/reopening |
 | Former release gates/#11–#14 | Historical; bind current acceptance to the current build |
 
-0.8.2 is a possible patch candidate only if the MCP contract remains
-unchanged and its gates pass. Sprint 1 changed no version. Apply the current [release procedure](releasing.md):
-version and pre-release acceptance travel in the change PR. Merge, tagging and
+0.8.3 is a patch release only if the MCP contract remains unchanged and its
+gates pass. Apply the current [release procedure](releasing.md): version and
+pre-release acceptance travel in the change PR. Merge, tagging and
 publication remain maintainer decisions. No release is authorized by this plan.

package/docs/sprints/2026-10-15-s4-decision.md

@@ -0,0 +1,185 @@
+# Sprint 4: next-investment decision
+
+Date: 2026-10-15. Base: main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb` (the
+merge of the 0.8.2 release pull request). Tracking:
+[#77](https://github.com/plagor44-ux/pi-session-mcp/issues/77). Planning
+sources: the [roadmap](../roadmap.md), the
+[post-0.8.1 audit](../reviews/2026-10-13-post-0.8.1-audit.md#sprint-4-decide-the-next-investment-from-usage)
+and the [Sprint 4 decision inputs](2026-10-13-s4-decision-inputs.md).
+
+Exit gate from the audit: a documented decision, at most one next investment,
+a focused issue, and an appropriate ADR for scope or contract changes. No
+feature implementation without a separate justified decision.
+
+## Decision
+
+| Topic | Decision |
+| --- | --- |
+| Next investment | One: decide isolation for coding profiles on non-disposable repositories, as an options comparison in ADR 0008 (Proposed), tracked in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79). No runtime change before ADR 0008 is accepted. |
+| ADR 0003 | Trigger E fired on 2026-10-15; [ADR 0003](../adr/0003-post-mvp-maintenance.md#revisit-triggers) records it, as it already does for the B-type trigger. Candidates C, D and F stay rejected with their revisit triggers. |
+| Interim operation | The maintainer keeps the operating rules below until ADR 0008 is accepted, with the residual risks stated there. |
+| Maintenance | Continues. The fresh-install defect found during this sprint ([#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78)) is maintenance, not the investment, and ships as patch 0.8.3. |
+| R12, R15, R17 | Not met; stay deferred with their entry conditions. |
+| R18 | Not determinable; stays deferred unless the maintainer decides to harden publication independently. |
+| [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) | Closed as not planned (maintainer decision). The strict neighbor criterion stays; the `trio` timing with Claude Code as controller remains "not established". Reopen when a usage claim needs it. |
+| R10, R11, R22 | Open, blocked on operator actions (work Mac; ChatGPT project instructions). Nothing here claims macOS acceptance. |
+
+The maintainer decided on 2026-10-15 to run this evaluation before the
+current macOS acceptance (R10, R11), although the audit's dependency graph
+places that acceptance before Sprint 4. The macOS gate affects platform
+claims, not which investment comes next; it stays open.
+
+## Usage evidence from Sprint 3
+
+Sources: [Sprint 3](2026-10-13-s3-live-usage.md) and
+[Acceptance](../acceptance.md#sprint-3-live-acceptance-2026-10-13).
+
+- The ten-task Level 3 cycle was accepted 10 of 10 with Claude Code `2.1.296`
+  and Codex CLI `0.162.1` on Linux `x64`, in six strictly sequential
+  invocations of 56–94 s each. The worker profiles were copies (`l3-read`,
+  `l3-code`) of `explore-fast` and `code-deepseek`, without the operator
+  profiles' external MCP grant. No change fell outside the approved diff, and
+  no session or process remained.
+- R06 (Codex abort, 100 s) and R07 (Codex discovery of the setup-installed
+  skill) passed. R08 `trio` passed for Codex (102 s); Claude Code (118 s)
+  failed only `neighborsNotRunningDuringAbort`, a timing outcome of the
+  scenario design (#74).
+- Polling: in Level 3, every turn was seen `running` in at most one
+  `pi_turn_get` poll, and both clients slept between polls. This counts polls
+  that saw a running turn, not `pi_turn_get` calls per turn; R06 and R08
+  record no poll counts. ADR 0003's baseline is 1–3 calls per turn.
+- Restarts: Sprint 3 records no restart result, and Level 3 excludes restart
+  and resume. No record reports useful work lost to a restart.
+- All recorded coding ran on synthetic fixtures; the `review` fixture of
+  `trio` is a frozen read-only fixture.
+- Not established: macOS, other providers and models, the operator profiles'
+  external MCP grant, larger tasks, more than three concurrent sessions, and
+  the `trio` timing with Claude Code as controller.
+
+## New facts on 2026-10-15
+
+- The maintainer confirmed that coding profiles have already written on
+  non-disposable repositories through configured workspace aliases (real
+  repositories and their worktrees). No incident is known: no unintended
+  change, push or write outside a workspace has been reported, but the use was
+  not audited systematically. Profiles, poll counts and restarts of that use
+  were not recorded, so it is not usage evidence in the sense of the
+  acceptance records.
+- The published-release acceptance of v0.8.2 found that a fresh
+  `npm install -g pi-session-mcp@0.8.2` installs a server that exits at
+  startup ([#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78);
+  evidence in [Acceptance](../acceptance.md#v082-post-release-evidence)). The
+  pinned Pi SDK `1.1.0` declares its sibling `@earendil-works/pi-codemode` with
+  a caret range, `pi-codemode` `1.2.0` removed an export the SDK imports, and
+  installed packages do not get this repository's lockfile. CI, the canary and
+  the pre-release acceptance all install from the lockfile, so none of them
+  saw it.
+
+## Revisit triggers of ADR 0003
+
+| Candidate | ADR 0003 status | Trigger | Assessment |
+| --- | --- | --- | --- |
+| C: bounded turn waiting | Rejected | Routinely more than about five polls per turn, or costly client tool-call limits or approval prompts | Not evidenced in recorded use: Level 3 saw a running turn in at most one poll; the real-repository use was not measured |
+| D: persistence and resume | Rejected | Useful work lost to a restart in practice | Not evidenced: no record and no report of lost work; restarts were not part of the recorded runs |
+| E: isolation | Deferred | Coding profiles on non-disposable repositories or with untrusted content, at the latest before a local writer runs on real repositories | **Fired** on 2026-10-15 (maintainer confirmation above) |
+| F: remote transport | Rejected | A concrete remote or mobile case that SSH or remote development cannot meet | Not fired: no such case |
+| B-type work | Delivered | Repeated setup or diagnosis friction beyond version drift | Fired earlier for the client-version allowlist (ADR 0004); no new repeated friction recorded |
+
+The audit's guidance applies: if real writing is next, isolation is the first
+architecture question. Real writing is not next; it has already happened.
+
+## The next investment: decide isolation
+
+[#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) authorizes a
+decision, not an implementation. Sprint 4 decides that isolation is next, not
+how. ADR 0008 (Proposed) must compare at least:
+
+1. operator-environment containment with no server change (separate OS user,
+   container or VM per writer, separate clone);
+2. whole-process self-restriction of the server on Linux, and the macOS
+   equivalent or gap;
+3. moving Pi out of process per session, which would amend ADR 0002.
+
+Two facts constrain the options. `edit` and `write` run inside the server
+process and only `bash` runs as a child process, so confining `bash` alone
+would give false assurance. One server process serves every session of a
+client, so whole-process confinement can only allow the union of all
+workspaces plus Pi's agent directory and the provider network. The ADR also
+names the threats each option addresses: model error, prompt injection from
+repository content or `AGENTS.md`, and trusted extension code. Filesystem
+confinement does nothing against extension code or exfiltration through the
+provider. Its acceptance is a synthetic isolated-write test that covers
+`edit` and `write` as well as `bash`.
+
+The strongest argument against expansion remains the security and
+maintenance surface it adds to a deliberately small local server; option 1
+keeps that surface unchanged.
+
+## Interim operating rules
+
+Maintainer decision on 2026-10-15: until ADR 0008 is accepted, coding
+profiles keep running on non-disposable repositories under these rules. They
+are operator practice; the server enforces none of them.
+
+- Coding profiles only on dedicated worktrees of trusted repositories, one
+  writer per alias; never on untrusted content.
+- Skill catalog and override directories outside every workspace.
+- Every worker diff is reviewed before it leaves the worktree.
+- Cursor-backed profiles only where a write would be uncritical.
+
+These rules limit the damage of mistakes. They do not contain a misbehaving
+worker. Accepted residual risks, as the two reviews of this decision named
+them:
+
+- A Git worktree is not a boundary: it shares configuration, hooks, refs and
+  objects with its main repository, so a change to `.git/hooks` or
+  `.git/config` can run code in the operator's later Git commands.
+- `bash` runs with the server's OS identity, network access and inherited
+  credentials, so a worker can commit, push, or call `gh` and `ssh` before any
+  diff review.
+- Files outside the workspace stay reachable, among them the Pi Session MCP
+  configuration file, client configurations, the installed controller skills,
+  shell start-up files, user cron and service units, `~/.ssh` and any other
+  credential readable by the OS identity; `read` is not path-confined in
+  `read-only` profiles either.
+- The Cursor runtime starts processes of its own (`git`, `ssh`, `gh`, its MCP
+  servers), also in `read-only` profiles, and can write below `~/.pi/agent`,
+  `~/.cursor/projects/` and `<workspace>/.pi/`.
+- External MCP grants of the operator profiles were not covered by acceptance.
+- No decision date is set for ADR 0008, so the interim period is open-ended.
+
+## Conditional items, re-checked on 2026-10-15
+
+| Item | Facts | Assessment |
+| --- | --- | --- |
+| R17 scheduled advisory check | `npm audit` and `npm audit --omit=dev` at `bdfb95d`: 0 vulnerabilities (331 dependencies). Dependabot alerts enabled, 0 open; no `.github/dependabot.yml` | Not met |
+| R18 provenance | None of 0.6.1–0.8.2 carries an attestation. 1,284 downloads in the npm window 2026-09-13 to 2026-10-12 (daily from 2026-10-07: 59, 15, 150, 349, 342, 369). One star, no forks or watchers; 14-day traffic 1,116 clones (308 unique) and 54 views (4 unique). Of 47 issues only #28 and #29 come from another account; all 29 pull requests from the maintainer | Not determinable: the counts cannot separate external users from mirrors, automation and the maintainer's own installations |
+| R12 real crash, contention, signal runs | No report of an interrupted real skill update, a customization conflict or a signal-ended analysis | Not met |
+| R15 unreadable start time | No Sprint 3 live run failed with `noServerObserved` | Not met |
+
+#78 is not drift in the sense of R17: `npm audit` reports advisories, not
+broken resolutions. Its detection, a lockfile-free install smoke in CI and
+nightly, belongs to #78.
+
+## Reviews of this decision
+
+The draft was reviewed on 2026-10-15 by an independent advisor (Claude Opus
+5.5) and by a read-only Pi worker of another model family (`review-grok`,
+xAI `grok-4.7`). Their corrections are applied above: C, D and F are rejected
+in ADR 0003, not deferred; the B-type trigger fired before; Level 3 used
+profile copies; the polling observation counts running sightings, not calls;
+the investment is a decision with option 1 included, not a predetermined
+OS-isolation build; ADR 0003 is annotated instead of a separate Sprint 4 ADR.
+The reviewers also recommended stricter interim rules; the maintainer kept
+the rules above and the residual risks are recorded instead.
+
+## Sources and checks
+
+- Sprint 3 records, Acceptance, ADRs 0002–0004, the threat model and
+  `src/session-tools.ts`, read on 2026-10-15.
+- `npm audit` and `npm audit --omit=dev` at `bdfb95d`; the npm registry
+  metadata of `pi-session-mcp`; the npm download API; the GitHub API for
+  repository statistics, traffic, Dependabot alerts and authorship; all
+  read-only, 2026-10-15 (15:36 UTC).
+- The published-release acceptance of v0.8.2 and the reproduction of #78,
+  recorded in [Acceptance](../acceptance.md#v082-post-release-evidence).

package/docs/tool-contracts.md

@@ -40,7 +40,7 @@ records name the package version and the build they ran on, see
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.8.2" },
+  "server": { "name": "pi-session-mcp", "version": "0.8.3" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -126,7 +126,7 @@ none of the eight public tools or their fields, states and error codes; see the
 bounded projection policy in [session-mcp.md](session-mcp.md). If the turn itself
 fails, the public result still contains only `turn_failed` / `Pi turn failed`.
 
-`turn_failed` remains the only terminal failure projection. The characterization was made against `@earendil-works/pi-coding-agent` 0.84.4, which exposes no closed, structured terminal cause discriminator; its provider-free tests keep their assertions on the pinned 1.0.4, whose public `AssistantMessage` type still carries only the stop reason plus free-form `errorMessage`, `rawStopReason`, and open-typed `diagnostics`, and Pi Session MCP uses no such discriminator: it normalizes the final assistant outcome by its stop reason (`src/sdk-pi-adapter.ts:106-130`, see *Final stop reasons* below) and the registry projects `turn_failed` for every outcome that is neither `completed` nor `aborted` (`src/session-registry.ts:242-243`). Retry and compaction events can describe an interim error that later recovers. Assistant `errorMessage`, `rawStopReason`, and `diagnostics` are free-form and may contain sensitive provider text; they cannot reliably identify the underlying terminal cause.
+`turn_failed` remains the only terminal failure projection. The characterization was made against `@earendil-works/pi-coding-agent` 0.84.4, which exposes no closed, structured terminal cause discriminator; its provider-free tests keep their assertions on the pinned 1.2.0, whose public `AssistantMessage` type still carries only the stop reason plus free-form `errorMessage`, `rawStopReason`, and open-typed `diagnostics`, and Pi Session MCP uses no such discriminator: it normalizes the final assistant outcome by its stop reason (`src/sdk-pi-adapter.ts:106-130`, see *Final stop reasons* below) and the registry projects `turn_failed` for every outcome that is neither `completed` nor `aborted` (`src/session-registry.ts:242-243`). Retry and compaction events can describe an interim error that later recovers. Assistant `errorMessage`, `rawStopReason`, and `diagnostics` are free-form and may contain sensitive provider text; they cannot reliably identify the underlying terminal cause.
 
 This change therefore adds no runtime classification: no code is derived from `errorMessage`, `rawStopReason`, diagnostics, context size, or event order, and no provider text, diagnostics, or context figure is projected. In particular `turn_context_exceeded` is not added; an observed pattern (a long same-session turn fails, a fresh narrow session succeeds) stays a hypothesis that the public surface cannot confirm.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [
@@ -54,7 +54,13 @@
     "prepack": "npm run build && npm run build:cli"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-agent-core": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-codemode": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-mcp": "1.2.0",
+    "@earendil-works/pi-telemetry": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/server": "2.3.1",
     "zod": "4.6.5"