pi-session-mcp 0.8.1 → 0.8.3

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/threat-model.md

@@ -29,7 +29,7 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
 - **Skill installation into clients:** `setup --apply` writes the controller skill `pi-session-orchestration` into the clients' skill directories, in the home directory (`~/.agents/skills`, `~/.claude/skills`) and, for Claude Code `project`, in the project that setup runs in (`<project>/.claude/skills`). What is written there becomes instructions for the controlling agent, so the copy is as trusted as the package or the override it comes from. Mitigations:
   - Copies come only from the package's `skills/` directory or from the operator's override directory next to the configuration file. No tool argument, client prompt or workspace names a source.
   - The override directory and its `.pi-session-mcp-bases.json` are operator-trusted configuration next to the configuration file, never a workspace. Keep them out of every workspace and writable only by the operator; a `coding` session that can write there could change what setup installs next.
-  - Setup reads a bounded tree of regular files (at most 32 files and 1 MiB, no links or special files) and installs it as a real copy, never as a link. The copy is staged and renamed into place. An update renames the old tree to a backup named after the pending record's transaction id and deletes it only after verifying that it is the exact old tree; leftover intermediates are deleted only by their exact names and only after verification, and anything modified or foreign stays (`skill_recovery_retained`).
+  - Setup reads a bounded tree of regular files (at most 32 files and 1 MiB, no links or special files) and installs it as a real copy, never as a link. The copy is staged and renamed into place. An update renames the old tree to a backup named after the pending record's transaction id and deletes it only after verifying that it is the exact old tree; leftover intermediates are deleted only by their exact names and only after verification (a leftover trash directory only while it still is the complete, unchanged replaced copy), and anything modified, foreign, partial or otherwise unprovable stays (`skill_recovery_retained`).
   - Setup never replaces or deletes a modified installed copy, hidden operator entries inside it, a foreign skill of the same name or a linked or non-directory entry; it reports `skill_divergent`. A link to exactly the effective skill is accepted as the operator's own (`skill_linked`) and never written through or deleted. Ownership records hold a version 2 content fingerprint (and, during an update, the replaced fingerprint), no path. A bare version 1 value from 0.8.0 names a copy only when a trusted reference (a released 0.8.0 shipped tree or the current library tree) has that value and the copy's exact bytes; otherwise setup reports `skill_legacy_unverified` and changes nothing; a project record carries an unsalted, truncated SHA-256 of the project's real path as an opaque identity, which someone who can read the state file could test against guessed paths.
   - A project may be untrusted. Inside a project setup never follows a link: any link below the project root makes the slot divergent, so a repository cannot redirect the write outside itself. In the home directory the client's skills directory may be the operator's own link (for example into a dotfiles checkout) and is followed; the skill entry itself is never followed.
   - `--customize-skill` writes only below the override directory, never overwrites an existing override and never edits an operator's file. It moves the recorded base only on an explicit `--apply`, which acknowledges a reviewed change to the shipped skill. `--apply` runs under an exclusive kernel lock on `<override dir>/.pi-session-mcp-bases.lock` and replaces the bases file atomically, so concurrent runs cannot lose a base; the dry-run takes no lock and writes nothing.

package/docs/tool-contracts.md

@@ -15,6 +15,24 @@ Every response includes text JSON for broad client compatibility and the same ob
 
 There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inventory exists.
 
+## Versions
+
+Three different versions exist. They identify different things and change for
+different reasons; none of them stands in for another.
+
+| Version | What it identifies | Where it appears | When it changes |
+| --- | --- | --- | --- |
+| Package version | One build and release of Pi Session MCP: the npm package, the GitHub release and the server. | `package.json`; `server.version` of `pi_capabilities_get`; `packageVersion` of the Doctor result | With every release. A release that keeps the MCP tool contract is a patch release. |
+| MCP tool contract | The eight tools of this document: their inputs, response fields, states and error codes. | Only this document. It carries no version number of its own and no tool, field or code names one. | A change to a tool, field, state or error code needs a new minor release and its own decision, so within a `0.x` minor line the contract is stable. A client identifies its compatibility by the package version, as `pi_capabilities_get` reports it, and by this document at that release. |
+| Setup report `schemaVersion` | The shape of the result of `pi-session-mcp-setup`, currently `1`; the human output derives from the same result. | The `schemaVersion` field of the `--json` report | Independent of the package version and no part of the MCP tool contract; a release does not change it by itself. It has been `1` since the first public release, and no document defines a further rule for changing it. |
+
+The setup report is not an MCP response. The Doctor result has its own
+`schemaVersion` (currently `1`), and the skill customization bases file has a
+`schemaVersion` (currently `2`) that is separate again; neither is the setup
+report's. Release rules are in [Releasing](releasing.md#versioning); acceptance
+records name the package version and the build they ran on, see
+[Acceptance](acceptance.md#evidence-rules).
+
 ## Capability discovery
 
 `pi_capabilities_get` accepts only `{}`. Unknown fields fail MCP schema validation. Success has this strict shape:
@@ -22,7 +40,7 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.8.1" },
+  "server": { "name": "pi-session-mcp", "version": "0.8.3" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -108,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.1",
+  "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"

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

@@ -78,8 +78,11 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 - `aborted` means the turn stopped. Look at what the workspace contains before reusing it.
 - `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.
 - `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Decide an observation and cleanup budget before you abort, for example a fixed number of polling rounds within a few minutes. Poll `pi_turn_get` until the turn is terminal or the budget is spent, then close the session with `pi_session_close`. If the close fails or does not finish, stop using that workspace, treat it as unverified and report it. Never wait without a bound.
-- On `pi_session_start` errors, do not retry blindly and do not change the profile. These codes need the operator; a retry cannot fix them: `unknown_execution_profile`, `unknown_workspace`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing` and `external_mcp_activation_mismatch`.
-- `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol) and `extension_load_failed` (an invalid package, but also a start timeout) can be transient. Retry at most once after a pause, then report.
+- Classify every `pi_session_start` error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Each code below is in exactly one class:
+  - Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `server_stopping`. The last code means the server is shutting down: a new server process is needed, not a retry.
+  - Transient (retry at most once after a pause, then report): `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol), `extension_load_failed` (an invalid package, but also a start timeout), `local_authentication_unavailable` (local authentication could not be resolved within its deadline).
+  - Unknown (report the code; at most one retry in a fresh session): `pi_session_creation_failed`. Any code not listed above is also unknown.
+- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`invalid_execution_profile_config` or `invalid_thinking_level`). No MCP server is available; the operator must fix the configuration.
 
 ## 10. Close every session