pi-session-mcp 0.11.9 → 0.12.1

package/dist/writer-relay.d.ts

@@ -0,0 +1,33 @@
+import { type Transport } from "@modelcontextprotocol/client";
+import type { WorkspaceModeEntry } from "./execution-modes.js";
+import type { ConfiguredExecutionProfile } from "./execution-profile.js";
+import { type PiSessionAdapter, type PiSessionHandle } from "./pi-adapter.js";
+export declare const RELAY_START_BUDGET_MS = 60000;
+export declare const RELAY_POLL_INTERVAL_MS = 1000;
+export declare const RELAY_CALL_TIMEOUT_MS = 10000;
+export declare const RELAY_PREFLIGHT_DEADLINE_MS = 15000;
+export declare const RELAY_ABORT_DEADLINE_MS = 15000;
+export declare const RELAY_CLEANUP_DEADLINE_MS = 10000;
+export declare const RELAY_MAX_RESPONSE_BYTES = 524288;
+export interface WriterProcessFactory {
+    spawn(wrapperPath: string, env: Record<string, string>): Transport;
+}
+export declare class WriterRelayAdapter implements PiSessionAdapter {
+    private readonly options;
+    constructor(options: {
+        home: string;
+        workspaceModes: ReadonlyMap<string, WorkspaceModeEntry>;
+        executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
+        spawn?: WriterProcessFactory;
+        now?: () => number;
+        pollIntervalMs?: number;
+    });
+    create(input: Parameters<PiSessionAdapter["create"]>[0]): Promise<PiSessionHandle>;
+}
+export declare class RoutingPiSessionAdapter implements PiSessionAdapter {
+    private readonly host;
+    private readonly relay;
+    private readonly workspaceModes;
+    constructor(host: PiSessionAdapter, relay: PiSessionAdapter, workspaceModes: ReadonlyMap<string, WorkspaceModeEntry>);
+    create(input: Parameters<PiSessionAdapter["create"]>[0]): Promise<PiSessionHandle>;
+}

package/dist/writer-relay.js

@@ -0,0 +1,359 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { Client } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import { ChildStdioTransport } from "./child-stdio-transport.js";
+import { PiSessionCreationError, WriterUnavailableError } from "./pi-adapter.js";
+import { RegistryError } from "./session-registry.js";
+import { capabilitiesSchema, errorSchema, promptSuccessSchema, successSchema, turnSuccessSchema } from "./tool-schemas.js";
+import { writerPaths } from "./writer-state.js";
+export const RELAY_START_BUDGET_MS = 60_000;
+export const RELAY_POLL_INTERVAL_MS = 1_000;
+export const RELAY_CALL_TIMEOUT_MS = 10_000;
+export const RELAY_PREFLIGHT_DEADLINE_MS = 15_000;
+export const RELAY_ABORT_DEADLINE_MS = 15_000;
+export const RELAY_CLEANUP_DEADLINE_MS = 10_000;
+// The inner text cap is 64 KiB; JSON escaping can grow it up to sixfold.
+export const RELAY_MAX_RESPONSE_BYTES = 524_288;
+// Read the launch discriminator locally until all writer-state producers have migrated.
+// Unknown fields are deliberately tolerated; no clone inspection is an admission check.
+const relayStateSchema = z.object({
+    alias: z.string(), index: z.number().int(), phase: z.enum(["ready", "not_ready", "provisioning"]),
+    launch: z.enum(["legacy", "relay"]).default("legacy"),
+    acceptance: z.object({ verdict: z.literal("pass"), fingerprint: z.string(), at: z.string(), network: z.enum(["limited", "not_limited"]) }).optional(),
+    base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/) }),
+});
+async function readState(home, name) {
+    try {
+        const file = await open(writerPaths(home, name).state, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > RELAY_MAX_RESPONSE_BYTES)
+                return undefined;
+            const state = relayStateSchema.parse(JSON.parse(await file.readFile("utf8")));
+            return `${state.alias}-w${state.index}` === name ? state : undefined;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bounds even injected transports which ignore AbortSignal. The losing operation stays observed. */
+async function bounded(operation, ms, signal) {
+    const controller = new AbortController();
+    let timer;
+    let cancel;
+    try {
+        return await Promise.race([
+            new Promise((_, reject) => {
+                cancel = () => { controller.abort(); reject(new Error("Relay operation cancelled")); };
+                signal?.addEventListener("abort", cancel, { once: true });
+                timer = setTimeout(cancel, Math.max(0, ms));
+                if (signal?.aborted || ms <= 0)
+                    cancel();
+            }),
+            Promise.resolve().then(() => { controller.signal.throwIfAborted(); return operation(controller.signal); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (cancel)
+            signal?.removeEventListener("abort", cancel);
+    }
+}
+const creationCodes = new Set([
+    "unknown_provider", "unknown_model", "local_authentication_missing", "local_authentication_unavailable",
+    "model_unavailable", "thinking_level_unavailable", "execution_selection_mismatch", "external_mcp_unavailable",
+    "external_mcp_no_tools", "external_mcp_grant_tool_missing", "external_mcp_activation_mismatch",
+    "extension_not_installed", "extension_version_mismatch", "extension_load_failed", "extension_tool_conflict",
+    "extension_tool_missing", "skill_load_failed", "pi_session_creation_failed",
+]);
+class InnerError extends Error {
+    code;
+    constructor(code) {
+        super("Writer refused the operation");
+        this.code = code;
+    }
+}
+class Connection {
+    transport;
+    client = new Client({ name: "pi-session-mcp-relay", version: "1" }, { capabilities: {} });
+    lost = false;
+    onLost;
+    tools = [];
+    constructor(transport) {
+        this.transport = transport;
+        const lost = () => { this.lost = true; this.onLost?.(); };
+        this.client.onclose = lost;
+        this.client.onerror = lost;
+    }
+    async connect(ms, signal) {
+        await bounded(s => this.client.connect(this.transport, { signal: s, timeout: ms }), ms, signal);
+    }
+    async discover(ms, signal) {
+        const result = await bounded(s => this.client.listTools({}, { signal: s, timeout: ms }), ms, signal);
+        this.tools = result.tools;
+    }
+    async call(name, args, schema, ms = RELAY_CALL_TIMEOUT_MS, signal) {
+        const toolDefinition = this.tools.find(tool => tool.name === name);
+        if (!toolDefinition)
+            throw new Error("Writer tool missing");
+        const result = await bounded(s => this.client.callTool({ name, arguments: args }, { signal: s, timeout: ms, maxTotalTimeout: ms, resetTimeoutOnProgress: false, toolDefinition }), ms, signal);
+        try {
+            const raw = result.structuredContent;
+            const encoded = JSON.stringify(raw);
+            if (encoded === undefined || Buffer.byteLength(encoded) > RELAY_MAX_RESPONSE_BYTES)
+                throw new Error();
+            const refusal = errorSchema.safeParse(raw);
+            if (refusal.success)
+                throw new InnerError(refusal.data.error.code);
+            return schema.parse(raw);
+        }
+        catch (error) {
+            if (error instanceof InnerError)
+                throw error;
+            this.lost = true;
+            this.onLost?.();
+            throw new Error("Invalid writer response");
+        }
+    }
+    async cleanup(sessionId, ms = RELAY_CLEANUP_DEADLINE_MS) {
+        // One deadline covers the RPC AND transport close, not two consecutive deadlines.
+        const end = Date.now() + ms;
+        try {
+            if (sessionId && !this.lost)
+                await this.call("pi_session_close", { sessionId }, successSchema, Math.max(0, end - Date.now()));
+        }
+        catch { /* EOF still requests launcher cleanup. */ }
+        finally {
+            try {
+                const closing = this.transport.close();
+                void closing.catch(() => undefined);
+                await bounded(() => closing, Math.max(0, end - Date.now()));
+            }
+            catch { /* bounded shutdown */ }
+        }
+    }
+}
+class RelayHandle {
+    connection;
+    placement;
+    pollIntervalMs;
+    sdkSessionId;
+    appliedSelection;
+    deadlines = { preflightMs: RELAY_PREFLIGHT_DEADLINE_MS, abortMs: RELAY_ABORT_DEADLINE_MS, cleanupMs: RELAY_CLEANUP_DEADLINE_MS };
+    active;
+    disposed = false;
+    disposal;
+    constructor(connection, session, placement, pollIntervalMs) {
+        this.connection = connection;
+        this.placement = placement;
+        this.pollIntervalMs = pollIntervalMs;
+        this.sdkSessionId = session.id;
+        this.appliedSelection = { provider: session.provider, model: session.model, thinkingLevel: session.thinkingLevel };
+        connection.onLost = () => this.settle({ status: "failed" });
+    }
+    isLost() { return this.connection.lost; }
+    settle(outcome) { const active = this.active; this.active = undefined; active?.settle(outcome); }
+    lose() { this.connection.lost = true; this.settle({ status: "failed" }); }
+    observe(turn) {
+        const active = this.active;
+        if (!active || turn.turnId !== active.turnId || turn.sessionId !== this.sdkSessionId) {
+            this.lose();
+            return;
+        }
+        if (active.updatedAt !== undefined && active.updatedAt !== turn.updatedAt)
+            active.activity?.();
+        active.updatedAt = turn.updatedAt;
+        if (turn.state === "completed")
+            this.settle({ status: "completed", assistantText: turn.assistantText, truncated: turn.truncated });
+        else if (turn.state === "aborted" || turn.state === "failed")
+            this.settle({ status: turn.state });
+    }
+    async prompt(text, preflight, onActivity) {
+        if (this.isLost() || this.disposed)
+            throw new RegistryError("writer_session_lost");
+        if (this.active)
+            throw new Error("Relay turn already running");
+        let settle;
+        const outcome = new Promise(resolve => { settle = resolve; });
+        const active = { settle, activity: onActivity };
+        this.active = active;
+        try {
+            const result = await this.connection.call("pi_session_prompt", { sessionId: this.sdkSessionId, prompt: text }, promptSuccessSchema);
+            if (result.turn.state !== "running" || result.session.id !== this.sdkSessionId) {
+                this.lose();
+                preflight(false);
+            }
+            else if (this.active === active) {
+                active.turnId = result.turn.turnId;
+                active.updatedAt = result.turn.updatedAt;
+                preflight(true);
+                void this.poll(active);
+            }
+            else
+                preflight(false);
+        }
+        catch (error) {
+            preflight(false);
+            if (!(error instanceof InnerError) && !this.isLost()) {
+                // Acceptance is uncertain: ask the inner registry to settle before returning failure.
+                try {
+                    await this.abort();
+                }
+                catch {
+                    this.lose();
+                }
+            }
+            this.settle({ status: "failed" });
+        }
+        return outcome;
+    }
+    async poll(active) {
+        while (this.active === active && !this.isLost() && !this.disposed) {
+            await new Promise(resolve => setTimeout(resolve, this.pollIntervalMs));
+            if (this.active !== active || this.isLost() || this.disposed)
+                return;
+            try {
+                const { turn } = await this.connection.call("pi_turn_get", { sessionId: this.sdkSessionId, turnId: active.turnId }, turnSuccessSchema);
+                // An abort may have settled this turn and a new prompt may already be running.
+                if (this.active === active)
+                    this.observe(turn);
+            }
+            catch {
+                this.lose();
+            }
+        }
+    }
+    async abort() {
+        if (this.isLost())
+            throw new Error("Writer session lost");
+        const active = this.active;
+        try {
+            await bounded(async (signal) => {
+                const result = await this.connection.call("pi_session_abort", { sessionId: this.sdkSessionId }, successSchema, RELAY_CALL_TIMEOUT_MS, signal);
+                if (result.session.id !== this.sdkSessionId)
+                    throw new Error("Writer session mismatch");
+                if (!active || this.active !== active)
+                    return;
+                // A lost prompt response has no turn ID. It cannot be safely resumed.
+                if (!active.turnId)
+                    throw new Error("Writer turn unknown");
+                const { turn } = await this.connection.call("pi_turn_get", { sessionId: this.sdkSessionId, turnId: active.turnId }, turnSuccessSchema, RELAY_CALL_TIMEOUT_MS, signal);
+                if (turn.state === "running")
+                    throw new Error("Writer abort incomplete");
+                if (this.active === active)
+                    this.observe(turn);
+            }, RELAY_ABORT_DEADLINE_MS);
+        }
+        catch {
+            this.lose();
+            throw new Error("Writer abort failed");
+        }
+    }
+    dispose() {
+        if (!this.disposal) {
+            this.disposed = true;
+            this.settle({ status: "failed" });
+            this.disposal = this.connection.cleanup(this.sdkSessionId);
+        }
+        return this.disposal;
+    }
+}
+export class WriterRelayAdapter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async create(input) {
+        if (process.platform !== "linux")
+            throw new WriterUnavailableError("none_ready");
+        const now = this.options.now ?? Date.now, end = now() + RELAY_START_BUDGET_MS;
+        const left = () => Math.max(0, end - now());
+        const remaining = () => Math.min(RELAY_CALL_TIMEOUT_MS, left());
+        const settings = this.options.workspaceModes.get(input.workspace)?.container;
+        const ready = [];
+        for (let i = 1; i <= (settings?.writers ?? 0); i++) {
+            const name = `${input.workspace}-w${i}`, state = await readState(this.options.home, name);
+            if (state?.phase === "ready" && state.launch === "relay" && state.acceptance)
+                ready.push({ name, state });
+        }
+        if (!ready.length)
+            throw new WriterUnavailableError("none_ready");
+        const base = input.base ?? settings?.base;
+        const candidates = base === undefined ? [] : ready.filter(({ state }) => state.base.ref === `refs/heads/${base}`);
+        if (!candidates.length)
+            throw new WriterUnavailableError("none_at_base");
+        const counts = { busy: 0, notAtBaseline: 0, settingsChanged: 0 };
+        const env = { HOME: this.options.home };
+        for (const key of ["PATH", "XDG_RUNTIME_DIR"])
+            if (process.env[key] !== undefined)
+                env[key] = process.env[key];
+        const factory = this.options.spawn ?? { spawn: (wrapper, environment) => new ChildStdioTransport(wrapper, environment) };
+        for (const candidate of candidates) {
+            input.signal?.throwIfAborted();
+            if (left() <= 0)
+                break;
+            let connection, sessionId, admitted = false;
+            try {
+                connection = new Connection(factory.spawn(writerPaths(this.options.home, candidate.name).wrapper, env));
+                // The handshake waits for credential warm-up and the container start: it may use the whole budget.
+                await connection.connect(left(), input.signal);
+                await connection.discover(remaining(), input.signal);
+                const capabilities = await connection.call("pi_capabilities_get", {}, capabilitiesSchema, remaining(), input.signal);
+                const inner = capabilities.executionProfiles.find(profile => profile.alias === input.executionProfile.alias);
+                const host = this.options.executionProfiles.get(input.executionProfile.alias);
+                if (!host || !inner || ["permissionProfile", "provider", "model", "thinkingLevel"].some(key => inner[key] !== host[key])) {
+                    counts.settingsChanged++;
+                    continue;
+                }
+                const result = await connection.call("pi_session_start", { workspace: input.workspace, executionProfile: input.executionProfile.alias }, successSchema, remaining(), input.signal);
+                sessionId = result.session.id;
+                if (remaining() <= 0 || connection.lost)
+                    continue;
+                const state = await readState(this.options.home, candidate.name);
+                if (!state || state.base.ref !== candidate.state.base.ref || state.base.commit !== candidate.state.base.commit)
+                    continue;
+                input.signal?.throwIfAborted();
+                admitted = true;
+                return new RelayHandle(connection, result.session, { writer: candidate.name, base: state.base }, this.options.pollIntervalMs ?? RELAY_POLL_INTERVAL_MS);
+            }
+            catch (error) {
+                if (input.signal?.aborted)
+                    throw input.signal.reason;
+                if (error instanceof InnerError) {
+                    if (error.code === "writer_busy")
+                        counts.busy++;
+                    else if (error.code === "writer_uncollected")
+                        counts.notAtBaseline++;
+                    else if (!["writer_fenced", "writer_not_ready", "container_runtime_unavailable"].includes(error.code)) {
+                        const code = error.code;
+                        throw new PiSessionCreationError(creationCodes.has(code) ? code : "pi_session_creation_failed");
+                    }
+                }
+            }
+            finally {
+                // Own bound, not the start budget: a started inner session is always closed explicitly.
+                if (!admitted && connection)
+                    await connection.cleanup(sessionId);
+            }
+        }
+        throw new WriterUnavailableError("none_admitted", counts);
+    }
+}
+export class RoutingPiSessionAdapter {
+    host;
+    relay;
+    workspaceModes;
+    constructor(host, relay, workspaceModes) {
+        this.host = host;
+        this.relay = relay;
+        this.workspaceModes = workspaceModes;
+    }
+    create(input) {
+        return (input.executionProfile.permissionProfile === "coding" && this.workspaceModes.get(input.workspace)?.mode === "container" ? this.relay : this.host).create(input);
+    }
+}

package/dist/writer-state.d.ts

@@ -17,6 +17,10 @@ export declare const writerStateSchema: z.ZodObject<{
         ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
+    launch: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        relay: "relay";
+    }>>;
     profiles: z.ZodReadonly<z.ZodArray<z.ZodString>>;
     providers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         provider: z.ZodString;
@@ -29,7 +33,12 @@ export declare const writerStateSchema: z.ZodObject<{
     cache: z.ZodEnum<{
         go: "go";
         none: "none";
+        uv: "uv";
     }>;
+    tags: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        reachable: "reachable";
+    }>>;
     imageId: z.ZodString;
     base: z.ZodObject<{
         ref: z.ZodString;
@@ -49,7 +58,9 @@ export declare const writerStateSchema: z.ZodObject<{
         at: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export type WriterState = z.infer<typeof writerStateSchema>;
+export type WriterState = Omit<z.infer<typeof writerStateSchema>, "launch"> & {
+    launch?: "legacy" | "relay";
+};
 export declare function writerName(alias: string, index: number): string;
 export declare function writerRegistrationName(name: string): string;
 export declare function writersRoot(home: string): string;
@@ -61,6 +72,7 @@ export declare function writerPaths(home: string, name: string): {
     config: string;
     events: string;
     go: string;
+    uv: string;
     wrapper: string;
     state: string;
     acceptanceFailure: string;

package/dist/writer-state.js

@@ -24,13 +24,15 @@ export const writerStateSchema = z.object({
     index: indexSchema,
     phase: z.enum(["provisioning", "ready", "not_ready"]),
     lifecycle: z.enum(["persistent", "ephemeral"]),
+    launch: z.enum(["legacy", "relay"]).default("legacy"),
     profiles: z.array(aliasSchema).min(1).readonly(),
     providers: z.array(z.object({
         provider: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
         model: z.string().min(1).max(200),
     }).strict()).refine((providers) => new Set(providers.map(({ provider }) => provider)).size === providers.length).readonly(),
     network: z.enum(["pasta", "none"]),
-    cache: z.enum(["none", "go"]),
+    cache: z.enum(["none", "go", "uv"]),
+    tags: z.enum(["none", "reachable"]).default("none"),
     imageId: hex64,
     base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/) }).strict(),
     acceptance: z.object({
@@ -60,7 +62,7 @@ export function writerPaths(home, name) {
     const root = join(writersRoot(home), name);
     return {
         root, clone: join(root, "clone"), agent: join(root, "agent"), bundles: join(root, "bundles"),
-        config: join(root, "config"), events: join(root, "events"), go: join(root, "go"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
+        config: join(root, "config"), events: join(root, "events"), go: join(root, "go"), uv: join(root, "uv"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
         acceptanceFailure: join(root, "acceptance-failure.json"),
     };
 }

package/docs/acceptance.md

@@ -2457,6 +2457,178 @@ 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
+candidate `169f00c`, 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 and the roadmap.
+
+The minor release ships ADR 0012 (#157) with #151 and #154. It changes the MCP
+contract as the changelog lists; the setup report keeps `schemaVersion` `1`.
+
+- 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, 3693 passed and 14 skipped, and no unhandled error.
+  - `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
+    `764e22c8373934ce339cfd76ea1e56b96006a34d`); nothing under
+    `docs/superpowers/` is packed, and a scan of the packed files for private
+    names, hosts and paths found none.
+  - Doctor reported `packageVersion` `0.12.0`. 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.0`.
+- In every Level 2 run the real client registrations and the built files were
+  unchanged, no process remained, and the leak check passed.
+- Review: every task of #157 had a cross-family read-only review before it was
+  integrated; the findings were fixed in #158.
+
+Level 2 runs no container writer. The Podman-gated tests in
+`test/writer-lifecycle.podman.test.ts` ran on the candidate with rootless
+Podman and the local Node image, separately from the suite: 4 of 4 passed,
+including the lease descriptor check, the finite-input probe and the release of
+a writer after its relay parent was killed.
+
+Not established for `0.12.0`: the migration of an installed release's container
+repositories, a relayed coding session through the one host registration, the
+live checks of #151 and #154, which follow the release; Level 3. No
+post-release evidence was recorded for `0.11.9`, a documentation-only release,
+beyond its release notes.
+
 ### v0.11.8 post-release evidence
 
 The published-release acceptance of `v0.11.8` ran on 2026-10-26 from 22:40 to