pi-session-mcp 0.14.1 → 0.14.2

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

@@ -2,6 +2,62 @@
 
 ## Unreleased
 
+## 0.14.2 — 2026-10-30
+
+Patch release under ADR 0003 for Sprint 13 and its follow-ups. The MCP tool
+contract, result codes and configuration schema are unchanged. Collection adds
+the export names `<branch>-index` and `<base>-stash-<n>`, and the versioned
+collection digest means that a writer collected by 0.14.1 but not yet reset
+must be collected once more before `finish`, `reset`, `recreate` or `remove`.
+`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)).
+
+- Writer cleanup no longer loses work that exists only in a stash entry
+  ([#202](https://github.com/plagor44-ux/pi-session-mcp/issues/202)).
+  Collection exports every stash entry, including one without a reflog, as
+  `<base>-stash-<n>` in `stash@{n}` order, and records a digest only when every
+  stash commit exists in the operator checkout. Tags, notes, replace refs,
+  remote-tracking refs and refs in other namespaces stay unexported, but each
+  must name an object the operator checkout already has: otherwise the writer
+  is not at its baseline and collection is `writer_collect_incomplete`, so
+  `finish`, `reset`, `recreate` and `remove` without `--discard` refuse.
+  Provisioned tags and remote-tracking refs, and lightweight tags on exported
+  commits, still pass while the operator checkout has their objects; only such
+  a ref's name is lost at cleanup. Ref names outside the branch export rules,
+  such as a tag `pkg@1.0.0+build`, do not make inspection fail.
+- Writer cleanup no longer loses work that exists only in the clone's Git
+  index ([#200](https://github.com/plagor44-ux/pi-session-mcp/issues/200)).
+  Inspection now also evaluates the original index tree on a temporary copy,
+  so a staged change that the worktree reverted (`git status` `MM`) is neither
+  baseline nor clean. Collection exports such a staged tree as an extra
+  `<branch>-index` commit next to the unchanged `<branch>-wip` and
+  `<base>-detached` exports, and records a digest only when the index and
+  worktree trees exist in the operator checkout. An index that cannot be
+  evaluated, such as an unmerged conflict, makes inspection and collection fail
+  closed (`writer_inspect_failed`, `writer_collect_failed`), so `finish`,
+  `reset`, `recreate` and `remove` without `--discard` refuse and the clone
+  stays unchanged. Upgrade note: the collection digest is versioned and covers
+  the index tree, so a digest recorded by 0.14.1 or earlier never authorizes
+  cleanup; collect a writer once more before resetting or removing it. Pool
+  admission was already index-aware through the in-boundary `git status`
+  probe, and Doctor's `writer_dirty` stays an offline ref-only hint.
+- `--list-models`, `--probe-profile` and sessions now see the models of the
+  catalog overlay that Pi persisted earlier (`models-store.json`), restored
+  offline: no network request and no credential refresh. The catalog restores
+  it at creation; a session restores it for its selected provider only, within
+  the existing auth deadline. Writers receive a byte copy of the host's
+  persisted catalog in their private agent directory at provisioning, reset,
+  recreate and launch; without a host file the copy is removed. Before, a model
+  that only Pi's refreshed catalog offered failed with `probe_model_unknown` or
+  `unknown_model`
+  ([#199](https://github.com/plagor44-ux/pi-session-mcp/issues/199)).
+- `--writer <name> --remove`, provisioning restarts and recreation now remove a
+  writer tree that contains read-only directories, such as the Go module cache
+  of a writer with `--cache go`. Before, removal failed with
+  `writer_operation_failed` after deleting `state.json`, which left a writer
+  that setup could no longer address; `state.json` is now removed last
+  ([#198](https://github.com/plagor44-ux/pi-session-mcp/issues/198)).
+
 ## 0.14.1 — 2026-10-30
 
 Patch release under ADR 0003 for Sprint 12. The MCP tool contract, result

package/README.md

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

package/dist/model-catalog.d.ts

@@ -17,7 +17,14 @@ export interface ModelCatalog {
 export declare const CATALOG_ID_PATTERN: RegExp;
 /** Bound for one offline authentication lookup. */
 export declare const AUTH_CHECK_TIMEOUT_MS = 5000;
-/** The part of the SDK's `ModelRuntime` the catalog reads; created without model network and without a refresh. */
+/**
+ * The part of the SDK's `ModelRuntime` the catalog reads. The runtime is created with `refreshOnCreate: true` and
+ * `allowModelNetwork: false`: that is an offline restore of the catalog Pi persisted earlier (the pi.dev overlay in
+ * `models-store.json`), which the SDK applies only inside its refresh. With network off, a provider reads its stored
+ * credential record, restores the cached catalog and returns before any credential is refreshed, so no request is made.
+ * The availability pass that follows reads credential records and resolves API-key values in-process, like the
+ * `checkAuth` calls below already do; no value leaves the process and no network call is made.
+ */
 export interface CatalogRuntime {
     getProviders(): readonly {
         readonly id: string;
@@ -30,11 +37,17 @@ export interface CatalogRuntime {
         signal?: AbortSignal;
     }): Promise<unknown>;
 }
+/** Options for an offline restore of Pi's persisted catalog: no model network, no credential refresh. */
+export declare const OFFLINE_RUNTIME_OPTIONS: {
+    readonly refreshOnCreate: true;
+    readonly allowModelNetwork: false;
+};
 /**
  * Reads the provider ids Pi knows offline, whether each has configured authentication, and its model
- * ids. `checkAuth` reports only whether and how a provider is configured; its result is reduced to a
- * boolean. `hasConfiguredAuth` is not used: it reads a snapshot that only an online availability refresh
- * fills. Never calls `getAuth` or `getAvailable`, so no credential value is resolved and no provider is
- * contacted. Providers registered only by Pi extensions are not part of the registry.
+ * ids, including the models of Pi's persisted catalog overlay. `checkAuth` reports only whether and how
+ * a provider is configured; its result is reduced to a boolean. `hasConfiguredAuth` is not used. Never
+ * calls `getAuth`, `getAvailable` or `refresh` itself, so no credential value is resolved and no
+ * provider is contacted; the only refresh is the offline restore at creation. Providers registered only
+ * by Pi extensions are not part of the registry.
  */
 export declare function createModelCatalog(createRuntime?: () => Promise<CatalogRuntime>): Promise<ModelCatalog>;

package/dist/model-catalog.js

@@ -5,7 +5,9 @@
 export const CATALOG_ID_PATTERN = /^[A-Za-z0-9@][A-Za-z0-9._:@\/-]{0,255}$/;
 /** Bound for one offline authentication lookup. */
 export const AUTH_CHECK_TIMEOUT_MS = 5_000;
-const createCatalogRuntime = () => import("@earendil-works/pi-coding-agent").then(({ ModelRuntime }) => ModelRuntime.create({ refreshOnCreate: false, allowModelNetwork: false }));
+/** Options for an offline restore of Pi's persisted catalog: no model network, no credential refresh. */
+export const OFFLINE_RUNTIME_OPTIONS = { refreshOnCreate: true, allowModelNetwork: false };
+const createCatalogRuntime = () => import("@earendil-works/pi-coding-agent").then(({ ModelRuntime }) => ModelRuntime.create({ ...OFFLINE_RUNTIME_OPTIONS }));
 const compareIds = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
 /** True only for a settled, present result; a rejection or a lookup past the bound counts as not configured. */
 const authConfigured = (runtime, providerId) => new Promise((resolve) => {
@@ -18,10 +20,11 @@ const authConfigured = (runtime, providerId) => new Promise((resolve) => {
 });
 /**
  * Reads the provider ids Pi knows offline, whether each has configured authentication, and its model
- * ids. `checkAuth` reports only whether and how a provider is configured; its result is reduced to a
- * boolean. `hasConfiguredAuth` is not used: it reads a snapshot that only an online availability refresh
- * fills. Never calls `getAuth` or `getAvailable`, so no credential value is resolved and no provider is
- * contacted. Providers registered only by Pi extensions are not part of the registry.
+ * ids, including the models of Pi's persisted catalog overlay. `checkAuth` reports only whether and how
+ * a provider is configured; its result is reduced to a boolean. `hasConfiguredAuth` is not used. Never
+ * calls `getAuth`, `getAvailable` or `refresh` itself, so no credential value is resolved and no
+ * provider is contacted; the only refresh is the offline restore at creation. Providers registered only
+ * by Pi extensions are not part of the registry.
  */
 export async function createModelCatalog(createRuntime = createCatalogRuntime) {
     const runtime = await createRuntime();

package/dist/sdk-pi-adapter.d.ts

@@ -78,6 +78,11 @@ export declare function createPhase0ResourceLoader(cwd: string, skills?: readonl
     resourceLoader: DefaultResourceLoader;
     settingsManager: SettingsManager;
 }>;
+/**
+ * Created without the refresh-time availability pass, which would read and resolve every provider's credential. Pi's persisted
+ * catalog is restored per session for the selected provider only (`resolveVerifiedModel`). The extension path uses the same factory.
+ */
+export declare const defaultModelRuntimeFactory: () => Promise<ModelRuntime>;
 export declare class SdkPiSessionAdapter implements PiSessionAdapter {
     private runtimePromise;
     private readonly modelRuntimeFactory;

package/dist/sdk-pi-adapter.js

@@ -341,6 +341,11 @@ export async function createPhase0ResourceLoader(cwd, skills = [], permissionPro
     await resourceLoader.reload();
     return { resourceLoader, settingsManager };
 }
+/**
+ * Created without the refresh-time availability pass, which would read and resolve every provider's credential. Pi's persisted
+ * catalog is restored per session for the selected provider only (`resolveVerifiedModel`). The extension path uses the same factory.
+ */
+export const defaultModelRuntimeFactory = () => ModelRuntime.create({ refreshOnCreate: false });
 export class SdkPiSessionAdapter {
     runtimePromise;
     modelRuntimeFactory;
@@ -352,7 +357,7 @@ export class SdkPiSessionAdapter {
     sandbox;
     protectedReadPaths;
     constructor(options = {}) {
-        this.modelRuntimeFactory = options.modelRuntimeFactory ?? (() => ModelRuntime.create({ refreshOnCreate: false }));
+        this.modelRuntimeFactory = options.modelRuntimeFactory ?? defaultModelRuntimeFactory;
         this.createSession = options.createSession ?? createAgentSession;
         this.diagnosticSink = options.diagnosticSink ?? (() => undefined);
         this.mcpConnectionFactory = options.mcpConnectionFactory ?? createStdioMcpConnection;
@@ -597,6 +602,10 @@ export class SdkPiSessionAdapter {
         }
         if (!provider)
             throw this.failure(executionProfile, "provider", "unknown_provider");
+        // Restores the catalog Pi persisted (the pi.dev overlay) for this provider only, offline and bounded (#199). Best effort:
+        // on failure the shipped models remain, and the checks below decide.
+        await withAuthDeadline((signal) => runtime.refresh({ allowNetwork: false, providers: [executionProfile.provider], signal }))
+            .catch(() => undefined);
         let model;
         try {
             model = runtime.getModel(executionProfile.provider, executionProfile.model);

package/dist/writer-launch.d.ts

@@ -22,6 +22,8 @@ export interface LaunchDependencies {
     now(): number;
     /** Warms up one host OAuth credential through Pi's locked store; defaults to the SDK refresh, tests inject a fake. */
     warmupHostCredential?: (input: HostCredentialRefresh) => Promise<void>;
+    /** The host's persisted Pi model catalog copied into the writer's agent directory; defaults to the host agent directory below `home`. */
+    modelsStorePath?: string;
     setInterval(callback: () => void, ms: number): ReturnType<typeof setInterval>;
     clearInterval(timer: ReturnType<typeof setInterval>): void;
 }

package/dist/writer-launch.js

@@ -10,6 +10,7 @@ import { ensureWriterAbsent, writerContainerName } from "./writer-fence.js";
 import { createProcessRunner } from "./setup-process.js";
 import { ensureWriterEventsDirectory, podmanInfo, serveArgs } from "./writer-boundary.js";
 import { expiresWithin, REFRESH_INTERVAL_MS, REFRESH_THRESHOLD_MINUTES, refreshHostCredential, selectedOAuthProviders, selectBoundaryCredentials, writeBoundaryCredentials } from "./writer-credentials.js";
+import { copyModelsStore, hostModelsStorePath } from "./writer-models-store.js";
 import { currentAcceptanceFingerprint, readWriterState, WRITER_NAME_PATTERN, writerEventDeliveryEnabled, writerPaths } from "./writer-state.js";
 export { currentAcceptanceFingerprint } from "./writer-state.js";
 export { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
@@ -122,6 +123,8 @@ async function launchLeased(argv, deps, name, lease) {
     catch {
         return refuse("writer_not_ready");
     }
+    // Best effort: without the host's persisted catalog the writer's Pi keeps the static model list.
+    await copyModelsStore(deps.modelsStorePath ?? hostModelsStorePath(deps.home), paths.agent);
     const command = argv.length > 1 ? argv.slice(1) : ["node", "/opt/pi-session-mcp/dist/main.js"];
     let child;
     try {

package/dist/writer-lifecycle.d.ts

@@ -8,6 +8,8 @@ export interface WriterContext {
     checkout: string;
     alias: string;
     leaseFd?: number;
+    /** The host's persisted Pi model catalog copied into writers; defaults to the host agent directory below `home`. Tests inject it. */
+    modelsStorePath?: string;
 }
 export type WriterOutcome = {
     code: string;
@@ -72,6 +74,11 @@ export declare function inspectWork(ctx: WriterContext, name: string): Promise<{
         commit: string;
     }[];
     dirty: boolean;
+    stashes: readonly string[];
+    unknownRefs: number;
+    indexTree: string;
+    tree: string;
+    headTree: string;
 }>;
 export type CollectOutcome = WriterOutcome & {
     refs: readonly string[];