pi-session-mcp 0.14.1 → 0.14.2

package/dist/writer-lifecycle.js

@@ -3,12 +3,15 @@ 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 { removeWriterTree } from "./writer-tree-removal.js";
+import { copyModelsStore, hostModelsStorePath } from "./writer-models-store.js";
 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";
+const modelsStoreSource = (ctx) => ctx.modelsStorePath ?? hostModelsStorePath(ctx.home);
 function leasedContext(ctx) {
     if (ctx.leaseFd === undefined)
         return ctx;
@@ -292,7 +295,7 @@ export async function provisionWriter(ctx, input) {
             }
         }
         if (restart || existing?.phase === "provisioning")
-            await rm(paths.root, { recursive: true, force: true });
+            await removeWriterTree(paths.root);
         // 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] : [];
@@ -312,6 +315,7 @@ export async function provisionWriter(ctx, input) {
         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 });
         await jsonFile(join(paths.agent, "auth.json"), {});
+        await copyModelsStore(modelsStoreSource(ctx), paths.agent);
         await writeFile(paths.wrapper, renderWrapper(ctx.nodePath, ctx.releaseRoot, name), { mode: 0o700, flag: "wx" });
         await writeWriterState(ctx.home, name, { ...state, phase: "not_ready" });
         return { code: "writer_provisioned", status: "ok" };
@@ -320,6 +324,21 @@ export async function provisionWriter(ctx, input) {
         return failure(error);
     }
 }
+/**
+ * Distinct object names among `objects` that the operator checkout does not have. Objects that an operator ref
+ * names need no further call; each remaining one costs one `cat-file`, since the runner has no stdin for a batch.
+ */
+async function missingObjects(ctx, objects) {
+    if (objects.length === 0)
+        return [];
+    const known = new Set((await git(ctx, ["for-each-ref", "--format=%(objectname)"], true))?.split("\n"));
+    const missing = [];
+    for (const object of new Set(objects)) {
+        if (!known.has(object) && await git(ctx, ["cat-file", "-e", object], true) === undefined)
+            missing.push(object);
+    }
+    return missing;
+}
 export async function inspectWork(ctx, name) {
     ctx = leasedContext(ctx);
     const state = await readWriterState(ctx.home, name);
@@ -327,25 +346,40 @@ export async function inspectWork(ctx, name) {
         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 script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\ncp .git/index /tmp/index\ncp .git/index /tmp/staged-index\nmkdir /tmp/objects\nexport GIT_INDEX_FILE=/tmp/index GIT_OBJECT_DIRECTORY=/tmp/objects GIT_ALTERNATE_OBJECT_DIRECTORIES="$1/.git/objects"\nstaged=$(GIT_INDEX_FILE=/tmp/staged-index ${BOUNDARY_GIT} write-tree)\n${BOUNDARY_GIT} add -A\n${BOUNDARY_GIT} rev-parse --verify HEAD\n${BOUNDARY_GIT} for-each-ref --format='%(refname) %(objectname)'\nif stash=$(${BOUNDARY_GIT} rev-parse -q --verify refs/stash); then\n  log=$(${BOUNDARY_GIT} rev-list --walk-reflogs refs/stash)\n  printf 'stash %s\\n' "$stash" $log\nfi\n${BOUNDARY_GIT} write-tree\nprintf '%s\\n' "$staged"\n${BOUNDARY_GIT} rev-parse 'HEAD^{tree}'\n${BOUNDARY_GIT} rev-parse "$2^{tree}"`;
     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");
     const hash = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
-    const head = lines.shift(), baseTree = lines.pop(), headTree = lines.pop(), tree = lines.pop();
-    if (![head, baseTree, headTree, tree].every((value) => value !== undefined && hash.test(value)))
+    const head = lines.shift(), baseTree = lines.pop(), headTree = lines.pop(), indexTree = lines.pop(), tree = lines.pop();
+    if (![head, baseTree, headTree, indexTree, tree].every((value) => value !== undefined && hash.test(value)))
         throw new LifecycleError("writer_inspect_failed");
-    const refs = lines.map((line) => {
+    const refs = [], stashes = [];
+    for (const line of lines) {
         const [name, commit, extra] = line.split(" ");
-        if (!name || !isSafeRefName(name) || !commit || !hash.test(commit) || extra !== undefined || !(name.startsWith("refs/heads/") || name === "refs/stash"))
+        if (!commit || !hash.test(commit) || extra !== undefined)
             throw new LifecycleError("writer_inspect_failed");
-        return { name, commit };
-    });
+        if (name === "stash")
+            stashes.push(commit);
+        // Only branch names reach a command (as export names); other refs such as a tag `pkg@1.0.0+build` are
+        // only compared, so any ref name Git accepts must not make inspection fail.
+        else if (name && (name.startsWith("refs/heads/") ? isSafeRefName(name) : name.startsWith("refs/")))
+            refs.push({ name, commit });
+        else
+            throw new LifecycleError("writer_inspect_failed");
+    }
+    const branches = refs.filter(({ name }) => name.startsWith("refs/heads/"));
+    // Refs outside branches and the stash are not exported (#202): they must name objects the operator
+    // checkout already has, or the clone holds work that only it can recover.
+    const others = refs.filter(({ name }) => !name.startsWith("refs/heads/") && name !== "refs/stash");
+    const unknownRefs = (await missingObjects(ctx, others.map(({ commit }) => commit))).length;
     return {
-        baseline: head === state.base.commit && refs.length === 1 && refs[0].name === state.base.ref && refs[0].commit === state.base.commit && tree === baseTree,
-        dirty: tree !== headTree, head: head, branches: refs.filter(({ name }) => name.startsWith("refs/heads/")),
-        digest: `sha256:${createHash("sha256").update(result.stdout).digest("hex")}`,
+        baseline: head === state.base.commit && branches.length === 1 && branches[0].name === state.base.ref && branches[0].commit === state.base.commit
+            && !refs.some(({ name }) => name === "refs/stash") && stashes.length === 0 && unknownRefs === 0 && tree === baseTree && indexTree === baseTree,
+        dirty: tree !== headTree || indexTree !== headTree, head: head, branches, stashes, unknownRefs,
+        indexTree: indexTree, tree: tree, headTree: headTree,
+        digest: `sha256:${createHash("sha256").update("inspect-v2\n").update(result.stdout).digest("hex")}`,
     };
 }
 async function requiredState(ctx, name) {
@@ -379,6 +413,7 @@ async function refreshPrivateFiles(ctx, name, state) {
         await rm(path, { force: true });
     await jsonFile(join(paths.config, "writer-guard.json"), { schemaVersion: 1, workspace: ctx.alias, baseRef: state.base.ref, baseCommit: state.base.commit });
     await jsonFile(join(paths.agent, "auth.json"), {});
+    await copyModelsStore(modelsStoreSource(ctx), paths.agent);
 }
 export async function collectWriter(ctx, name) {
     ctx = leasedContext(ctx);
@@ -403,13 +438,37 @@ ${BOUNDARY_GIT} for-each-ref --format='%(refname) %(objectname)' refs/heads | wh
     ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "$ref" "$commit"
   fi
 done
+# Every stash entry, newest first as in stash@{n}, under a derived name (#202). The tip covers a missing reflog.
+if stash=$(${BOUNDARY_GIT} rev-parse -q --verify refs/stash); then
+  log=$(${BOUNDARY_GIT} rev-list --walk-reflogs refs/stash)
+  n=0 previous=
+  for commit in "$stash" $log; do
+    if [ "$commit" = "$previous" ]; then continue; fi
+    previous=$commit
+    if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$4-stash-$n" \\
+      || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$4-stash-$n" "$commit" 2>/dev/null; then
+      printf '%s\\n' ref_name_refused
+    fi
+    n=$((n + 1))
+  done
+fi
 cp .git/index /tmp/index
+cp .git/index /tmp/staged-index
 export GIT_INDEX_FILE=/tmp/index GIT_OBJECT_DIRECTORY=/tmp/scratch/objects
+staged=$(GIT_INDEX_FILE=/tmp/staged-index ${BOUNDARY_GIT} write-tree)
 ${BOUNDARY_GIT} add -A
 tree=$(${BOUNDARY_GIT} write-tree)
+export GIT_AUTHOR_NAME=pi-writer GIT_AUTHOR_EMAIL=pi-writer@example.invalid
+export GIT_COMMITTER_NAME=pi-writer GIT_COMMITTER_EMAIL=pi-writer@example.invalid
+if [ "$staged" != "$(${BOUNDARY_GIT} rev-parse 'HEAD^{tree}')" ] && [ "$staged" != "$tree" ]; then
+  commit=$(printf '%s\\n' 'Index collected by pi-session-mcp' | ${BOUNDARY_GIT} commit-tree "$staged" -p HEAD)
+  branch=$(${BOUNDARY_GIT} symbolic-ref --short HEAD || printf '%s' "$4")
+  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$branch-index" \\
+    || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$branch-index" "$commit" 2>/dev/null; then
+    printf '%s\\n' ref_name_refused
+  fi
+fi
 if [ "$tree" != "$(${BOUNDARY_GIT} rev-parse 'HEAD^{tree}')" ]; then
-  export GIT_AUTHOR_NAME=pi-writer GIT_AUTHOR_EMAIL=pi-writer@example.invalid
-  export GIT_COMMITTER_NAME=pi-writer GIT_COMMITTER_EMAIL=pi-writer@example.invalid
   commit=$(printf '%s\\n' 'WIP collected by pi-session-mcp' | ${BOUNDARY_GIT} commit-tree "$tree" -p HEAD)
   branch=$(${BOUNDARY_GIT} symbolic-ref --short HEAD || printf '%s' "$4")
   # A taken name, or one that conflicts with an exported branch path, is refused rather than aborting the export.
@@ -459,11 +518,19 @@ fi`;
             // Defence in depth (#193): whatever the boundary script exported or reported as nothing to collect,
             // every commit the clone's work refers to must exist as a commit object in the operator checkout
             // before a digest is recorded.
-            for (const sha of [work.head, ...work.branches.map((branch) => branch.commit)]) {
+            for (const sha of [work.head, ...work.branches.map((branch) => branch.commit), ...work.stashes]) {
                 if (sha === undefined || await git(ctx, ["cat-file", "-e", `${sha}^{commit}`], true) === undefined) {
                     return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
                 }
             }
+            // Tags, notes and other refs are not exported: their objects must already be in the operator checkout (#202).
+            if (work.unknownRefs > 0)
+                return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
+            for (const tree of [work.indexTree, work.tree]) {
+                if (tree !== work.headTree && await git(ctx, ["cat-file", "-e", `${tree}^{tree}`], true) === undefined) {
+                    return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
+                }
+            }
             await writeWriterState(ctx.home, name, { ...state, collected: { digest: work.digest, at: new Date().toISOString() } });
             return { status: "ok", code: refs.length === 0 ? "nothing_to_collect" : "writer_collected", refs, refused: findings.length, findings };
         }
@@ -485,7 +552,7 @@ async function recreate(ctx, name, state, base) {
     const next = { ...retained, base: { ref: `refs/heads/${base.short}`, commit: base.commit } };
     await writeWriterState(ctx.home, name, { ...next, phase: "provisioning" });
     for (const path of [paths.clone, paths.agent]) {
-        await rm(path, { recursive: true, force: true });
+        await removeWriterTree(path);
         await privateDirectory(path);
     }
     await cloneFromBundle(ctx, paths, state.imageId, base, remote, state.tags);
@@ -574,7 +641,7 @@ export async function removeWriter(ctx, name, opts) {
             if (!work.baseline && state.collected?.digest !== work.digest)
                 throw new LifecycleError("writer_uncollected");
         }
-        await rm(paths.root, { recursive: true, force: true });
+        await removeWriterTree(paths.root);
         return { code: "writer_removed", status: "ok" };
     }
     catch (error) {

package/dist/writer-models-store.d.ts

@@ -0,0 +1,16 @@
+/** File name of Pi's persisted model catalog overlay, next to `auth.json` in an agent directory. */
+export declare const MODELS_STORE_FILE = "models-store.json";
+/** Upper bound for the copied catalog; a larger file is skipped rather than read into memory. */
+export declare const MODELS_STORE_MAX_BYTES: number;
+/** The host's persisted catalog overlay, resolved like the host `auth.json` the launcher reads. */
+export declare const hostModelsStorePath: (home: string) => string;
+/**
+ * Copies the host's persisted Pi model catalog into a writer's private agent directory, so the writer's Pi resolves the
+ * same models as the host (#199). The file holds model catalog data, not credentials, and is copied byte for byte: it is
+ * neither parsed nor printed. A missing, non-regular, symbolic-link or oversized source is skipped, and so is any failure:
+ * the destination is then removed, so neither a stale copy nor a file left by a worker in the writable agent directory
+ * survives, and the writer keeps the static model list shipped with the SDK. The destination is replaced by an atomic
+ * rename of a 0600 temporary file, so a link at the destination path is replaced, never followed. Returns whether a copy
+ * was made.
+ */
+export declare function copyModelsStore(source: string, agentDir: string): Promise<boolean>;

package/dist/writer-models-store.js

@@ -0,0 +1,64 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+/** File name of Pi's persisted model catalog overlay, next to `auth.json` in an agent directory. */
+export const MODELS_STORE_FILE = "models-store.json";
+/** Upper bound for the copied catalog; a larger file is skipped rather than read into memory. */
+export const MODELS_STORE_MAX_BYTES = 32 * 1024 * 1024;
+/** The host's persisted catalog overlay, resolved like the host `auth.json` the launcher reads. */
+export const hostModelsStorePath = (home) => join(home, ".pi", "agent", MODELS_STORE_FILE);
+/**
+ * Copies the host's persisted Pi model catalog into a writer's private agent directory, so the writer's Pi resolves the
+ * same models as the host (#199). The file holds model catalog data, not credentials, and is copied byte for byte: it is
+ * neither parsed nor printed. A missing, non-regular, symbolic-link or oversized source is skipped, and so is any failure:
+ * the destination is then removed, so neither a stale copy nor a file left by a worker in the writable agent directory
+ * survives, and the writer keeps the static model list shipped with the SDK. The destination is replaced by an atomic
+ * rename of a 0600 temporary file, so a link at the destination path is replaced, never followed. Returns whether a copy
+ * was made.
+ */
+export async function copyModelsStore(source, agentDir) {
+    const copied = await copy(source, agentDir);
+    if (!copied)
+        await unlink(join(agentDir, MODELS_STORE_FILE)).catch(() => undefined);
+    return copied;
+}
+async function copy(source, agentDir) {
+    let temporary;
+    try {
+        // O_NOFOLLOW refuses a symbolic link at the source path; the opened file is checked again after open.
+        const input = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        let content;
+        try {
+            const stat = await input.stat();
+            if (!stat.isFile() || stat.size > MODELS_STORE_MAX_BYTES)
+                return false;
+            content = await input.readFile();
+        }
+        finally {
+            await input.close();
+        }
+        if (content.length > MODELS_STORE_MAX_BYTES)
+            return false;
+        await mkdir(agentDir, { recursive: true, mode: 0o700 });
+        temporary = join(agentDir, `.${MODELS_STORE_FILE}-${randomUUID()}.tmp`);
+        const output = await open(temporary, "wx", 0o600);
+        try {
+            await output.writeFile(content);
+            await output.sync();
+        }
+        finally {
+            await output.close();
+        }
+        await rename(temporary, join(agentDir, MODELS_STORE_FILE));
+        temporary = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (temporary !== undefined)
+            await unlink(temporary).catch(() => undefined);
+    }
+}

package/dist/writer-tree-removal.d.ts

@@ -0,0 +1,16 @@
+/** Upper bound for the entries one permission walk visits: a Go module cache holds many thousands. */
+export declare const TREE_WALK_LIMIT = 5000000;
+/**
+ * Gives the current user rwx on every real directory below `root` (and on `root` itself) that lacks it. Go creates
+ * its module cache with directories that have no owner write bit, and Node's recursive `rm` cannot unlink inside
+ * such a directory. Nothing is followed: every entry is `lstat`ed, a symbolic link is never opened or `chmod`ed,
+ * and only directories owned by the current user are changed. The walk visits only entries below `root`.
+ */
+export declare function makeTreeRemovable(root: string, limit?: number): Promise<void>;
+/**
+ * Removes a writer's storage tree. Permissions are restored first. Then everything except the top-level `clone` and
+ * `state.json` is deleted, then `clone`, then `state.json`, then the root. A part-way failure therefore keeps
+ * `state.json`, and as long as anything else fails also `clone`, so a retry without `--discard` can still inspect the
+ * writer instead of finding one that setup can no longer address.
+ */
+export declare function removeWriterTree(root: string): Promise<void>;

package/dist/writer-tree-removal.js

@@ -0,0 +1,75 @@
+import { chmod, lstat, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+/** Upper bound for the entries one permission walk visits: a Go module cache holds many thousands. */
+export const TREE_WALK_LIMIT = 5_000_000;
+const OWNER_RWX = 0o700;
+const errorCode = (error) => (error instanceof Error && "code" in error ? String(error.code) : undefined);
+/**
+ * Gives the current user rwx on every real directory below `root` (and on `root` itself) that lacks it. Go creates
+ * its module cache with directories that have no owner write bit, and Node's recursive `rm` cannot unlink inside
+ * such a directory. Nothing is followed: every entry is `lstat`ed, a symbolic link is never opened or `chmod`ed,
+ * and only directories owned by the current user are changed. The walk visits only entries below `root`.
+ */
+export async function makeTreeRemovable(root, limit = TREE_WALK_LIMIT) {
+    const uid = process.getuid?.();
+    const pending = [root];
+    let visited = 0;
+    for (let path = pending.pop(); path !== undefined; path = pending.pop()) {
+        if (++visited > limit)
+            throw new Error("tree_walk_limit_exceeded");
+        let stat;
+        try {
+            stat = await lstat(path);
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (!stat.isDirectory())
+            continue; // Files and symbolic links need no change; removal unlinks a link without following it.
+        if (uid !== undefined && stat.uid === uid && (stat.mode & OWNER_RWX) !== OWNER_RWX)
+            await chmod(path, (stat.mode & 0o7777) | OWNER_RWX);
+        let names;
+        try {
+            names = await readdir(path);
+        }
+        catch (error) {
+            // A directory of another user stays unreadable; the removal that follows reports it.
+            if (errorCode(error) === "EACCES" || errorCode(error) === "ENOENT")
+                continue;
+            throw error;
+        }
+        for (const name of names)
+            pending.push(join(path, name));
+    }
+}
+/**
+ * Removes a writer's storage tree. Permissions are restored first. Then everything except the top-level `clone` and
+ * `state.json` is deleted, then `clone`, then `state.json`, then the root. A part-way failure therefore keeps
+ * `state.json`, and as long as anything else fails also `clone`, so a retry without `--discard` can still inspect the
+ * writer instead of finding one that setup can no longer address.
+ */
+export async function removeWriterTree(root) {
+    let stat;
+    try {
+        stat = await lstat(root);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    if (!stat.isDirectory()) {
+        await rm(root, { force: true });
+        return;
+    }
+    await makeTreeRemovable(root);
+    for (const name of await readdir(root)) {
+        if (name !== "state.json" && name !== "clone")
+            await rm(join(root, name), { recursive: true, force: true });
+    }
+    await rm(join(root, "clone"), { recursive: true, force: true });
+    await rm(join(root, "state.json"), { force: true });
+    await rm(root, { recursive: true, force: true });
+}

package/docs/acceptance.md

@@ -2598,6 +2598,131 @@ image) reported `writer_accepted` from 09:48 to 09:51 UTC. Client-target
 all 14 writers. Doctor reported no error, only `workspace_mode_unset` for one
 workspace without a mode.
 
+### v0.14.2 pre-release acceptance
+
+`v0.14.2` was accepted on 2026-10-30 from 15:41 to 15:47 UTC on its release
+candidate `e911a6d`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.166.0` and Claude Code `2.1.314`. 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 release ships #198 and #199 (PR #201), #200 (PR #203) and #202
+(PR #204) from `main` at `5acbebb`; the candidate adds only the version, the
+changelog heading and the roadmap lines. The MCP tool contract, result codes
+and configuration schema are unchanged. The #200 source changes were accepted
+on their branch before the merge, see
+[Issue #200 candidate acceptance](#issue-200-candidate-acceptance-2026-10-30);
+#198, #199 and #202 were checked in their pull requests by the full test suite
+and, for #202, the native Podman tests.
+
+- Level 1 in the checkout 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
+    144 files, 4097 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` 8.10.2 finding through `@earendil-works/pi-coding-agent`
+    1.4.0, the latest SDK release, with eight advisories
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 940 files (tarball shasum
+    `775e6de2a6e810839ceb4d8518b8e7c93eae38f3`, identical in three packs). A
+    scan of the unpacked files for private names, hosts and the maintainer's
+    home path found none; the only matches were the public repository owner in
+    links and the already redacted paths of disposable evaluation homes.
+  - Doctor reported `packageVersion` `0.14.2`. 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.14.2`.
+- In every Level 2 run the real client registrations were unchanged and the
+  disposable prefixes were removed.
+- Podman-gated writer tests on the candidate (Podman `6.1.4`): 10 of 10 passed
+  (9 lifecycle tests, including the detached-`HEAD` export of #193, the
+  index-only export of #200 and the stash export of #202, and 1 boundary test).
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+
+Not established for `0.14.2`: a Level 3 cycle on the release candidate, and the
+published-release Level 2 and upgrades, which follow after publishing.
+
+### Issue #200 candidate acceptance (2026-10-30)
+
+Recorded on 2026-10-30 for the unreleased branch `fix/writer-index-only-work`
+([Sprint 13](sprints/2026-10-30-s13-index-only-work.md)), on its source commit
+`1e1e694`, in a fresh clone on Linux (`x64`) with Node.js `26.12.1`, npm
+`12.2.1`, Podman `6.1.4`, Codex CLI `0.166.0` and Claude Code `2.1.314`. Later
+commits on the branch change only documentation.
+
+- Level 1 after `npm ci`: typecheck, `build:cli`, the test run with
+  `NODE_OPTIONS=--unhandled-rejections=strict` (141 files, 4062 passed, 14
+  skipped, no unhandled error), `build` and `git diff --check` exited with `0`,
+  and the status stayed clean. `npm audit --omit=dev` still exits with `1` for
+  the known `undici` finding (#120).
+- Podman-gated writer tests, none skipped: 8 of 8 lifecycle tests, including
+  the new index-only case, and 1 of 1 boundary test. The index-only case fails
+  against the source of `7752d3f` (`baseline: true`).
+- Level 2 in the working tree: 160 of 160 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.14.1`.
+- In every Level 2 run the built files and the real client registrations were
+  unchanged, no process remained, the leak check passed and the disposable
+  directories were removed.
+
+Not established: a Level 3 cycle, macOS, and a productive writer upgrade with
+this change.
+
+### v0.14.1 post-release evidence
+
+Recorded on 2026-10-30 for the published release `0.14.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.14.1` (tag object
+`bd1ba81739742e1692d65425e94d5a091731a402`) peels to the merge commit
+`7752d3f1555d19fed06f43c0e046da07017a3320` of #197, and
+`git describe --tags --exact-match` reports `v0.14.1`. CI on the merge commit
+(run 41013930671) and on the tag (run 41017350738) passed on the first attempt.
+The npm package records `gitHead` `0753fad`, the head of #197, whose tree
+(`36654c3`) is identical to the merge commit's.
+
+- Level 1 on the tag clone after `npm ci`, from 08:27 to 08:29 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (141 files, 4044 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.14.1` and exited with `2` because no
+  configuration was set (`config_missing`).
+- `pi-session-mcp@0.14.1` on npm: 933 files, shasum
+  `886a20688a44a967d1f917e9dad5461e83fbb5e5`; `npm pack` of the tag clone gives
+  the same shasum and file count. It differs from the candidate's
+  `47cf66a3856530112c11095d07cb05b7ab9892f4` below because `0753fad` adds the
+  pre-release record to the packaged `docs/acceptance.md`; no other file
+  changed.
+- Published release, Level 2 on the tag clone, 08:29 to 08:31 UTC: 160 of 160
+  with delivery off and 228 of 228 with `--events spool`. The manifests and
+  the 152 built runtime files were byte-identical before and after the client
+  cycles.
+- Published npm package, Level 2 from a fresh prefix, 08:31 to 08:33 UTC:
+  160 of 160 with delivery off and 228 of 228 with `--events spool`. The
+  install smoke on the published package reported `smoke_passed` with version
+  `0.14.1`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained and the leak check passed. Clients: Codex CLI `0.166.0` and Claude
+  Code `2.1.314`.
+- The GitHub release `v0.14.1` was published the same day.
+
+Installations: the workstation and the second machine (Linux) run `0.14.1`,
+upgraded by the maintainer with the steps of
+[Installation](installation.md#container-writers); both client targets passed
+`--verify`, and Doctor reported no error. On the workstation all 18 writers
+were provisioned again with `0.14.1` on 2026-10-30 for a profile change and
+reported `writer_accepted` and `--writer <name> --verify` ok. Those writers
+were removed before re-provisioning on the strength of the `0.14.1`
+inspection, which #200 shows to ignore work that exists only in the index;
+whether any of them held such work cannot be established afterwards.
+
 ### v0.14.1 pre-release acceptance
 
 `v0.14.1` was accepted on 2026-10-30 from 06:04 to 06:15 UTC on its release

package/docs/doctor-design.md

@@ -44,7 +44,7 @@ and owners are:
 | `writer_not_migrated` | Warning. The writer state still records the legacy launch, so the writer is not in the relay pool | validated writer name |
 | `writer_off_default_base` | Warning. One or more ready writers of a container workspace have a base other than the workspace default base; the remediation states only their count | validated workspace alias |
 | `writer_git_identity_missing` | Clone Git config lacks a readable user name and email (warning); set both in the operator checkout, then reset the writer | validated writer name |
-| `writer_dirty` | HEAD is not the base branch, its commit differs, another branch exists, or Git metadata cannot safely be inspected (warning) | validated writer name |
+| `writer_dirty` | HEAD is not the base branch, its commit differs, another branch exists, or Git metadata cannot safely be inspected (warning). It reads only `HEAD` and refs, never the index or worktree, so an `ok` result is no proof of a clean clone and never authorizes cleanup; the boundary inspection does (#200) | validated writer name |
 | `writer_uncollected_bundle` | Bundles directory is unsafe/unreadable or contains entries other than base.bundle (warning; an absent directory alone does not warn) | validated writer name |
 | `extension_missing` | Pi has no user install of a package that a profile's `extensions` names | `<profile>:<package>` |
 | `extension_version_mismatch` | The installed manifest's version differs from the pinned version, or the manifest or its `pi.extensions` entries are invalid | `<profile>:<package>` |

package/docs/execution-modes.md

@@ -119,6 +119,11 @@ not selected by tool prefix. Their private state lives under
 `$HOME/.local/state/pi-session-mcp/writers/<name>/`: `clone`, `agent`, `config`,
 `bundles`, optional `go`, `wrapper.sh` and `state.json`. This lifecycle metadata
 is distinct from in-memory MCP sessions; it does not implement session resume.
+The writer's `agent` directory also receives a byte copy of the host's persisted
+Pi model catalog (`models-store.json`, catalog data and no credentials) at
+provisioning, reset, recreate and each launch, so that a writer resolves the same
+models as the host. A missing, linked or oversized host file is skipped and the
+writer keeps the SDK's shipped model list.
 Each clone is made via a bundle, with no hardlinks to the operator's repository.
 The workspace records a short default `base` in its container entry, selected
 by `--base` or origin's symbolic HEAD, falling back to local main. Repeating a
@@ -182,10 +187,18 @@ pi-session-mcp-setup --writer my-project-w1 --finish --apply
 
 Collection exports changed branches via a bundle into the operator's checkout as
 `refs/remotes/writer-<name>/<branch>`. Uncommitted/untracked work is captured as a
-synthetic `<branch>-wip` commit. A clean detached HEAD whose commit no branch in
+synthetic `<branch>-wip` commit. A staged index whose tree differs from both
+HEAD's tree and the worktree (for example a staged change that the worktree
+reverted) is exported as an extra synthetic `<branch>-index` commit, so work
+that exists only in the index is recovered too; the same name rules apply. An
+index that cannot be evaluated, such as an unmerged conflict, makes inspection
+and collection fail closed and every non-`--discard` cleanup refuse. Such a
+writer is not at its baseline, so it is not admitted to a new session either;
+its work stays in the clone until the operator decides on `--discard`. Have the
+worker resolve or abort a merge before its session ends. A clean detached HEAD whose commit no branch in
 the clone reaches is exported as `<base>-detached` (for example `main-detached`,
 imported as `refs/remotes/writer-<name>/main-detached`); a dirty detached HEAD
-keeps the `<base>-wip` export. A `<base>-detached` or `<branch>-wip` name that
+keeps the `<base>-wip` export. A `<base>-detached`, `<branch>-wip` or `<branch>-index` name that
 an exported branch already takes, or that conflicts with an exported branch's
 path (such as a branch `main-detached/topic`), is refused and makes collection
 incomplete (`writer_collect_incomplete`); the other branches are still
@@ -198,9 +211,30 @@ commit exist in the operator checkout; otherwise collection is incomplete
 commit: if the operator checkout no longer has it (for example after a deleted
 base branch and garbage collection), collect and finish fail this way even on a
 pristine writer, without refused names; fetch the base again or resolve with
-`--reset --discard --apply`. New work invalidates
-that authorization. Stashes are not exported as branches:
-resolve any needed stash inside the boundary before collection.
+`--reset --discard --apply`. The digest also covers the index tree, and the
+index and worktree tree objects must exist in the operator checkout. New work,
+including a change to the index alone, invalidates that authorization. A digest
+recorded by 0.14.1 or earlier never matches the versioned digest, so collect
+such a writer again before a destructive operation.
+
+Every stash entry is exported as `<base>-stash-<n>`, numbered like
+`stash@{n}` (newest first; for example `main-stash-0`), with its index and
+untracked parts as the commit's parents; `git stash apply` accepts the imported
+ref. The same name rules apply, and every stash commit must exist in the
+operator checkout before a digest is recorded. Tags, notes, replace refs,
+remote-tracking refs and refs in any other namespace are not exported, whatever
+their names. Each must name an object the operator checkout already has,
+otherwise the writer is not at its baseline and collection is incomplete
+(`writer_collect_incomplete`, without a refused name) and no digest is
+recorded. Provisioned tags and remote-tracking refs, and a lightweight tag on
+an exported commit, pass while the operator checkout still has their objects:
+only such a ref's name is lost at cleanup. An annotated tag, a note, a replace
+ref or a moved remote-tracking ref that the worker created blocks cleanup until
+a later session on that writer removes it or the operator decides on
+`--discard`; the server guard admits such a writer as long as its branches,
+stash and worktree are at the baseline. If the operator deletes a provisioned
+annotated tag and its object is garbage-collected, the writer's copy blocks
+cleanup the same way.
 
 `--finish` collects, then resets a persistent writer or recreates an ephemeral
 writer, on the workspace default base. A collect refusing any branch name is incomplete (`writer_collect_incomplete`,
@@ -215,7 +249,7 @@ unexported work. Do not blindly retry or bypass a refusal by changing profiles.
 | `--reset --apply [--base <ref>]` | Reset to current source base branch, delete extra branches/stash and clean untracked files, and ignored files with `--clean all`; falls back to recreation if post-reset verification fails |
 | `--recreate --apply` | Rebuild clone and agent copy from the workspace default base, retaining image/settings |
 | `--finish --apply` | Collect, then reset persistent / recreate ephemeral on the workspace default base |
-| `--remove` | Explicit mutation: unregister owned registrations before removing writer state |
+| `--remove` | Explicit mutation: unregister owned registrations before removing writer state; read-only directories inside the writer root (such as Go's module cache) are made removable first, and `state.json` is removed last |
 | `--verify` | Doctor and bounded relay-path MCP handshake/tools/list/capabilities; verify the host registration with client-target verify too; no session or provider request |
 
 Other than explicit `--remove` and `--verify`, omitting apply only plans.
@@ -305,12 +339,12 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `clone_verification_failed` | Clone layout/hook/config redirects unsafe |
 | `writer_state_invalid` | Missing/malformed/mismatched writer state |
 | `writer_state_unreadable` | Writer state cannot safely be read |
-| `writer_inspect_failed` | Contained work inspection failed |
+| `writer_inspect_failed` | Contained work inspection failed, including an index that cannot be evaluated such as an unmerged conflict |
 | `writer_uncollected` | Changed work lacks a matching complete collection digest; destructive operation refused |
-| `writer_collect_failed` | Bundle generation/verification/import failed |
-| `writer_collect_incomplete` | One or more branch names refused; no cleanup authorization |
-| `ref_name_refused` | Unsafe export name or WIP name collision |
-| `nothing_to_collect` | No changed branch or WIP to export |
+| `writer_collect_failed` | Bundle generation/verification/import failed, including an unmerged index |
+| `writer_collect_incomplete` | One or more branch names refused, a collected commit or tree is missing from the operator checkout, or a tag, note or other unexported ref names an object only the clone has; no cleanup authorization |
+| `ref_name_refused` | Unsafe export name, or a `-wip`, `-index`, `-detached` or `-stash-<n>` name collision |
+| `nothing_to_collect` | No changed branch, WIP, index, detached commit or stash entry to export |
 | `writer_collected` | Complete export recorded |
 | `writer_reset_failed` | Reset command or validation failed |
 | `writer_reset` | Persistent clone reset and verified |

package/docs/installation.md

@@ -105,6 +105,15 @@ Providers registered only by Pi extensions are not listed; the report includes
 that note. Invalid catalog ids are omitted and counted in `omittedIds`.
 Catalog creation failures report `catalog_unavailable`.
 
+The list includes the models in the catalog overlay that Pi persisted earlier
+(`models-store.json` in Pi's agent directory, written when Pi refreshes its
+model catalogs), restored offline. Pi Session MCP makes no request to refresh
+it: run Pi once so that it refreshes its catalogs, and a model that only the
+refreshed catalog offers becomes available to `--list-models`,
+`--probe-profile` and sessions alike. Without that file only the models
+shipped with the Pi SDK are listed. (ADR 0014 describes the original design
+with a catalog that is created without this restore.)
+
 With `PI_SESSION_MCP_CONFIG` already set to the configuration to check:
 
 ```bash