pi-session-mcp 0.12.0 → 0.12.1

package/.pi-session-mcp-cli/client-adapters/mcp-verifier.js

@@ -1,3 +1,4 @@
+import { isShortBranchName, MAX_WRITERS } from "../execution-modes.js";
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
 import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS } from "../session-tools.js";
 import { MAX_PROFILE_SKILLS } from "../skill-catalog.js";
@@ -106,8 +107,11 @@ function validCapabilities(value) {
         if (!workspace || typeof workspace !== "object")
             return false;
         const record = workspace;
-        return exactKeys(record, ["alias", "mode"]) && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
-            && typeof record.mode === "string" && ["unset", "host", "container", "read-only"].includes(record.mode);
+        return exactKeys(record, record.mode === "container" ? ["alias", "mode", "writers", "defaultBase"] : ["alias", "mode"])
+            && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
+            && typeof record.mode === "string" && ["unset", "host", "container", "read-only"].includes(record.mode)
+            && (record.mode !== "container" || (typeof record.writers === "number" && Number.isInteger(record.writers) && record.writers >= 1 && record.writers <= MAX_WRITERS
+                && (record.defaultBase === null || (typeof record.defaultBase === "string" && isShortBranchName(record.defaultBase)))));
     }))
         return false;
     if (!profiles.every((profile) => {

package/.pi-session-mcp-cli/execution-modes.js

@@ -5,6 +5,8 @@ import { ConfigError } from "./config.js";
 import { ImmutableMap } from "./execution-profile.js";
 import { isSafeRefName } from "./writer-boundary.js";
 export const EXECUTION_MODES_FILE = "execution-modes.json";
+/** Writers per container workspace; capabilities report it and setup verify checks it. */
+export const MAX_WRITERS = 16;
 /** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
 export function isShortBranchName(value) {
     return value.length <= 200
@@ -21,7 +23,7 @@ const entrySchema = z.discriminatedUnion("mode", [
     z.object({ mode: z.literal("read-only") }).strict(),
     z.object({
         mode: z.literal("container"),
-        writers: z.number().int().min(1).max(16).default(1),
+        writers: z.number().int().min(1).max(MAX_WRITERS).default(1),
         lifecycle: z.enum(["persistent", "ephemeral"]).default("persistent"),
         profiles: z.array(z.string()).min(1),
         image: z.union([z.literal("node"), z.string().regex(/^[0-9a-f]{64}$/)]).default("node"),

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.12.1 — 2026-10-28
+
+Patch release for
+[#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160). The MCP
+contract is unchanged. `npm audit` still reports `undici` 8.10.2, pinned by Pi
+SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+- Fixed: `setup --verify` of a client target failed with `mcp_failed` on every
+  installation with a `container` workspace. The verifier did not accept the
+  `writers` and `defaultBase` fields that 0.12.0 added to such workspaces in
+  `pi_capabilities_get`. It now accepts exactly these fields on container
+  workspaces, with `writers` from 1 to 16 and `defaultBase` `null` or a short
+  branch name, and still rejects them on every other mode. A new test verifies
+  the real server with container workspaces, which Level 2 does not configure
+  ([#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160)).
+- Changed: the upgrade runbook names the reset after migration. Migration keeps
+  each clone, so writers migrated from an older release lack the commit
+  identity until they are reset or finished.
+- Tests: the Doctor mode-order test no longer reads the host's writer lease
+  directory, which made it fail after a 0.12.0 migration.
+
 ## 0.12.0 — 2026-10-28
 
 Minor release under ADR 0003 for

package/README.md

@@ -30,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.12.0**.
+The package version is **0.12.1**.
 
 [Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 

package/dist/client-adapters/mcp-verifier.js

@@ -1,3 +1,4 @@
+import { isShortBranchName, MAX_WRITERS } from "../execution-modes.js";
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
 import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS } from "../session-tools.js";
 import { MAX_PROFILE_SKILLS } from "../skill-catalog.js";
@@ -106,8 +107,11 @@ function validCapabilities(value) {
         if (!workspace || typeof workspace !== "object")
             return false;
         const record = workspace;
-        return exactKeys(record, ["alias", "mode"]) && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
-            && typeof record.mode === "string" && ["unset", "host", "container", "read-only"].includes(record.mode);
+        return exactKeys(record, record.mode === "container" ? ["alias", "mode", "writers", "defaultBase"] : ["alias", "mode"])
+            && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
+            && typeof record.mode === "string" && ["unset", "host", "container", "read-only"].includes(record.mode)
+            && (record.mode !== "container" || (typeof record.writers === "number" && Number.isInteger(record.writers) && record.writers >= 1 && record.writers <= MAX_WRITERS
+                && (record.defaultBase === null || (typeof record.defaultBase === "string" && isShortBranchName(record.defaultBase)))));
     }))
         return false;
     if (!profiles.every((profile) => {

package/dist/execution-modes.d.ts

@@ -15,6 +15,8 @@ export interface WorkspaceModeEntry {
     readonly container?: ContainerSettings;
 }
 export declare const EXECUTION_MODES_FILE = "execution-modes.json";
+/** Writers per container workspace; capabilities report it and setup verify checks it. */
+export declare const MAX_WRITERS = 16;
 /** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
 export declare function isShortBranchName(value: string): boolean;
 export declare function executionModesPath(configPath: string): string;

package/dist/execution-modes.js

@@ -5,6 +5,8 @@ import { ConfigError } from "./config.js";
 import { ImmutableMap } from "./execution-profile.js";
 import { isSafeRefName } from "./writer-boundary.js";
 export const EXECUTION_MODES_FILE = "execution-modes.json";
+/** Writers per container workspace; capabilities report it and setup verify checks it. */
+export const MAX_WRITERS = 16;
 /** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
 export function isShortBranchName(value) {
     return value.length <= 200
@@ -21,7 +23,7 @@ const entrySchema = z.discriminatedUnion("mode", [
     z.object({ mode: z.literal("read-only") }).strict(),
     z.object({
         mode: z.literal("container"),
-        writers: z.number().int().min(1).max(16).default(1),
+        writers: z.number().int().min(1).max(MAX_WRITERS).default(1),
         lifecycle: z.enum(["persistent", "ephemeral"]).default("persistent"),
         profiles: z.array(z.string()).min(1),
         image: z.union([z.literal("node"), z.string().regex(/^[0-9a-f]{64}$/)]).default("node"),

package/dist/setup-writers.js

@@ -6,6 +6,7 @@ import { loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { ALIAS_PATTERN } from "./execution-profile.js";
 import { runDoctor } from "./doctor.js";
+import { MAX_WRITERS } from "./execution-modes.js";
 import { changeExecutionMode } from "./setup-modes.js";
 import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
 import { createCommandMcpStdioLauncher, createProcessRunner } from "./setup-process.js";
@@ -158,7 +159,7 @@ async function remove(ctx, name, discard, deps, extras = []) {
 const writerIndex = (name) => Number(name.slice(name.lastIndexOf("-w") + 2));
 async function plan(ctx, entry) {
     const keep = [], missing = [], surplus = [];
-    for (let index = 1; index <= 16; index++) {
+    for (let index = 1; index <= MAX_WRITERS; index++) {
         const name = writerName(ctx.alias, index), state = await readWriterState(ctx.home, name);
         if (entry.mode === "container" && index <= entry.container.writers) {
             keep.push(name);
@@ -322,7 +323,7 @@ export async function changeWriterMode(configPath, request, deps) {
                 return changeExecutionMode(configPath, request, modeDependencies);
             }
             writerWork = config.workspaceModes.get(request.alias)?.mode === "container";
-            for (let index = 1; index <= 16 && !writerWork; index++) {
+            for (let index = 1; index <= MAX_WRITERS && !writerWork; index++) {
                 try {
                     await lstat(join(writersRoot(deps.home ?? homedir()), writerName(request.alias, index)));
                     writerWork = true;
@@ -359,7 +360,7 @@ export async function changeWriterMode(configPath, request, deps) {
             const config = await loadConfig(configPath);
             if (!config.workspaceModes.get(request.alias)?.container?.base) {
                 const bases = new Set();
-                for (let index = 1; index <= 16; index++) {
+                for (let index = 1; index <= MAX_WRITERS; index++) {
                     const state = await readWriterState(deps.home ?? homedir(), writerName(request.alias, index));
                     if (state)
                         bases.add(state.base.ref);

package/docs/acceptance.md

@@ -2457,6 +2457,131 @@ Not established for `0.11.6`:
   wrapper's periodic credential copy (#136);
 - the VS Code wake; macOS delivery.
 
+### v0.12.1 pre-release acceptance
+
+`v0.12.1` was accepted on 2026-10-28 from 13:12 to 13:17 UTC on its release
+candidate `c6b472d`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.162.1` and Claude Code `2.1.312`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The patch ships #160 on top of 0.12.0. It does not change the MCP contract or
+the setup report schema.
+
+- Level 1 in a clean worktree of the candidate after `npm ci`: every command
+  exited with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    120 files, 3708 passed and 14 skipped, and no unhandled error. It ran on a
+    host with a real writer lease directory, which the Doctor mode-order test
+    no longer reads.
+  - `npm audit` exited with `1` and names only the known `undici` finding
+    through `@earendil-works/pi-coding-agent` 1.4.0
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 907 files (tarball shasum
+    `f206e0eb0818342fb9e6a36c2c147fb690c515ce`); a scan of the packed files for
+    private names, hosts and paths found none.
+  - Doctor reported `packageVersion` `0.12.1`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke reported `smoke_passed`
+  with version `0.12.1`.
+- In every Level 2 run the real client registrations and the built files were
+  unchanged, no process remained, and the leak check passed.
+- Podman-gated writer tests on the candidate: 4 of 4 passed.
+- The candidate's setup verifier against its own server with the operator's
+  real configuration, which has five container workspaces, reported
+  `verified`, with initialize, `tools/list` (eight tools) and
+  `pi_capabilities_get`. The same check with the installed 0.12.0 failed at
+  `pi_capabilities_get`.
+- Review: `review-glm` (another model family than the author) on the fix,
+  verdict `NON_BLOCKING_ONLY`; the shared writer bound and the real-server test
+  with container workspaces were added.
+
+Not established for `0.12.1`: client-target `--verify` through the installed
+package, which follows the upgrade; Level 3.
+
+### v0.12.0 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.12.0`.
+
+Tag binding: a fresh clone of the annotated tag `v0.12.0` (tag object
+`bb77dfd8a4e49849d5e9c7fd305fb00baf443044`) peels to the merge commit
+`dfbef8c5efce38eacc8704dbaf93c534cdad0ef8` of #159, and
+`git describe --tags --exact-match` reports `v0.12.0`. CI on the merge commit
+passed on Linux, macOS 15, macOS 26 and `verify` after one rerun: the first
+macOS 26 run hit a timeout in `test/extension-ablation-deps.test.ts`
+(5044 ms against 5000 ms), a git-heavy evaluation test that the release did not
+touch. CI on the tag passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`: typecheck, `build:cli`, the test
+  run (120 files, 3693 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean. Doctor
+  reported `packageVersion` `0.12.0`.
+- `pi-session-mcp@0.12.0` on npm: 907 files, shasum
+  `4699b05ef849e88c6d56f5ddae6b06984799cea6`, `gitHead` `1fb8a7e` (the head of
+  #159, whose tree equals the merge commit). A local `npm pack` of the merge
+  commit gives the same shasum. A scan of the published files for private
+  names, hosts and paths found none.
+- Published npm package, Level 2 from a fresh prefix: 160 of 160 with delivery
+  off and 228 of 228 with `--events spool`; the install smoke reported
+  `smoke_passed` with version `0.12.0`. Clients: Codex CLI `0.162.1` and Claude
+  Code `2.1.312`.
+- The GitHub release `v0.12.0` was published the same day.
+
+Operator upgrade of the workstation from `0.11.8` to `0.12.0` on 2026-10-28,
+following [Installation](installation.md#container-writers):
+
+- Coding sessions were closed and the two pi-session-mcp writer servers were
+  disabled in the controller; one idle controller of another repository still
+  had four writer containers running.
+- Both host client targets (`claude-code:user`, `codex:user`) were removed with
+  `0.11.8`, then `npm install -g pi-session-mcp@0.12.0`. Doctor reported
+  `packageVersion` `0.12.0` and, as expected, every writer `writer_not_ready`
+  and `writer_not_migrated`.
+- Five container repositories with 18 writers were migrated by repeating their
+  provisioning commands with unchanged settings, each first as a dry run
+  (`planned`), then with `--apply`: pi-session-mcp (2 writers), node-app (4),
+  go-app (4, operator image, `--cache go`), pynode-app (4, operator image,
+  base `dev`) and py-app (4, operator image). Every writer reported
+  `writer_accepted` and is `launch: "relay"`, `ready`, verdict `pass`. Each
+  repository recorded its shared default base (`main`, and `dev` for
+  pynode-app). All 36 owned writer registrations and their hook entries were
+  removed; the fence removed the four running legacy containers; no writer
+  container remained.
+- `--apply` of both client targets passed, but `--verify` failed with
+  `mcp_failed` on both:
+  [#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160). A direct
+  handshake with the installed server returned the eight tools and the
+  capabilities, including `writers` and `defaultBase` for each container
+  workspace; the 0.12.0 verifier rejected them. The fix, run with the real
+  configuration against the candidate's own server, reported `verified`.
+- `--writer <name> --verify` passed for all 18 writers over the relay path
+  (`mcp_verified`).
+- Live relayed coding session through the one host registration, after
+  reconnecting `pi-session-mcp`: `pi_capabilities_get` listed the container
+  workspaces with `writers` and `defaultBase`; `pi_session_start` with profile
+  `code` on the pi-session-mcp workspace leased `pi-session-mcp-w1` at
+  `refs/heads/main` and returned `writer` and `base`. The worker implemented
+  the #160 fix in two turns. Both turns woke the controller through the wake
+  hook from the host spool, without polling. Close, collect and finish
+  succeeded without a reconnect. A read-only `review-glm` session on the host
+  checkout reviewed the commit (`NON_BLOCKING_ONLY`).
+- The first turn could not commit: the migrated clones had no commit identity
+  (Doctor `writer_git_identity_missing` on all 18 writers), because migration
+  keeps the clone and only provisioning and reset copy the identity. After
+  `--finish` of the used writer and `--reset --apply` of the other 17, Doctor
+  reported no writer finding, and all 18 writers stayed `relay`, `ready` and
+  accepted. The upgrade runbook now names this step.
+
+Not established for `0.12.0`: the upgrade of the second machine; the live
+checks of #151 (`--cache uv`) and #154 (`--tags reachable`), which need a
+settings change of an existing writer; a busy-pool (`writer_unavailable`) and a
+`base` fix round in live use; Level 3.
+
 ### v0.12.0 pre-release acceptance
 
 `v0.12.0` was accepted on 2026-10-28 from 11:40 to 11:45 UTC on its release

package/docs/installation.md

@@ -756,6 +756,15 @@ repository step between the install and the client targets:
 3. `--apply` and `--verify` the client targets, then `--writer <name> --verify`
    for each writer. Reconnect the host `pi-session-mcp` server after migration
    and client setup. Later reset, finish and recreate need no reconnect.
+   On 0.12.0, client-target verify fails with `mcp_failed` once a container
+   workspace exists
+   ([#160](https://github.com/plagor44-ux/pi-session-mcp/issues/160)); 0.12.1
+   fixes it.
+4. Migration keeps each clone, so a writer migrated from a release before
+   0.12.0 has no commit identity yet, and Doctor reports
+   `writer_git_identity_missing`. Collect any work, then
+   `--writer <name> --reset --apply` (or `--finish --apply`) each writer;
+   reset copies the operator checkout's identity into the clone.
 
 The repository step does not count another repository's writers that are not
 ready yet, so the repositories can be accepted one after the other. Releases

package/docs/roadmap.md

@@ -15,7 +15,8 @@ mean they are implemented or that their gates passed.
 - 2026-10-28: [ADR 0012](adr/0012-leased-writer-pool.md) was accepted and
   implemented in #157: one host registration with a leased container writer
   pool, base-aware allocation and host-spool events. Prepared as minor release
-  0.12.0 together with #151 and #154; no new live acceptance is claimed.
+  0.12.0 together with #151 and #154, released the same day and installed with
+  a live relayed coding session; 0.12.1 fixes client-target verify (#160).
 
 The explicit 2026-10-17 user request adds a bounded development-only
 [token-footprint measurement](sprints/2026-10-17-token-footprint.md), following

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

package/package.json

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