pi-session-mcp 0.11.9 → 0.12.0

package/.pi-session-mcp-cli/writer-lifecycle.js

@@ -1,13 +1,19 @@
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, mkdir, open, readdir, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { configSchema } from "./config.js";
 import { renderWrapper } from "./writer-wrapper.js";
 import { builtinSkillName } from "./skill-catalog.js";
 import { resolveLibrarySkill, shippedLibrarySkill } from "./skill-library.js";
 import { BOUNDARY_GIT, BoundaryError, IMAGE_PULL_TIMEOUT_MS, isSafeRefName, podmanInfo, resolveImage, throwawayArgs, verifyCloneLayout } from "./writer-boundary.js";
 import { readWriterState, writerName, writerPaths, writeWriterState, WriterStateError } from "./writer-state.js";
+function leasedContext(ctx) {
+    if (ctx.leaseFd === undefined)
+        return ctx;
+    const runner = ctx.runner;
+    return { ...ctx, runner: { run: (command, args, signal, options) => runner.run(command, args, signal, { ...options, inheritFds: [ctx.leaseFd] }) } };
+}
 class LifecycleError extends Error {
     code;
     constructor(code) {
@@ -100,13 +106,23 @@ function buildContainedConfig(alias, clonePath, rawConfig, selected, availableBu
 }
 // CommandRunner has no per-call environment option. Hooks are disabled even for injected runners.
 async function git(ctx, args, optional = false) {
+    ctx = leasedContext(ctx);
     const result = await ctx.runner.run("git", ["-c", "core.hooksPath=/dev/null", "-C", ctx.checkout, ...args], AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
     if (result.exitCode !== 0) {
         if (optional)
             return undefined;
         throw new LifecycleError("writer_base_unavailable");
     }
-    return result.stdout.trim();
+    return args[0] === "config" ? result.stdout.replace(/\n$/, "") : result.stdout.trim();
+}
+async function operatorIdentity(ctx) {
+    const name = await git(ctx, ["config", "--get", "user.name"], true);
+    const email = await git(ctx, ["config", "--get", "user.email"], true);
+    const valid = (value) => value !== undefined && value.length >= 1 && value.length <= 256 && !value.startsWith("-") && !/[\p{Cc}]/u.test(value);
+    return valid(name) && valid(email) ? [name, email] : ["", ""];
+}
+function identityScript(name, email) {
+    return `if [ -n "$${name}" ] && [ -n "$${email}" ]; then\n${BOUNDARY_GIT} config user.name "$${name}"\n${BOUNDARY_GIT} config user.email "$${email}"\nelse\n${BOUNDARY_GIT} config --unset-all user.name || :\n${BOUNDARY_GIT} config --unset-all user.email || :\nfi`;
 }
 async function collectGit(ctx, args) {
     try {
@@ -143,15 +159,21 @@ async function resolveBase(ctx, requested) {
         throw new LifecycleError("writer_base_unavailable");
     return { ref, short, commit };
 }
-async function baseBundle(ctx, paths, ref) {
+/** The short branch name provisioning would record for `requested` (or its default base), normalized like the writer state. */
+export async function baseBranchName(ctx, requested) {
+    return (await resolveBase(ctx, requested)).short;
+}
+async function baseBundle(ctx, paths, ref, commit, tags) {
+    // for-each-ref prints one full ref per line; `git tag` honours column.ui/column.tag and can print several per line.
+    const reachable = tags === "reachable" ? (await git(ctx, ["for-each-ref", "--format=%(refname)", "--merged", commit, "refs/tags"]))?.split("\n").filter((ref) => ref.startsWith("refs/tags/")) ?? [] : [];
     await rm(join(paths.bundles, "base.bundle"), { force: true });
-    await git(ctx, ["bundle", "create", join(paths.bundles, "base.bundle"), ref]);
+    await git(ctx, ["bundle", "create", join(paths.bundles, "base.bundle"), ref, ...reachable]);
     await chmod(join(paths.bundles, "base.bundle"), 0o600);
 }
-async function cloneFromBundle(ctx, paths, imageId, base, remote) {
+async function cloneFromBundle(ctx, paths, imageId, base, remote, tags) {
     // Clone only auto-fetches refs/heads; fetch the exact bundled ref before checkout.
-    const script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\n${BOUNDARY_GIT} clone --no-hardlinks /bundles/base.bundle "$1"\ncd "$1"\n${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle "$5"\n${BOUNDARY_GIT} checkout -B "$2" "$3"\nif [ -n "$4" ]; then ${BOUNDARY_GIT} remote set-url origin "$4"; else ${BOUNDARY_GIT} remote remove origin; fi`;
-    const clone = await ctx.runner.run("podman", throwawayArgs(paths, imageId, { clone: "rw", bundles: true }, script, [paths.clone, base.short, base.commit, remote ?? "", base.ref]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    const script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\n${BOUNDARY_GIT} clone --no-hardlinks /bundles/base.bundle "$1"\ncd "$1"\n${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle "$5"\n${BOUNDARY_GIT} checkout -B "$2" "$3"\nif [ -n "$4" ]; then ${BOUNDARY_GIT} remote set-url origin "$4"; else ${BOUNDARY_GIT} remote remove origin; fi\n${identityScript(6, 7)}\n${tags === "reachable" ? `${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle '+refs/tags/*:refs/tags/*'` : ""}`;
+    const clone = await ctx.runner.run("podman", throwawayArgs(basename(paths.root), paths, imageId, { clone: "rw", bundles: true }, script, [paths.clone, base.short, base.commit, remote ?? "", base.ref, ...await operatorIdentity(ctx)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
     if (clone.exitCode !== 0)
         throw new LifecycleError("writer_clone_failed");
     await verifyCloneLayout(paths.clone);
@@ -198,7 +220,7 @@ async function storedConfig(paths) {
 async function sameSettings(paths, existing, settings, now) {
     const stored = await storedConfig(paths);
     return stored !== undefined && existing.imageId === now.imageId && existing.lifecycle === settings.lifecycle
-        && existing.network === settings.network && existing.cache === settings.cache
+        && existing.network === settings.network && existing.cache === settings.cache && existing.tags === settings.tags
         && JSON.stringify(existing.profiles) === JSON.stringify(settings.profiles)
         && JSON.stringify(existing.providers) === JSON.stringify(now.providers) && canonical(withoutDeliveryOff(stored)) === canonical(withoutDeliveryOff(now.config));
 }
@@ -217,6 +239,7 @@ function withoutDeliveryOff(config) {
  * answers but cannot resolve the image.
  */
 export async function writerSettingsDrift(ctx, input) {
+    ctx = leasedContext(ctx);
     try {
         const name = writerName(ctx.alias, input.index), paths = writerPaths(ctx.home, name);
         const existing = await readWriterState(ctx.home, name);
@@ -233,6 +256,7 @@ export async function writerSettingsDrift(ctx, input) {
     }
 }
 export async function provisionWriter(ctx, input) {
+    ctx = leasedContext(ctx);
     try {
         const { index, settings } = input;
         const name = writerName(ctx.alias, index), paths = writerPaths(ctx.home, name);
@@ -271,16 +295,17 @@ export async function provisionWriter(ctx, input) {
         // With spool delivery the spool directory exists from provisioning on: launch would otherwise add it to the
         // writer root, a host directory the acceptance harness digests around its own first launch.
         const spool = config.events?.delivery === "spool" ? [paths.events] : [];
-        for (const path of [paths.root, paths.clone, paths.config, paths.agent, paths.bundles, ...spool, ...(settings.cache === "go" ? [paths.go] : [])])
+        const cache = settings.cache === "go" ? [paths.go] : settings.cache === "uv" ? [paths.uv] : [];
+        for (const path of [paths.root, paths.clone, paths.config, paths.agent, paths.bundles, ...spool, ...cache])
             await privateDirectory(path);
         const state = {
             schemaVersion: 1, alias: ctx.alias, index, phase: "provisioning", lifecycle: settings.lifecycle,
-            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, imageId,
+            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, tags: settings.tags, imageId,
             base: { ref: `refs/heads/${short}`, commit },
         };
         await writeWriterState(ctx.home, name, state);
-        await baseBundle(ctx, paths, ref);
-        await cloneFromBundle(ctx, paths, imageId, base, remote);
+        await baseBundle(ctx, paths, ref, commit, settings.tags);
+        await cloneFromBundle(ctx, paths, imageId, base, remote, settings.tags);
         await jsonFile(join(paths.config, "pi-session-mcp.json"), config);
         await jsonFile(join(paths.config, "execution-modes.json"), { schemaVersion: 1, workspaces: { [ctx.alias]: { mode: "host", acceptHostWrites: true } } });
         await jsonFile(join(paths.config, "writer-guard.json"), { schemaVersion: 1, workspace: ctx.alias, baseRef: state.base.ref, baseCommit: commit });
@@ -294,13 +319,14 @@ export async function provisionWriter(ctx, input) {
     }
 }
 export async function inspectWork(ctx, name) {
+    ctx = leasedContext(ctx);
     const state = await readWriterState(ctx.home, name);
     if (!state || state.alias !== ctx.alias)
         throw new LifecycleError("writer_state_invalid");
     const paths = writerPaths(ctx.home, name);
     await verifyCloneLayout(paths.clone);
     const script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\ncp .git/index /tmp/index\nmkdir /tmp/objects\nexport GIT_INDEX_FILE=/tmp/index GIT_OBJECT_DIRECTORY=/tmp/objects GIT_ALTERNATE_OBJECT_DIRECTORIES="$1/.git/objects"\n${BOUNDARY_GIT} add -A\n${BOUNDARY_GIT} rev-parse --verify HEAD\n${BOUNDARY_GIT} for-each-ref --format='%(refname) %(objectname)' refs/heads refs/stash\n${BOUNDARY_GIT} write-tree\n${BOUNDARY_GIT} rev-parse 'HEAD^{tree}'\n${BOUNDARY_GIT} rev-parse "$2^{tree}"`;
-    const result = await ctx.runner.run("podman", throwawayArgs(paths, state.imageId, { clone: "ro", bundles: false }, script, [paths.clone, state.base.commit]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "ro", bundles: false }, script, [paths.clone, state.base.commit]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
     if (result.exitCode !== 0)
         throw new LifecycleError("writer_inspect_failed");
     const lines = result.stdout.trim().split("\n");
@@ -332,7 +358,7 @@ async function writerBase(ctx, name, state, requested) {
     // State normalizes remote branches to local heads. The original source ref remains
     // in the single-ref base bundle, including when no corresponding host head exists.
     const heads = await git(ctx, ["bundle", "list-heads", join(writerPaths(ctx.home, name).bundles, "base.bundle")], true);
-    const match = /^(?:[0-9a-f]{40}|[0-9a-f]{64}) (refs\/(?:heads\/.+|remotes\/[^/]+\/.+))$/.exec(heads ?? "");
+    const match = /^(?:[0-9a-f]{40}|[0-9a-f]{64}) (refs\/(?:heads\/.+|remotes\/[^/]+\/.+))$/m.exec(heads ?? "");
     const source = match?.[1];
     if (source && isSafeRefName(source) && shortBranch(source) === shortBranch(state.base.ref))
         return resolveBase(ctx, source);
@@ -353,6 +379,7 @@ async function refreshPrivateFiles(ctx, name, state) {
     await jsonFile(join(paths.agent, "auth.json"), {});
 }
 export async function collectWriter(ctx, name) {
+    ctx = leasedContext(ctx);
     const refs = [], findings = [];
     try {
         const paths = writerPaths(ctx.home, name);
@@ -394,7 +421,7 @@ if [ -z "$(${BOUNDARY_GIT} --git-dir=/tmp/scratch for-each-ref --format='%(refna
 else
   ${BOUNDARY_GIT} --git-dir=/tmp/scratch bundle create /bundles/collect.bundle --all
 fi`;
-            const result = await ctx.runner.run("podman", throwawayArgs(paths, state.imageId, { clone: "ro", bundles: true }, script, [paths.clone, state.base.ref, state.base.commit, shortBranch(state.base.ref)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+            const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "ro", bundles: true }, script, [paths.clone, state.base.ref, state.base.commit, shortBranch(state.base.ref)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
             if (result.exitCode !== 0)
                 throw new LifecycleError("writer_collect_failed");
             const messages = result.stdout.split("\n");
@@ -437,7 +464,7 @@ async function recreate(ctx, name, state, base) {
     const remote = await git(ctx, ["remote", "get-url", "origin"], true);
     if (remote && /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/]*@/.test(remote))
         throw new LifecycleError("remote_url_refused");
-    await baseBundle(ctx, paths, base.ref);
+    await baseBundle(ctx, paths, base.ref, base.commit, state.tags);
     const { collected: _collected, ...retained } = state;
     const next = { ...retained, base: { ref: `refs/heads/${base.short}`, commit: base.commit } };
     await writeWriterState(ctx.home, name, { ...next, phase: "provisioning" });
@@ -445,7 +472,7 @@ async function recreate(ctx, name, state, base) {
         await rm(path, { recursive: true, force: true });
         await privateDirectory(path);
     }
-    await cloneFromBundle(ctx, paths, state.imageId, base, remote);
+    await cloneFromBundle(ctx, paths, state.imageId, base, remote, state.tags);
     await refreshPrivateFiles(ctx, name, next);
     await writeWriterState(ctx.home, name, next);
     if (!(await inspectWork(ctx, name)).baseline)
@@ -453,26 +480,30 @@ async function recreate(ctx, name, state, base) {
     return { status: "ok", code: "writer_recreated" };
 }
 export async function recreateWriter(ctx, name, opts) {
+    ctx = leasedContext(ctx);
     try {
         const state = await requiredState(ctx, name);
         await requireCollected(ctx, name, state, opts.discard);
-        return await recreate(ctx, name, state, await writerBase(ctx, name, state));
+        return await recreate(ctx, name, state, await writerBase(ctx, name, state, opts.baseRef));
     }
     catch (error) {
         return failure(error);
     }
 }
 export async function resetWriter(ctx, name, opts) {
+    ctx = leasedContext(ctx);
     try {
         const state = await requiredState(ctx, name);
         const base = await writerBase(ctx, name, state, opts.baseRef);
         await requireCollected(ctx, name, state, opts.discard);
         const paths = writerPaths(ctx.home, name);
         await verifyCloneLayout(paths.clone);
-        await baseBundle(ctx, paths, base.ref);
+        await baseBundle(ctx, paths, base.ref, base.commit, state.tags);
         const script = `set -eu
 export GIT_CONFIG_NOSYSTEM=1
 ${BOUNDARY_GIT} checkout -f --detach
+${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/tags | while read -r ref; do ${BOUNDARY_GIT} update-ref -d "$ref"; done
+${state.tags === "reachable" ? `${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle '+refs/tags/*:refs/tags/*'` : ""}
 ${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle "+$1:$1"
 ${BOUNDARY_GIT} checkout -f -B "$2" "$3"
 ${BOUNDARY_GIT} reset --hard "$3"
@@ -480,8 +511,9 @@ ${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/heads | while read -r re
   if [ "$ref" != "refs/heads/$2" ]; then ${BOUNDARY_GIT} update-ref -d "$ref"; fi
 done
 ${BOUNDARY_GIT} stash clear
-${BOUNDARY_GIT} clean -fd`;
-        const result = await ctx.runner.run("podman", throwawayArgs(paths, state.imageId, { clone: "rw", bundles: true }, script, [base.ref, base.short, base.commit]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+${BOUNDARY_GIT} clean -fd
+${identityScript(4, 5)}`;
+        const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "rw", bundles: true }, script, [base.ref, base.short, base.commit, ...await operatorIdentity(ctx)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
         if (result.exitCode !== 0)
             throw new LifecycleError("writer_reset_failed");
         const next = { ...state, base: { ref: `refs/heads/${base.short}`, commit: base.commit } };
@@ -503,13 +535,13 @@ ${BOUNDARY_GIT} clean -fd`;
         return failure(error);
     }
 }
-export async function finishWriter(ctx, name) {
+export async function finishWriter(ctx, name, opts = {}) {
     try {
         const state = await requiredState(ctx, name);
         const collected = await collectWriter(ctx, name);
         if (collected.status === "failed")
             return collected;
-        return state.lifecycle === "ephemeral" ? await recreateWriter(ctx, name, { discard: false }) : await resetWriter(ctx, name, { discard: false });
+        return state.lifecycle === "ephemeral" ? await recreateWriter(ctx, name, { discard: false, ...opts }) : await resetWriter(ctx, name, { discard: false, ...opts });
     }
     catch (error) {
         return failure(error);

package/.pi-session-mcp-cli/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/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## Unreleased
 
+## 0.12.0 — 2026-10-28
+
+Minor release under ADR 0003 for
+[ADR 0012](docs/adr/0012-leased-writer-pool.md)
+([#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157)): one host
+registration codes in container workspaces through a leased writer pool. The
+MCP contract changes: `pi_session_start` gains an optional `base`, sessions and
+capabilities gain writer fields, and there are new error codes. It also ships
+the writer cache and identity changes of
+[#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151) and
+[#154](https://github.com/plagor44-ux/pi-session-mcp/issues/154). `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)).
+
+Upgrading needs a one-time migration of every container repository; follow
+[Installation](docs/installation.md#upgrade). Writers must be accepted again
+after the upgrade, as after every release.
+
+- Changed: coding on a `container` workspace goes through the one host
+  registration `pi-session-mcp`. The host leases a ready, accepted writer at
+  the requested or default base and relays the session to the writer's
+  contained server over stdio. Setup no longer adds `pi-coding-<alias>-w<n>`
+  registrations or writer hook entries, and `--client codex` has no writer
+  effect any more. Relayed start has a 60-second budget, prompt preflight and
+  abort 15 seconds each, and close cleanup 10 seconds; inner replies are
+  validated and size-bounded.
+- Changed: every writer operation, from launch to setup's collect, finish,
+  reset and recreate, runs under a per-writer host lease
+  (`~/.local/state/pi-session-mcp/leases/<name>.lock`) and a container fence
+  (container name, label and clone mount). A held lease fails with
+  `writer_busy`; setup waits up to 10 seconds for it. A container that cannot be
+  removed fails with `writer_fenced`. The lease descriptor never enters a
+  container.
+- Changed: reset, finish and recreate no longer need a reconnect of the writer
+  server; setup no longer reports `writer_reconnect_required`.
+- Added: `pi_session_start` accepts an optional `base`, a short branch name,
+  for coding profiles on `container` workspaces; elsewhere it fails with
+  `base_not_applicable`. Container coding sessions carry `writer` and `base`,
+  and `pi_capabilities_get` lists each container workspace's `writers` and
+  `defaultBase`.
+- Added: error codes `writer_unavailable` (with `reason` `none_ready`,
+  `none_at_base` or `none_admitted`, and the counts `busy`, `notAtBaseline`
+  and `settingsChanged`), `writer_session_lost` and `base_not_applicable`.
+- Added: container modes record a default base. Setup records the base that
+  provisioning resolves (`--base`, else `origin/HEAD`, else `main`); migration
+  records the writers' shared base and fails with `workspace_base_ambiguous` if
+  they differ and no `--base` is given. Finish returns a writer to the default
+  base.
+- Added: re-running a repository's provisioning command migrates its writers:
+  it removes the owned writer registrations and hooks, rewrites the wrappers,
+  marks the writers `launch: "relay"` and accepts them again. A divergent
+  registration is never removed; it reports `registration_divergent`, and that
+  writer stays outside the pool.
+- Added: Doctor checks `writer_lease_directory`, `writer_not_migrated`,
+  `workspace_base_unset` and `writer_off_default_base`.
+- Added: `--cache uv` mounts a private per-writer cache at `/pi/uv` with
+  `UV_CACHE_DIR=/pi/uv/cache` and `npm_config_cache=/pi/uv/npm`
+  ([#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151)).
+- Added: writer clones get the operator checkout's commit identity when both
+  values are valid, and Doctor warns with `writer_git_identity_missing`
+  otherwise. `--tags reachable` bundles the tags reachable from the base
+  commit; the default stays `none`
+  ([#154](https://github.com/plagor44-ux/pi-session-mcp/issues/154)).
+- Changed: the wake hook matches only `mcp__pi-session-mcp__*` and reads the
+  host spool, which now also carries relayed container turns. Migrated writers
+  get no spool mount; a writer that is not yet migrated keeps it.
+- Limits: lease, fence and relay need Linux. The live migration of an existing
+  installation and a relayed coding turn follow the release.
+
 ## 0.11.9 — 2026-10-27
 
 Documentation-only release. The published `docs/` of 0.9.0 to 0.11.8 contained

package/README.md

@@ -30,9 +30,9 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.11.9**.
+The package version is **0.12.0**.
 
-Since 0.9.0, [per-repository execution modes](docs/execution-modes.md) make host writes explicit and block host coding for container/read-only aliases, and setup provisions, accepts, collects and resets rootless-Podman container writers on Linux.
+[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).
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
@@ -173,6 +173,7 @@ Contract and design:
 - [ADR 0004: setup accepts clients by contract, not by version](docs/adr/0004-client-contract-not-version.md)
 - [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
 - [ADR 0011: turn events and controller wake](docs/adr/0011-turn-events-and-controller-wake.md)
+- [ADR 0012: one registration with a leased writer pool](docs/adr/0012-leased-writer-pool.md)
 
 Maintain:
 

package/dist/capabilities.d.ts

@@ -18,6 +18,8 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
     workspaces: {
         alias: string;
         mode: import("./execution-modes.js").WorkspaceMode;
+        writers?: number;
+        defaultBase?: string | null;
     }[];
     executionProfiles: {
         alias: string;

package/dist/capabilities.js

@@ -12,7 +12,10 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
         events: { delivery: eventDelivery },
         workspaces: [...workspaces.keys()]
             .sort(compareAliases)
-            .map((alias) => ({ alias, mode: workspaceModes.get(alias)?.mode ?? "unset" })),
+            .map((alias) => {
+            const entry = workspaceModes.get(alias);
+            return { alias, mode: entry?.mode ?? "unset", ...(entry?.mode === "container" && entry.container ? { writers: entry.container.writers, defaultBase: entry.container.base ?? null } : {}) };
+        }),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
             .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, skills }) => ({

package/dist/child-stdio-transport.d.ts

@@ -0,0 +1,21 @@
+import { type Transport } from "@modelcontextprotocol/client";
+/** A launcher is a lease guardian: EOF requests cleanup; killing it would break that contract. */
+/** A frame carries a result twice (text content and structured content); 2 MiB covers both at the relay's size bound. */
+export declare class ChildStdioTransport implements Transport {
+    private readonly command;
+    private readonly env;
+    private readonly args;
+    onclose: Transport["onclose"];
+    onerror: Transport["onerror"];
+    onmessage: Transport["onmessage"];
+    private child?;
+    private closed;
+    private started;
+    private readonly buffer;
+    private pending;
+    constructor(command: string, env: Record<string, string>, args?: readonly string[]);
+    start(): Promise<void>;
+    send(message: Parameters<Transport["send"]>[0]): Promise<void>;
+    close(): Promise<void>;
+    private finish;
+}

package/dist/child-stdio-transport.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/client";
+/** A launcher is a lease guardian: EOF requests cleanup; killing it would break that contract. */
+/** A frame carries a result twice (text content and structured content); 2 MiB covers both at the relay's size bound. */
+export class ChildStdioTransport {
+    command;
+    env;
+    args;
+    onclose;
+    onerror;
+    onmessage;
+    child;
+    closed = false;
+    started = false;
+    buffer = new ReadBuffer({ maxBufferSize: 2_097_152 });
+    pending = Buffer.alloc(0);
+    constructor(command, env, args = []) {
+        this.command = command;
+        this.env = env;
+        this.args = args;
+    }
+    async start() {
+        if (this.started || this.closed)
+            throw new Error("Transport cannot start");
+        this.started = true;
+        const child = this.child = spawn(this.command, [...this.args], { detached: true, stdio: ["pipe", "pipe", "pipe"], env: { ...this.env }, shell: false });
+        child.stderr.on("data", () => undefined);
+        child.stdin.on("error", () => this.onerror?.(new Error("Writer input failed")));
+        child.on("error", () => this.onerror?.(new Error("Writer process failed")));
+        child.on("close", () => this.finish());
+        child.stdout.on("data", (chunk) => {
+            if (this.closed)
+                return;
+            try {
+                this.pending = Buffer.concat([this.pending, chunk]);
+                let newline;
+                while ((newline = this.pending.indexOf(10)) !== -1) {
+                    if (newline > 2_097_152)
+                        throw new Error();
+                    const line = this.pending.subarray(0, newline + 1);
+                    this.pending = this.pending.subarray(newline + 1);
+                    // ReadBuffer silently skips JSON syntax errors; detect them before decoding.
+                    JSON.parse(line.toString("utf8"));
+                    this.buffer.append(line);
+                    const message = this.buffer.readMessage();
+                    if (message === null)
+                        throw new Error();
+                    this.onmessage?.(message);
+                }
+                if (this.pending.length > 2_097_152)
+                    throw new Error();
+            }
+            catch {
+                this.onerror?.(new Error("Invalid writer frame"));
+                void this.close();
+            }
+        });
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", () => reject(new Error("Writer spawn failed")));
+        });
+    }
+    async send(message) {
+        if (this.closed || !this.child)
+            throw new Error("Writer transport is closed");
+        await new Promise((resolve, reject) => {
+            this.child.stdin.write(serializeMessage(message), error => error ? reject(new Error("Writer send failed")) : resolve());
+        });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.child?.stdin.end();
+        // Keep draining diagnostics/output while the guardian cleans up, without keeping the host alive.
+        this.child?.unref();
+        this.child?.stdout?.unref?.();
+        this.child?.stderr?.unref?.();
+        this.finish();
+    }
+    finish() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.buffer.clear();
+        this.pending = Buffer.alloc(0);
+        this.onclose?.();
+    }
+}

package/dist/client-adapters/types.d.ts

@@ -11,6 +11,7 @@ export interface CommandRunner {
     run(command: string, args: readonly string[], signal?: AbortSignal, options?: {
         cwd?: string;
         env?: NodeJS.ProcessEnv;
+        inheritFds?: readonly number[];
     }): Promise<CommandResult>;
 }
 export interface CommandExecution {

package/dist/doctor.d.ts

@@ -3,7 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "workspace_gitfile" | "workspace_mode_unset" | "workspace_host_writes_accepted" | "container_runtime_unavailable" | "container_profile_refused" | "writer_not_ready" | "writer_dirty" | "writer_uncollected_bundle" | "extension_missing" | "extension_version_mismatch" | "extension_unpinned" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated" | "event_spool_root";
+export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "workspace_gitfile" | "workspace_mode_unset" | "workspace_base_unset" | "workspace_host_writes_accepted" | "container_runtime_unavailable" | "container_profile_refused" | "writer_lease_directory" | "writer_not_ready" | "writer_not_migrated" | "writer_off_default_base" | "writer_dirty" | "writer_git_identity_missing" | "writer_uncollected_bundle" | "extension_missing" | "extension_version_mismatch" | "extension_unpinned" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated" | "event_spool_root";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -72,6 +72,8 @@ export interface DoctorDependencies {
     readonly env?: NodeJS.ProcessEnv;
     /** Metadata of the spool root without following a final symbolic link, `undefined` when absent; used only when event delivery is enabled. */
     readonly eventSpoolRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
+    /** Metadata of the writer lease directory without following a final symbolic link, `undefined` when absent. */
+    readonly writerLeaseRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
     /** Effective user id of the current process; defaults to the real one. */
     readonly uid?: number;
 }