pi-session-mcp 0.12.1 → 0.13.1

package/dist/writer-lifecycle.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, mkdir, open, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { writerLimits } from "./writer-limits.js";
 import { configSchema } from "./config.js";
 import { renderWrapper } from "./writer-wrapper.js";
 import { builtinSkillName } from "./skill-catalog.js";
@@ -220,7 +221,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.tags === settings.tags
+        && existing.network === settings.network && existing.cache === settings.cache && existing.tags === settings.tags && existing.clean === settings.clean
         && JSON.stringify(existing.profiles) === JSON.stringify(settings.profiles)
         && JSON.stringify(existing.providers) === JSON.stringify(now.providers) && canonical(withoutDeliveryOff(stored)) === canonical(withoutDeliveryOff(now.config));
 }
@@ -295,12 +296,13 @@ 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] : [];
-        const cache = settings.cache === "go" ? [paths.go] : settings.cache === "uv" ? [paths.uv] : [];
+        const cache = settings.cache === "none" ? [] : [paths[settings.cache]];
         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, tags: settings.tags, imageId,
+            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, tags: settings.tags, clean: settings.clean, imageId,
+            ...(writerLimits(settings) ? { limits: writerLimits(settings) } : {}),
             base: { ref: `refs/heads/${short}`, commit },
         };
         await writeWriterState(ctx.home, name, state);
@@ -511,7 +513,7 @@ ${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
+${BOUNDARY_GIT} clean ${state.clean === "all" ? "-ffdx" : "-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)

package/dist/writer-limits.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const cpusSchema: z.ZodNumber;
+export declare const cpuSharesSchema: z.ZodNumber;
+export declare const memorySchema: z.ZodString;
+export declare const writerLimitsSchema: z.ZodObject<{
+    cpus: z.ZodOptional<z.ZodNumber>;
+    cpuShares: z.ZodOptional<z.ZodNumber>;
+    memory: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WriterLimits = z.infer<typeof writerLimitsSchema>;
+/** Omitted settings remove previous limits; never persist an empty limits object. */
+export declare function writerLimits(settings: WriterLimits): WriterLimits | undefined;
+export declare function sameWriterLimits(left: WriterLimits | undefined, right: WriterLimits | undefined): boolean;

package/dist/writer-limits.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const cpusSchema = z.number().positive().max(1024).multipleOf(0.01);
+export const cpuSharesSchema = z.number().int().min(2).max(262144);
+export const memorySchema = z.string().regex(/^[1-9][0-9]{0,6}[mg]$/);
+export const writerLimitsSchema = z.object({
+    cpus: cpusSchema.optional(),
+    cpuShares: cpuSharesSchema.optional(),
+    memory: memorySchema.optional(),
+}).strict();
+/** Omitted settings remove previous limits; never persist an empty limits object. */
+export function writerLimits(settings) {
+    const { cpus, cpuShares, memory } = settings;
+    if (cpus === undefined && cpuShares === undefined && memory === undefined)
+        return undefined;
+    return { ...(cpus === undefined ? {} : { cpus }), ...(cpuShares === undefined ? {} : { cpuShares }), ...(memory === undefined ? {} : { memory }) };
+}
+export function sameWriterLimits(left, right) {
+    return left?.cpus === right?.cpus && left?.cpuShares === right?.cpuShares && left?.memory === right?.memory;
+}

package/dist/writer-relay.js

@@ -69,7 +69,7 @@ const creationCodes = new Set([
     "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",
+    "extension_tool_missing", "skill_load_failed", "sandbox_unavailable", "pi_session_creation_failed",
 ]);
 class InnerError extends Error {
     code;

package/dist/writer-state.d.ts

@@ -33,12 +33,22 @@ export declare const writerStateSchema: z.ZodObject<{
     cache: z.ZodEnum<{
         go: "go";
         none: "none";
+        npm: "npm";
         uv: "uv";
     }>;
     tags: z.ZodDefault<z.ZodEnum<{
         none: "none";
         reachable: "reachable";
     }>>;
+    clean: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        untracked: "untracked";
+    }>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        cpus: z.ZodOptional<z.ZodNumber>;
+        cpuShares: z.ZodOptional<z.ZodNumber>;
+        memory: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     imageId: z.ZodString;
     base: z.ZodObject<{
         ref: z.ZodString;
@@ -73,6 +83,7 @@ export declare function writerPaths(home: string, name: string): {
     events: string;
     go: string;
     uv: string;
+    npm: string;
     wrapper: string;
     state: string;
     acceptanceFailure: string;

package/dist/writer-state.js

@@ -5,6 +5,7 @@ import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { PACKAGE_VERSION } from "./package-metadata.js";
+import { writerLimitsSchema } from "./writer-limits.js";
 import { ALIAS_PATTERN } from "./execution-profile.js";
 export const WRITER_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}-w([1-9]|1[0-6])$/;
 export class WriterStateError extends Error {
@@ -31,8 +32,10 @@ export const writerStateSchema = z.object({
         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", "uv"]),
+    cache: z.enum(["none", "go", "uv", "npm"]),
     tags: z.enum(["none", "reachable"]).default("none"),
+    clean: z.enum(["untracked", "all"]).default("untracked"),
+    limits: writerLimitsSchema.optional(),
     imageId: hex64,
     base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/) }).strict(),
     acceptance: z.object({
@@ -62,7 +65,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"), uv: join(root, "uv"), 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"), npm: join(root, "npm"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
         acceptanceFailure: join(root, "acceptance-failure.json"),
     };
 }

package/docs/acceptance.md

@@ -2457,6 +2457,277 @@ Not established for `0.11.6`:
   wrapper's periodic credential copy (#136);
 - the VS Code wake; macOS delivery.
 
+### v0.13.0 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.13.0`.
+
+Tag binding: a fresh clone of the annotated tag `v0.13.0` (tag object
+`8c2d513ccac17916fdf7cf3fc36b3ccd454138ed`) peels to the merge commit
+`d1c63dac3b996952976aab4b5ad11665e7108fa3` of #171, and
+`git describe --tags --exact-match` reports `v0.13.0`. CI on the merge commit
+(run 40757781881) and on the tag (run 40759098803) passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 21:01 to 21:03 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (125 files, 3936 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.13.0` and exited with `2` because no
+  configuration was set (`config_missing`).
+- `pi-session-mcp@0.13.0` on npm: 916 files, shasum
+  `866d0ecfa3b4e1a71462d291b1776897229f7827`, `gitHead` `4521d39` (the head of
+  #171, whose tree equals the merge commit). `npm pack` of the tag clone gives
+  the same shasum and file count.
+- Published npm package, Level 2 from a fresh prefix, 21:03 to 21:05 UTC:
+  160 of 160 with delivery off and 228 of 228 with `--events spool`; real
+  registrations and built files unchanged, no process left, leak check passed.
+  Clients: Codex CLI `0.162.1` and Claude Code `2.1.312`. The install smoke on
+  the published package reported `smoke_passed` with version `0.13.0`.
+- The GitHub release `v0.13.0` was published the same day.
+
+Operator upgrade of the second machine (Linux) from `0.12.1` to `0.13.0` on
+2026-10-28 from 20:34 UTC, following
+[Installation](installation.md#container-writers), with Node.js `24.22.0`:
+
+- Both client targets were removed with `0.12.1`, then
+  `npm install -g pi-session-mcp@0.13.0`.
+- Four container repositories with 14 writers were migrated by repeating their
+  provisioning commands with unchanged settings and `--apply`: 2, 4, 4
+  (operator image, `--cache go`) and 4 (operator image) writers. Every writer
+  reported `writer_accepted`.
+- `--apply` and `--verify` of both client targets passed (`mcp_verified`), the
+  open point of the pre-release record, and `--writer <name> --verify` passed
+  for all 14 writers. Doctor reported no error.
+
+Operator upgrade of the workstation from `0.12.1` to `0.13.0` on 2026-10-28
+from 20:47 UTC, with the same steps: no writer container ran at the start;
+five container repositories with 18 writers (2, 4, 4 with `--cache go`, 4 with
+base `dev`, 4 with `--cache uv`, three of them with operator images) reported
+`writer_accepted`; client-target `--apply` and `--verify` passed for
+`claude-code:user` and `codex:user` (`mcp_verified`, `skill_verified`, and
+`hook_verified` for the wake hook); `--writer <name> --verify` passed for all
+18 writers. Doctor reported no error.
+
+Live check of `shell: "sandboxed"` on both machines, the open point of the
+pre-release record. Two read-only profiles were added to each configuration,
+copies of the existing review profiles with `"shell": "sandboxed"`, one per
+provider family. Doctor reported `sandbox_unavailable` and
+`workspace_git_unavailable` as `ok`. A stdio driver against the installed
+server started one session per profile on the pi-session-mcp workspace (a plain
+checkout, not a linked worktree) and sent one prompt with five steps. All four
+sessions completed with the same results:
+
+- `git log -1 --format=%h` through `bash` printed the checkout's head commit.
+- `touch sandbox-probe.txt && ls sandbox-probe.txt` succeeded in the sandbox;
+  afterwards the file did not exist on the host and `git status` of the host
+  checkout was clean.
+- `getent hosts example.com || echo NO_NETWORK` printed `NO_NETWORK`.
+- `echo HOME=$HOME` printed `HOME=/tmp/home`.
+- `read` of `/etc/hostname` returned `Path is outside the allowed read roots`.
+
+Finding from these checks: the first workstation edit left out the required
+profile field `default`. Doctor then reported only `config_invalid` with the
+generic remediation and did not name the profile or the field; parsing the file
+with the package's configuration schema named both. With `"default": false`
+added, Doctor reported no error.
+
+Not established for `0.13.0`: the sandbox on a host that restricts unprivileged
+user namespaces; Git inside the sandbox on a linked worktree in live use (the
+bubblewrap-gated tests cover it); the macOS upgrade; Level 3.
+
+### v0.13.1 pre-release acceptance
+
+`v0.13.1` was accepted on 2026-10-29 from 06:40 to 06:48 UTC on its release
+candidate `89a366e`, 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`. After the candidate, one lockfile-only
+commit moved the development-path `@hono/node-server` 2.1.1 → 2.1.5; Level 1
+was run again on it after `npm ci` (same counts). The packed package and the
+working-tree build that Level 2 used do not contain that package. Later commits
+on the release pull request change only this record.
+
+The patch release ships #173, #176, #177, #179 and #180 under an unchanged MCP
+contract. The setup report schema is unchanged; a broken kept writer now
+reports its own code on its target instead of `writer_reconcile_failed`.
+
+- 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
+    136 files, 3948 passed and 14 skipped, and no unhandled error.
+  - `npm audit --omit=dev` exited with `1` and names only the known `undici`
+    finding through `@earendil-works/pi-coding-agent` 1.4.0, now with eight
+    advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+    `npm audit` also named `@hono/node-server` 2.1.1 in the development path
+    (GHSA-rmxm-3fg6-px4f), patched in the lockfile afterwards as above.
+  - `npm pack` listed 922 files (tarball shasum
+    `93f9c5bc9e268af7e0be5e395d97558ec801668a`, identical in two packs). A scan
+    of the packed files for private names, hosts and paths found none; its only
+    matches for `/home/` are the already redacted paths in this file and in the
+    six `docs/evaluation/extension-functions-2026-10-17/cursor/` evidence files
+    that earlier releases shipped unchanged.
+  - Doctor reported `packageVersion` `0.13.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 from another fresh prefix
+  reported `smoke_passed` with version `0.13.1`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained, the leak check passed and the disposable directories were removed.
+- Podman-gated writer tests on the candidate (Podman `6.1.4`): 7 of 7 passed.
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+- Review: #179, #180 and #181 had an independent review (same model family as
+  the author) with no blocking findings; its follow-ups were fixed before the
+  merge of #184. The final test-file split commit was checked by comparing the
+  sorted test names before and after (464, identical).
+
+Not established for `0.13.1`: a live wake-hook race, a live reconcile with a
+broken writer, client-target `--verify` through the installed package, which
+follows the upgrade; Level 3.
+
+### v0.13.0 pre-release acceptance
+
+`v0.13.0` was accepted on 2026-10-28 from 19:30 to 19:36 UTC on its release
+candidate `f7442b3`, 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 minor release ships ADR 0013 (#169) and the writer settings changes #162,
+#163, #165 and #166. It changes the MCP contract (read-only confinement,
+profile field and capabilities field `shell`, start error
+`sandbox_unavailable`); the setup report schema is unchanged.
+
+- 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
+    125 files, 3936 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name 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 916 files (tarball shasum
+    `1259d57d2d59099ad72e796609ecab3d581e9b06`, identical in two packs). A scan
+    of the packed files for private names, hosts and paths found none; its only
+    matches for `/home/` are the already redacted
+    `<repo>/eval/results/.../home/.pi/...` paths of disposable evaluation homes
+    in six `docs/evaluation/extension-functions-2026-10-17/cursor/` evidence
+    files, which `0.12.1` shipped unchanged.
+  - Doctor reported `packageVersion` `0.13.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 from another fresh prefix
+  reported `smoke_passed` with version `0.13.0`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained, the leak check passed and the disposable directories were removed.
+- Podman-gated writer tests on the candidate: 7 of 7 passed.
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+- Review: #169 had an independent review of its full diff (same model family as
+  the author) that found no confinement or sandbox escape; its follow-ups were
+  fixed before the merge of #170.
+
+Not established for `0.13.0`: a live session with `shell: "sandboxed"` against
+a real provider, client-target `--verify` through the installed package, which
+follows the upgrade; Level 3.
+
+### v0.12.1 post-release evidence
+
+Recorded on 2026-10-28 for the published release `0.12.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.12.1` (tag object
+`eecd6dbf0c220ded997c697f281f6b984d9ebf4e`) peels to the merge commit
+`91799f2e84b514110f77c24986d59e72c5ed98e5` of #161, and
+`git describe --tags --exact-match` reports `v0.12.1`. CI on the merge commit
+and on the tag passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 14:43 to 14:47 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (120 files, 3708 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean.
+- `pi-session-mcp@0.12.1` on npm: 907 files, shasum
+  `58dc7235e0d54d4290d92934d877223e22eec03d`, `gitHead` `cc25693` (the head of
+  #161, whose tree equals the merge commit). `npm pack` of the tag clone gives
+  the same shasum and file count.
+- Published npm package, Level 2 from a fresh prefix: 160 of 160 with delivery
+  off and 228 of 228 with `--events spool`; real registrations and built files
+  unchanged, no process left, leak check passed. Clients: Codex CLI `0.162.1`
+  and Claude Code `2.1.312`. The install smoke on the published package
+  reported `smoke_passed` with version `0.12.1`.
+- The GitHub release `v0.12.1` was published the same day.
+
+Workstation, upgraded from `0.12.0` to `0.12.1` by the release session: Doctor
+reported no error, client-target `--verify` passed for `claude-code:user` and
+`codex:user` (`mcp_verified`, `skill_verified`, and `hook_verified` for the
+wake hook), the open point of the pre-release record, and
+`--writer <name> --verify` passed for all 18 writers (`mcp_verified`).
+
+Operator upgrade of the second machine (Linux) from `0.11.8` to `0.12.1` on
+2026-10-28 from 14:50 UTC, following
+[Installation](installation.md#container-writers), with Node.js `24.22.0`:
+
+- No pi-session-mcp server process and no writer container ran at the start.
+- Both client targets were removed with `0.11.8`, then
+  `npm install -g pi-session-mcp@0.12.1`. Doctor reported every writer
+  `writer_not_ready`, each container workspace `workspace_base_unset` and each
+  writer `writer_git_identity_missing`.
+- Four container repositories with 14 writers were migrated by repeating their
+  provisioning commands with unchanged settings, each first as a dry run
+  (`planned`), then with `--apply`: 2, 4, 4 (operator image, `--cache go`) and
+  4 (operator image) writers. Every writer reported `writer_accepted`.
+- `--finish --apply` of all 14 writers reported `writer_reset`; no work was
+  collected. Doctor then reported no writer or base finding.
+- `--apply` and `--verify` of both client targets passed (`mcp_verified`), and
+  `--writer <name> --verify` passed for all 14 writers. No writer registration
+  and no container remained.
+
+Live checks of #154 and #151 on the workstation, 15:02 to 15:04 UTC, with the
+coding profile `code-deepseek` through the one host registration and wake
+events from the host spool:
+
+- Settings change: a writer whose settings differ is refused with
+  `writer_settings_changed`. Both repositories' writers were collected
+  (`nothing_to_collect`), removed with `--writer <name> --remove` and
+  provisioned again with `--tags reachable` (2 writers) and `--cache uv`
+  (4 writers, operator image with uv `0.13.6`); every writer reported
+  `writer_accepted`.
+- Tags (#154): the writer with `--tags reachable` held 14 tags, the tags of
+  the operator checkout merged into `main`. In the session,
+  `git describe --tags` reported `v0.12.1` and
+  `git show v0.12.0:package.json` read the file at that tag. The writer without
+  the setting held no tags.
+- Identity (#154): an empty commit in the session, without `GIT_AUTHOR_*` or
+  `GIT_COMMITTER_*` and without `--author`, recorded the operator's name as
+  author and committer. `git config user.name` inside the writer failed with
+  exit `4` because `.git/config` is mounted read-only. The collected ref showed
+  the same identity. The test ref was removed afterwards.
+- uv cache (#151): three sessions on the same writer, with `--finish --apply`
+  between the second and the third. In the first, `UV_CACHE_DIR` was
+  `/pi/uv/cache` and empty; `uv sync --frozen` took 1.9 s and left 95,576 KiB
+  in 1,648 files. The second and third sessions found the same size and file
+  count before they ran anything, and `uv sync --frozen --offline` after
+  removing `.venv` took 0.07 s and 0.08 s.
+
+Findings from these checks:
+
+- Reset and finish keep Git-ignored files in the clone, as designed: `.venv`
+  from the first session was still present in the third, after the finish.
+  The opt-in `--clean all` removes them
+  ([#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162)); it is
+  not part of the released `0.12.1`.
+- A provisioning command with changed settings reported `mode_applied` and
+  recorded the new mode although every writer failed with
+  `writer_settings_changed`; Doctor reported no mismatch
+  ([#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163), open).
+
+Not established for `0.12.1`: a busy pool (`writer_unavailable`) and a `base`
+fix round in live use; Level 3; the macOS upgrade.
+
 ### 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

package/docs/adr/0009-execution-modes.md

@@ -105,8 +105,9 @@ This decision does not itself bump the package version or authorize publication.
    it passes, then require contained provider-free acceptance bound to wrapper,
    package version, image ID, Podman version, network and cache.
 6. **Credential lifetime.** Launcher checks every 60 seconds. Only selected
-   OAuth tokens expired or within 2 minutes of expiry trigger host login
-   warmup (invalid/missing expiry also triggers it); measured warmup refreshes
+   OAuth tokens expired or within 2 minutes of expiry (raised to 10 minutes
+   in [#142](https://github.com/plagor44-ux/pi-session-mcp/issues/142), see
+   [Execution modes](../execution-modes.md)) trigger host login warmup (invalid/missing expiry also triggers it); measured warmup refreshes
    expired/almost expired tokens only. It then re-copies credentials, with
    OAuth refresh tokens emptied. Direct verify disables refresh with
    `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, makes no session/provider request and

package/docs/adr/0012-leased-writer-pool.md

@@ -1,8 +1,8 @@
 # ADR 0012: One registration with a leased writer pool
 
-**Status:** Accepted (2026-10-28, maintainer decision) for release 0.12.0;
-implementation tracked in
-[#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157). Amends
+**Status:** Accepted (2026-10-28, maintainer decision); implemented in
+[#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157) and released
+in 0.12.0. Amends
 [ADR 0002](0002-embedded-pi-sdk.md) (container sessions are relayed to a Pi
 session in a writer process; host sessions stay embedded),
 [ADR 0008](0008-coding-profile-isolation.md) (adopts its option 4 in container

package/docs/adr/0013-hardened-read-only-profiles.md

@@ -0,0 +1,184 @@
+# ADR 0013: Hardened read-only profiles
+
+**Status:** Accepted (2026-10-28); released in 0.13.0. Amends
+[ADR 0006](0006-pi-extension-allowlist.md) and
+[ADR 0010](0010-read-only-extension-tools.md). Issue #169.
+
+## Context
+
+Read-only profiles have `read`, `grep`, `find` and `ls` and no shell. Review
+workers cannot run `git log`, `git blame`, a test file or a short script, and
+read more files instead.
+
+Read-only sessions run in the host server process. The SDK's read tools accept
+absolute paths, `..`, `~` and symlinks, so a read-only worker can read every
+file the operator can read, including Pi credentials outside the workspace.
+Today only the absence of a network path keeps that content local. A granted
+research tool with free-form input (search, documentation lookup) would give a
+prompt-injected worker a channel to send it out.
+
+## Decision
+
+### 1. Workspace-confined read tools for every read-only profile
+
+`read`, `grep`, `find` and `ls` of **every** read-only profile accept only
+paths inside the allowed read roots:
+
+- the session's workspace root, and
+- the directory of each selected skill file, because the model loads skills
+  with `read` and they live outside the workspace. If that directory equals or
+  contains the operator's home directory, the configuration file's directory
+  (and, for a symlinked configuration file, its target's directory), `~/.pi`
+  or Pi's agent directory (`~/.pi/agent`, or `PI_CODING_AGENT_DIR`), only the
+  skill file itself is a root, so a catalog entry such as `./SKILL.md` next to
+  the configuration or Pi's credentials does not expose them. The real file of
+  a symlinked skill file is a root as well, so the model can read it.
+
+The server replaces the SDK's built-in definitions with definitions built from
+the root exports `createReadToolDefinition`, `createGrepToolDefinition`,
+`createFindToolDefinition` and `createLsToolDefinition`, registered under the
+same names as SDK custom tools. Two layers check each call:
+
+1. Before the SDK tool runs, the `path` argument is resolved against the
+   session directory and canonicalized with `realpath` (for a path that does
+   not exist yet, the nearest existing ancestor plus the remaining segments).
+   It must equal an allowed root or lie below one. Arguments the SDK would
+   rewrite before resolving (a leading `@` or `~`, a `file:` URL, Unicode
+   spaces, NUL) are refused, so this check and the SDK always resolve the
+   same path.
+2. The `*Operations` hooks of `read`, `grep` and `ls` check the absolute path
+   the SDK hands them again. This also covers `read`'s file-name variants and
+   symlinks met during reading.
+
+`grep` and `find` start `rg` and `fd` on the checked path. Neither follows
+symlinks during traversal by default, so a symlink below the workspace does not
+lead out of it. A refusal is an ordinary tool error,
+`Path is outside the allowed read roots`, without the path.
+
+At admission the server checks with `getToolDefinition` that each of these
+names resolves to the server's own definition; otherwise the start fails with
+`pi_session_creation_failed`.
+
+The confinement is always on; there is no configuration field. Reading outside
+the workspace has no review use, and a per-profile switch would invite the
+unconfined variant for exactly the profiles that get external tools.
+
+### 2. Sandboxed shell, opt-in per profile
+
+The optional profile field `shell` takes the single value `"sandboxed"`. It is
+allowed only on `read-only` profiles, not together with
+`grantedExtensionTools` (granted extension tools may write, so the shell's
+read-only guarantee would not hold), and only on Linux; any other combination
+fails config validation with `invalid_execution_profile_config`.
+
+Such a profile also gets `bash`, built with `createBashToolDefinition(cwd,
+{ operations, exposeSessionEnvironment: false })` and a custom
+`BashOperations.exec`. Each command runs as
+`/usr/bin/bwrap <fixed arguments> -- /usr/bin/bash -c <command>`:
+
+- `--unshare-all` (no network), `--unshare-user` (which bubblewrap requires
+  for `--disable-userns`), `--disable-userns`, `--die-with-parent`,
+  `--new-session`, `--clearenv` with
+  `PATH=/usr/local/bin:/usr/bin:/bin` and `HOME=/tmp/home`;
+- `/usr` and `/etc` read-only; `/bin`, `/lib`, `/lib64` and `/sbin` recreated
+  as the host's merged-`/usr` symlinks or bound read-only; `--dev /dev`,
+  `--proc /proc`, a tmpfs `/tmp` limited to 512 MiB; no other host path, so the operator's home
+  is not visible;
+- the workspace at its host path as an overlay with a temporary upper layer
+  (`--overlay-src <workspace> --tmp-overlay <workspace>`): writes succeed
+  inside the sandbox and vanish when the command ends;
+- for a linked worktree (a `.git` file instead of a directory), the main
+  repository's Git directory as a second temporary overlay at its host path,
+  so `git log` and `git blame` work. The server accepts the pointer only if
+  `gitdir:` names `<common>/worktrees/<name>`, that directory's `gitdir` file
+  points back to the workspace's `.git`, its `commondir` resolves to
+  `<common>`, and `<common>` holds `HEAD`, `objects` and `refs`. Otherwise
+  nothing extra is bound and Git commands fail inside the sandbox. The read
+  tools stay confined to the workspace either way.
+
+A command without a `timeout` argument gets a default of 600 seconds; on
+timeout or abort the server kills bubblewrap, and the PID namespace takes every
+process of the sandbox with it.
+
+The bubblewrap path is fixed and must be a trusted system binary (root-owned,
+not group- or world-writable); there is no `PATH` lookup. The tool's own
+environment, the controller's environment and `PI_*` session variables never
+reach the command.
+
+Fail closed: before a session with `shell: "sandboxed"` starts, the server runs
+`/usr/bin/true` through the same sandbox for the session's workspace, bounded
+and cancelled with the start request. If the binary is untrusted or the probe
+fails, `pi_session_start` fails with the new code `sandbox_unavailable`, class
+`needs_operator`. A command whose sandbox cannot start fails as that command;
+there is never an unsandboxed fallback.
+
+### 3. Research tools
+
+There is no new mechanism. Operators grant them through the existing
+per-profile `mcpServers` with `readOnly: true`. The documentation advises
+query-style tools over free URL fetching. Now that every read-only profile is
+confined, granting research tools to read-only profiles no longer exposes files
+outside the workspace and the skill directories.
+
+### Doctor and capabilities
+
+Doctor stays offline. When any profile has `shell: "sandboxed"`, it probes
+each configured workspace with the session's fixed arguments, including a
+linked worktree's main Git directory, and reports `sandbox_unavailable` as an
+error when the trusted bubblewrap binary is missing or a probe fails, for
+example because the installed version lacks the overlay options, unprivileged
+user namespaces are disabled or restricted by AppArmor (see
+[ADR 0008](0008-coding-profile-isolation.md)), or the workspace's filesystem
+cannot be an overlay lower layer. For each
+workspace with an unusable gitfile pointer, it warns with
+`workspace_git_unavailable` when any profile has a sandboxed shell.
+
+Capabilities expose `shell` (`"none"` or `"sandboxed"`) for every profile,
+directly after `grantedExtensionTools`. This is configured intent only.
+
+## Amendments
+
+- ADR 0006: read-only profiles have `read`, `grep`, `find` and `ls`, and
+  additionally `bash` with `shell: "sandboxed"`. The read tools are
+  workspace-confined.
+- ADR 0010: the active tools of a read-only profile are the above, the granted
+  MCP tools and the granted extension tools. A profile with granted extension
+  tools cannot have a sandboxed shell.
+
+## Contract change and versioning
+
+The capabilities field `shell`, the start error `sandbox_unavailable` and the
+confinement of existing read-only profiles change the public contract and need
+minor release **0.13.0** under
+[ADR 0003](0003-post-mvp-maintenance.md#versioning). The confinement breaks
+read-only workflows that read files outside the workspace. This decision does
+not itself bump the version or authorize publication.
+
+## Consequences
+
+- Read-only workers can run Git, tests and scripts without touching the host
+  tree or the network.
+- The sandbox shows only `/usr`, `/etc` and the workspace. Toolchains under the
+  home directory or `/opt` (nvm, `~/.local`) are not available; Node.js and Git
+  from the distribution are.
+- Lock-dependent tests that need a supported local filesystem can fail on the
+  overlay (seen with `test/setup-modes.test.ts` in the #169 probe).
+- The sandbox has no memory, process-count or overlay upper-layer limits.
+  A prompt-injected worker can exhaust memory or processes of the operator's
+  user until the command times out, as a host-mode coding session already
+  can. Limits through a cgroup scope are a possible follow-up.
+- When `bash` truncates long output, the SDK stores the full output in the
+  host's temporary directory and names that file. Confined `read` refuses it
+  and the sandbox's `/tmp` is a fresh tmpfs, so only the truncated output is
+  available; workers should narrow their commands instead.
+- `ls` omits entries that are symlinks pointing outside the read roots,
+  without a notice.
+- The confinement checks a path when the call starts. A concurrent writer in
+  the same workspace, for example a host-mode coding session, could swap a
+  checked directory for a symlink before `rg` or `fd` opens it. Read-only
+  workers cannot create such symlinks themselves.
+- Extension hooks and granted extension tools keep running in the server
+  process with the operator's rights (ADR 0006/0010); confinement covers the
+  built-in tools only.
+- macOS, a VM backend and network allowlists inside the sandbox are out of
+  scope. Coding profiles are unchanged (ADR 0008/0009).

package/docs/architecture.md

@@ -47,7 +47,7 @@ reconciled only when the registration still matches that binding. A changed
 release fails closed and cannot silently inherit or replace another release's
 registration.
 
-`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, `configuration: { fingerprint, reloadPolicy: "restart-required" }` and `events: { delivery: "spool" | "off" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
+`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns workspace aliases with their execution `mode` (plus `writers` and `defaultBase` for container workspaces) and profile aliases with the configured permission/provider/model/thinking intent, the configured extension specs, `grantedExtensionTools`, `shell` (`none` or `sandboxed`) and the selected skill aliases, sorted by alias, `configuration: { fingerprint, reloadPolicy: "restart-required" }` and `events: { delivery: "spool" | "off" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
 
 ## Leased container writers