pi-session-mcp 0.6.2 → 0.6.4

package/.pi-session-mcp-cli/doctor-cli.js

@@ -1,11 +1,15 @@
+import { fileURLToPath } from "node:url";
 import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+// The generated CLI lives one level below the package root. An npm executable runs
+// from any directory, so the working directory says nothing about the package.
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const options = parseDoctorArgs(process.argv.slice(2));
 if (!options) {
     process.stderr.write("Usage: doctor [--json]\n");
     process.exitCode = 64;
 }
 else {
-    const result = await runDoctor();
+    const result = await runDoctor({ packageRoot: PACKAGE_ROOT });
     process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
     process.exitCode = result.exitCode;
 }

package/.pi-session-mcp-cli/doctor.js

@@ -104,8 +104,15 @@ export async function runDoctor(dependencies = {}) {
             const packageMtime = (await fs.stat(join(root, "package.json"))).mtimeMs;
             const lockMtime = await lockfileMtime(fs, root);
             const inputMtimes = [packageMtime, lockMtime].filter((value) => value !== undefined);
-            if (!dependencies.fileSystem)
-                inputMtimes.push(...await productionBuildInputMtimes(root));
+            if (!dependencies.fileSystem) {
+                const buildInputMtimes = await productionBuildInputMtimes(root);
+                // npm writes an installed package at extraction time in archive order, so without
+                // build inputs the manifest times say nothing about the freshness of the build.
+                if (buildInputMtimes.length === 0)
+                    inputMtimes.length = 0;
+                else
+                    inputMtimes.push(...buildInputMtimes);
+            }
             if (inputMtimes.some((mtime) => mtime > buildMtime))
                 checks.push(warning("build_stale", "build output", "run the production build"));
             else

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.6.4 — 2026-10-10
+
+- `pi-session-mcp-doctor` now checks the package it belongs to, whatever the
+  current directory is. Previously it checked the current directory: in an npm
+  installation, run from another directory, it failed with
+  `package_metadata_unreadable` and `build_missing`, and inside another
+  checkout it reported that checkout. `npm run doctor` in a release checkout
+  and `setup` were not affected.
+- The installation guide and client setup reference now say that Codex
+  rewrites `config.toml` when a registration changes: it groups the
+  `[mcp_servers.*]` tables and drops comments directly above them. Copy the
+  file first if its comments matter.
+- The client setup reference now explains that `codex exec` rejects
+  `pi_session_prompt`, `pi_session_abort` and `pi_session_close` unless they
+  are approved, because it never asks and the tools are marked destructive. It
+  shows the per-run `-c` approvals.
+
+## 0.6.3 — 2026-10-10
+
+- Doctor no longer reports a false `build_stale` warning right after
+  `npm install` with npm 12. npm 12 writes extracted files with the extraction
+  time, and the package lists `dist/` before `package.json`, so the installed
+  manifest was always newer than the build. An installation without build
+  configuration or TypeScript sources no longer compares manifest times; a
+  source checkout still does.
+- `setup` was re-recorded against Claude Code `2.1.296`; its `mcp` command
+  contract is unchanged.
+
 ## 0.6.2 — 2026-10-09
 
 - The server now shuts down when the MCP client closes its stdin. Previously

package/README.md

@@ -29,7 +29,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.6.2**.
+The package version is **0.6.4**.
 
 - **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 only**, Node.js 22.19.0 or newer.

package/dist/doctor-cli.js

@@ -1,11 +1,15 @@
+import { fileURLToPath } from "node:url";
 import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+// The generated CLI lives one level below the package root. An npm executable runs
+// from any directory, so the working directory says nothing about the package.
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const options = parseDoctorArgs(process.argv.slice(2));
 if (!options) {
     process.stderr.write("Usage: doctor [--json]\n");
     process.exitCode = 64;
 }
 else {
-    const result = await runDoctor();
+    const result = await runDoctor({ packageRoot: PACKAGE_ROOT });
     process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
     process.exitCode = result.exitCode;
 }

package/dist/doctor.js

@@ -104,8 +104,15 @@ export async function runDoctor(dependencies = {}) {
             const packageMtime = (await fs.stat(join(root, "package.json"))).mtimeMs;
             const lockMtime = await lockfileMtime(fs, root);
             const inputMtimes = [packageMtime, lockMtime].filter((value) => value !== undefined);
-            if (!dependencies.fileSystem)
-                inputMtimes.push(...await productionBuildInputMtimes(root));
+            if (!dependencies.fileSystem) {
+                const buildInputMtimes = await productionBuildInputMtimes(root);
+                // npm writes an installed package at extraction time in archive order, so without
+                // build inputs the manifest times say nothing about the freshness of the build.
+                if (buildInputMtimes.length === 0)
+                    inputMtimes.length = 0;
+                else
+                    inputMtimes.push(...buildInputMtimes);
+            }
             if (inputMtimes.some((mtime) => mtime > buildMtime))
                 checks.push(warning("build_stale", "build output", "run the production build"));
             else

package/docs/acceptance.md

@@ -147,6 +147,9 @@ snapshot and digest tools and the scan for leaked values are prepared per cycle.
 - Clients: record the exact client versions and how each client reached the
   server. Prefer a temporary per-invocation MCP configuration, so that no
   global registration changes.
+- Waiting: let each client wait a bounded time between `pi_turn_get` polls,
+  for example by allowing a shell `sleep` of a few seconds. A client that may
+  call only the Pi Session MCP tools has no way to wait and polls back to back.
 - Pre-registration: fix the plan, the acceptance criteria per task, the prompts,
   the oracles, the tools, the configurations and the fixture digests before the
   first task.
@@ -182,6 +185,10 @@ repeat a task.
 - Liveness: a running turn whose `updatedAt` advanced beyond `startedAt` shows
   observable activity. Its absence only means that the turn finished between
   two polls.
+- Polling cost: count the `pi_turn_get` calls per turn. The counts are evidence
+  for the revisit trigger on bounded waiting in
+  [ADR 0003](adr/0003-post-mvp-maintenance.md) only when the client could wait
+  between polls.
 
 ### Gate
 
@@ -225,3 +232,40 @@ Release notes state which levels were run for a release and what was not
 covered. Pi Session MCP has passed all three levels in earlier private cycles. The
 live two-client acceptance has not yet been repeated on a build with Pi SDK
 `1.x`.
+
+`v0.6.2` passed Level 1 on a fresh clone of its tag. It passed Level 2 in all
+three variants: working tree, published release, and published npm package.
+The clients were Codex CLI `0.162.0` (`user`) and Claude Code `2.1.295`
+(`user`, `project`, `local`), on 2026-10-09 and 2026-10-10. It had no Level 3
+cycle.
+
+Before its release, `v0.6.3` passed Level 1 and the working-tree Level 2 on its
+release candidate, with Claude Code `2.1.296`. On 2026-10-10 the same candidate
+also passed a narrower live check:
+- Scope: Claude Code `2.1.296` as the only client, with Pi SDK `1.1.0` on a
+  local `qwen3.6-35b-a3b-splash` model served by LM Studio.
+- All five tasks of the matrix reached their intended outcome in three
+  sequential invocations, and every pre-registered check passed.
+- It covered no Codex task and does not count as a ten-task cycle.
+
+After its release, `v0.6.3` passed Level 1 on a fresh clone of its tag. It also
+passed Level 2 as published release and as published npm package, with Codex
+CLI `0.162.0` and Claude Code `2.1.296`, on 2026-10-10.
+
+On 2026-10-10, `main` at `4d333da`, which is `v0.6.3` plus the Doctor fix and
+documentation, passed a narrower live check with Codex:
+- Scope: Codex CLI `0.162.0` as the only client, run headless with
+  `codex exec` and the three tool approvals that
+  [client setup](client-setup.md#run-codex-without-prompts) describes. Pi SDK
+  `1.1.0` ran on the same local model.
+- All five tasks of the matrix reached their intended outcome in three
+  sequential invocations, and every pre-registered check passed.
+- The client could wait between polls and needed 1 to 3 `pi_turn_get` calls per
+  turn.
+- It covered no Claude Code task and does not count as a ten-task cycle. The
+  Claude Code check above ran on another commit.
+
+Before its release, `v0.6.4` passed Level 1 and the working-tree Level 2 on its
+release candidate, with Codex CLI `0.162.0` and Claude Code `2.1.296`. Its
+server entry point `dist/main.js` is byte-identical to that of `4d333da` and of
+`v0.6.3`.

package/docs/client-setup.md

@@ -122,6 +122,37 @@ codex mcp list
 codex mcp get pi-session-mcp
 ```
 
+`codex mcp add` and `codex mcp remove` rewrite `config.toml`. Codex CLI
+`0.162.0` groups all `[mcp_servers.*]` tables together and drops a comment
+directly above such a table; settings are preserved. Copy the file first if its
+comments matter to you.
+
+### Run Codex without prompts
+
+Interactive Codex asks before it calls a tool that is marked
+`destructiveHint: true`: `pi_session_prompt`, `pi_session_abort` and
+`pi_session_close`. `codex exec` never asks, so Codex CLI `0.162.0` rejects
+these calls with "MCP tool call requires approval, but approval policy is
+never". A headless run can then start sessions but cannot prompt, abort or
+close them.
+
+Approve the three tools for each headless run:
+
+```bash
+codex exec \
+  -c 'mcp_servers.pi-session-mcp.tools.pi_session_prompt.approval_mode="approve"' \
+  -c 'mcp_servers.pi-session-mcp.tools.pi_session_abort.approval_mode="approve"' \
+  -c 'mcp_servers.pi-session-mcp.tools.pi_session_close.approval_mode="approve"' \
+  'Your task'
+```
+
+The same `approval_mode` entries can live in `config.toml` under
+`[mcp_servers.pi-session-mcp.tools.<tool>]`. They do not change the output of
+`codex mcp get`, so `setup` still treats the registration as equal. But
+`codex mcp remove`, which `setup --remove` and `--rollback` use, deletes them,
+so they are gone after an upgrade. The per-run overrides do not have this
+problem.
+
 ## Register with Claude Code
 
 Claude Code CLI 2.1.251 was locally confirmed with this command form. Replace every absolute-path placeholder with your local paths; use absolute paths for the Node executable, built entry point, and configuration file.

package/docs/doctor-design.md

@@ -3,6 +3,8 @@
 `src/doctor-cli.ts` is a separate local entry point. It never imports the MCP
 server, initializes transport, creates a Pi session, reads credentials, or
 performs network activity.
+It checks the package it was loaded from, never the current working
+directory: an npm executable can run from any directory.
 
 `runDoctor` returns one frozen result model (`schemaVersion: 1`, `ok`, a
 sanitized semver `packageVersion` when metadata is available, ordered `checks`,
@@ -20,7 +22,7 @@ and owners are:
 | `node_version_unsupported` | Runtime does not satisfy `package.json#engines.node` | `Node.js` |
 | `package_metadata_unreadable` | Package metadata is missing, unreadable or malformed, or a lockfile is present but malformed | `package metadata` |
 | `build_missing` | `dist/main.js` is absent, inaccessible, or not a regular file | `build output` |
-| `build_stale` | Package, lock, build configuration, or production TypeScript input is newer than the build output, or freshness cannot be established. Inputs that an npm installation does not contain are skipped | `build output` |
+| `build_stale` | Package, lock, build configuration, or production TypeScript input is newer than the build output, or freshness cannot be established. Inputs that an npm installation does not contain are skipped. Without any build configuration or TypeScript input, as in an npm installation, the package and lock times are not compared either, because npm writes extracted files with the extraction time | `build output` |
 | `version_mismatch` | Package and lock versions differ; this is a warning and does not apply to an npm installation, which has no lockfile | `package version` |
 | `config_missing` | `PI_SESSION_MCP_CONFIG` is not set, or the file it names is absent | `configuration` |
 | `config_unreadable` | The supported configuration path cannot be read | `configuration` |

package/docs/installation.md

@@ -47,7 +47,7 @@ the same arguments.
 - Codex CLI or Claude Code. `setup` does not pin client versions. It accepts a
   client whose public `mcp` command output matches the expected contract and
   reports `unsupported` otherwise. The contract was last recorded with Codex CLI
-  `0.162.0` and Claude Code `2.1.295`. Manual registration, described in the
+  `0.162.0` and Claude Code `2.1.296`. Manual registration, described in the
   [client setup reference](client-setup.md), works independently of `setup`.
 - For real prompts only: local Pi authentication and a provider and model pair
   that the local Pi configuration knows. Installation, Doctor and `setup` need
@@ -207,6 +207,13 @@ pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
 pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
 ```
 
+`setup` changes a Codex registration only through `codex mcp add` and
+`codex mcp remove`, and Codex rewrites `config.toml` on each of them. Codex CLI
+`0.162.0` groups all `[mcp_servers.*]` tables together and drops a comment
+directly above such a table; settings are preserved. If your `config.toml`
+contains comments worth keeping, copy it before `--apply`, `--rollback` or
+`--remove` on `codex:user:pi-session-mcp`.
+
 Each report has one line for the operation with its overall status, and one line
 per target with a finding in the form `status (code)`:
 

package/docs/tool-contracts.md

@@ -22,7 +22,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.6.2" },
+  "server": { "name": "pi-session-mcp", "version": "0.6.4" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [