pi-session-mcp 0.14.0 → 0.14.2

package/dist/sdk-pi-adapter.js

@@ -1,6 +1,7 @@
 import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { readFileSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { allowedReadRoots, createConfinedReadOnlyTools } from "./confined-tools.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-tools.js";
@@ -298,7 +299,7 @@ function isTextBlock(block) {
     return candidate.type === "text" && typeof candidate.text === "string";
 }
 /** Independently validated skills replace package and extension discovery on every reload. */
-function phase0ResourceLoaderOptions(skills) {
+function phase0ResourceLoaderOptions(skills, confinedCwd) {
     // Keep the closure's snapshot private: the SDK may annotate or mutate returned objects.
     const selected = skills.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } }));
     return {
@@ -307,6 +308,24 @@ function phase0ResourceLoaderOptions(skills) {
         noPromptTemplates: true,
         noThemes: true,
         noContextFiles: false,
+        ...(confinedCwd === undefined ? {} : {
+            agentsFilesOverride: (current) => ({
+                agentsFiles: current.agentsFiles.flatMap((file) => {
+                    try {
+                        const workspace = realpathSync(confinedCwd), real = realpathSync(file.path);
+                        const path = relative(workspace, real);
+                        if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+                            return [];
+                        // Re-read from the verified real path: the SDK read the link before this check.
+                        return [{ path: file.path, content: readFileSync(real, "utf-8").replace(/^\uFEFF/, "") }];
+                    }
+                    catch {
+                        // Unresolvable context files never enter a read-only session's model context.
+                        return [];
+                    }
+                }),
+            }),
+        }),
         systemPrompt: "phase-0-system-prompt-disabled",
         appendSystemPrompt: [],
         systemPromptOverride: () => undefined,
@@ -316,12 +335,17 @@ function phase0ResourceLoaderOptions(skills) {
         themesOverride: () => ({ themes: [], diagnostics: [] }),
     };
 }
-export async function createPhase0ResourceLoader(cwd, skills = []) {
+export async function createPhase0ResourceLoader(cwd, skills = [], permissionProfile) {
     const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
-    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills) });
+    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills, permissionProfile === "read-only" ? cwd : undefined) });
     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;
@@ -333,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;
@@ -367,7 +391,7 @@ export class SdkPiSessionAdapter {
         let resourceLoader;
         let settingsManager;
         try {
-            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills));
+            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills, executionProfile.permissionProfile));
         }
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
@@ -426,7 +450,7 @@ export class SdkPiSessionAdapter {
                 agentDir: cwd,
                 modelRuntime: runtime,
                 settingsManager: SettingsManager.inMemory(undefined, { projectTrusted: false }),
-                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills), additionalExtensionPaths: directories },
+                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills, executionProfile.permissionProfile === "read-only" ? cwd : undefined), additionalExtensionPaths: directories },
             }));
             this.checkResources(services.resourceLoader, skills, executionProfile, "extension_load");
             const loaded = services.resourceLoader.getExtensions();
@@ -578,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-boundary.d.ts

@@ -2,7 +2,7 @@ import type { CommandRunner } from "./client-adapters/types.js";
 import { writerPaths, type WriterState } from "./writer-state.js";
 export declare const NODE_IMAGE_REF = "docker.io/library/node@sha256:c4d5523090a817b7aa86d2111241fdd4f66d1e27782b44160e6aa63b357ecb2d";
 export declare const IMAGE_PULL_TIMEOUT_MS = 900000;
-export declare const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null";
+export declare const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null -c core.useReplaceRefs=false";
 type WriterPaths = ReturnType<typeof writerPaths>;
 export declare class BoundaryError extends Error {
     readonly code: "image_unavailable" | "clone_verification_failed" | "writer_fenced";

package/dist/writer-boundary.js

@@ -6,7 +6,8 @@ import { CONTAINER_EVENTS_DIR, EVENTS_DIR_ENV, writerEventsDir } from "./turn-ev
 import { writerContainerName, writerLabel } from "./writer-fence.js";
 export const NODE_IMAGE_REF = "docker.io/library/node@sha256:c4d5523090a817b7aa86d2111241fdd4f66d1e27782b44160e6aa63b357ecb2d";
 export const IMAGE_PULL_TIMEOUT_MS = 900_000;
-export const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null";
+// Replace refs in a clone are worker-controlled: they could make unexported work look reachable or clean (#193).
+export const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null -c core.useReplaceRefs=false";
 export class BoundaryError extends Error {
     code;
     constructor(code) {

package/dist/writer-guard.js

@@ -13,7 +13,7 @@ const guardSchema = z.object({
 }).strict();
 const run = promisify(execFile);
 const defaultGit = async (cwd) => {
-    const git = async (...args) => (await run("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args], { cwd, timeout: 10_000, encoding: "utf8" })).stdout;
+    const git = async (...args) => (await run("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "core.useReplaceRefs=false", ...args], { cwd, timeout: 10_000, encoding: "utf8" })).stdout;
     const [status, head, refs] = await Promise.all([
         git("status", "--porcelain=v1", "-uall"),
         git("rev-parse", "HEAD"),

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;
@@ -66,11 +68,17 @@ export declare function provisionWriter(ctx: WriterContext, input: {
 export declare function inspectWork(ctx: WriterContext, name: string): Promise<{
     baseline: boolean;
     digest: string;
+    head?: string;
     branches: readonly {
         name: string;
         commit: string;
     }[];
     dirty: boolean;
+    stashes: readonly string[];
+    unknownRefs: number;
+    indexTree: string;
+    tree: string;
+    headTree: string;
 }>;
 export type CollectOutcome = WriterOutcome & {
     refs: readonly string[];

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");
+        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");
-        return { name, commit };
-    });
+    }
+    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, 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,19 +438,49 @@ ${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")
-  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$branch-wip"; then
+  # A taken name, or one that conflicts with an exported branch path, is refused rather than aborting the export.
+  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$branch-wip" \\
+    || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$branch-wip" "$commit" 2>/dev/null; then
+    printf '%s\\n' ref_name_refused
+  fi
+elif ! ${BOUNDARY_GIT} symbolic-ref -q HEAD >/dev/null 2>&1 && [ -n "$(${BOUNDARY_GIT} rev-list -n 1 HEAD --not --branches)" ]; then
+  # Clean detached HEAD that no branch of the clone reaches: export its commit under a derived name (#193).
+  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$4-detached" \\
+    || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$4-detached" "$(${BOUNDARY_GIT} rev-parse --verify HEAD)" 2>/dev/null; then
     printf '%s\\n' ref_name_refused
-  else
-    ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$branch-wip" "$commit"
   fi
 fi
 if [ -z "$(${BOUNDARY_GIT} --git-dir=/tmp/scratch for-each-ref --format='%(refname)')" ]; then
@@ -450,6 +515,22 @@ fi`;
                 return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
             }
             const work = await inspectWork(ctx, name);
+            // 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), ...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 };
         }
@@ -471,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);
@@ -560,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-relay.js

@@ -2,6 +2,7 @@ import { constants } from "node:fs";
 import { open } from "node:fs/promises";
 import { Client } from "@modelcontextprotocol/client";
 import { z } from "zod";
+import { projectExecutionProfile } from "./capabilities.js";
 import { ChildStdioTransport } from "./child-stdio-transport.js";
 import { PiSessionCreationError, WriterUnavailableError } from "./pi-adapter.js";
 import { RegistryError } from "./session-registry.js";
@@ -71,6 +72,16 @@ const creationCodes = new Set([
     "extension_not_installed", "extension_version_mismatch", "extension_load_failed", "extension_tool_conflict",
     "extension_tool_missing", "skill_load_failed", "sandbox_unavailable", "pi_session_creation_failed",
 ]);
+const exactFields = ["permissionProfile", "provider", "model", "thinkingLevel", "shell"];
+const setFields = ["skills", "extensions", "grantedExtensionTools"];
+const sameSet = (left, right) => {
+    const a = new Set(left), b = new Set(right);
+    return a.size === left.length && b.size === right.length && a.size === b.size && [...a].every(value => b.has(value));
+};
+/** Admission compares every public capability field; a duplicate on either side is a mismatch. */
+function samePublishedProfile(host, inner) {
+    return exactFields.every(key => host[key] === inner[key]) && setFields.every(key => sameSet(host[key], inner[key]));
+}
 class InnerError extends Error {
     code;
     constructor(code) {
@@ -306,7 +317,7 @@ export class WriterRelayAdapter {
                 const capabilities = await connection.call("pi_capabilities_get", {}, capabilitiesSchema, remaining(), input.signal);
                 const inner = capabilities.executionProfiles.find(profile => profile.alias === input.executionProfile.alias);
                 const host = this.options.executionProfiles.get(input.executionProfile.alias);
-                if (!host || !inner || ["permissionProfile", "provider", "model", "thinkingLevel"].some(key => inner[key] !== host[key])) {
+                if (!host || !inner || !samePublishedProfile(projectExecutionProfile(host), inner)) {
                     counts.settingsChanged++;
                     continue;
                 }

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 });
+}