pi-session-mcp 0.8.3 → 0.12.0

package/dist/writer-lifecycle.js

@@ -0,0 +1,567 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { configSchema } from "./config.js";
+import { renderWrapper } from "./writer-wrapper.js";
+import { builtinSkillName } from "./skill-catalog.js";
+import { resolveLibrarySkill, shippedLibrarySkill } from "./skill-library.js";
+import { BOUNDARY_GIT, BoundaryError, IMAGE_PULL_TIMEOUT_MS, isSafeRefName, podmanInfo, resolveImage, throwawayArgs, verifyCloneLayout } from "./writer-boundary.js";
+import { readWriterState, writerName, writerPaths, writeWriterState, WriterStateError } from "./writer-state.js";
+function leasedContext(ctx) {
+    if (ctx.leaseFd === undefined)
+        return ctx;
+    const runner = ctx.runner;
+    return { ...ctx, runner: { run: (command, args, signal, options) => runner.run(command, args, signal, { ...options, inheritFds: [ctx.leaseFd] }) } };
+}
+class LifecycleError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function failure(error) {
+    return { status: "failed", code: error instanceof LifecycleError || error instanceof BoundaryError || error instanceof WriterStateError ? error.code : "writer_operation_failed" };
+}
+function record(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new LifecycleError("container_profile_unsupported");
+    return value;
+}
+// Snapshot filesystem-dependent builtin availability before applying the pure profile rules.
+export function containedBuiltinSkills(rawConfig, overrideDirectory) {
+    const available = new Set();
+    if (rawConfig === null || typeof rawConfig !== "object")
+        return available;
+    const catalog = rawConfig.skillCatalog;
+    if (catalog === null || typeof catalog !== "object" || Array.isArray(catalog))
+        return available;
+    for (const value of Object.values(catalog)) {
+        const builtin = typeof value === "string" ? builtinSkillName(value) : undefined;
+        if (builtin !== undefined && shippedLibrarySkill(builtin) !== undefined
+            && (overrideDirectory === undefined || resolveLibrarySkill(builtin, { overrideDirectory })?.source !== "override"))
+            available.add(builtin);
+    }
+    return available;
+}
+// Test one profile against the contained rendering rules without filesystem access or mutation.
+export function containedProfileRefused(rawConfig, profileName, availableBuiltinSkills) {
+    try {
+        buildContainedConfig("repo", "/clone", rawConfig, [profileName], availableBuiltinSkills);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * `overrideDirectory` is the operator's skill override directory of the host configuration. The boundary has none, so a
+ * `builtin:` skill resolves there only to the shipped skill: one without a shipped skill, or one the operator overrides,
+ * would fail to load or be replaced silently, and is refused instead (#135).
+ */
+export function renderContainedConfig(alias, clonePath, rawConfig, selected, overrideDirectory) {
+    const availableBuiltinSkills = containedBuiltinSkills(rawConfig, overrideDirectory);
+    if (selected.some((name) => containedProfileRefused(rawConfig, name, availableBuiltinSkills)))
+        throw new LifecycleError("container_profile_unsupported");
+    return buildContainedConfig(alias, clonePath, rawConfig, selected, availableBuiltinSkills);
+}
+function buildContainedConfig(alias, clonePath, rawConfig, selected, availableBuiltinSkills) {
+    if (selected.length === 0 || selected.includes("boundary-read-only"))
+        throw new LifecycleError("container_profile_unsupported");
+    const raw = record(rawConfig), profiles = record(raw.executionProfiles);
+    const skillCatalog = {};
+    const executionProfiles = Object.fromEntries(selected.map((name) => {
+        const profile = record(Object.hasOwn(profiles, name) ? profiles[name] : undefined);
+        if (profile.extensions !== undefined || profile.mcpServers !== undefined || profile.default !== false || profile.permissionProfile !== "coding") {
+            throw new LifecycleError("container_profile_unsupported");
+        }
+        if (profile.skills !== undefined) {
+            if (!Array.isArray(profile.skills))
+                throw new LifecycleError("container_profile_unsupported");
+            for (const skill of profile.skills) {
+                const catalog = record(raw.skillCatalog);
+                const value = typeof skill === "string" && Object.hasOwn(catalog, skill) ? catalog[skill] : undefined;
+                const builtin = typeof value === "string" ? builtinSkillName(value) : undefined;
+                if (builtin === undefined || !availableBuiltinSkills.has(builtin)) {
+                    throw new LifecycleError("container_profile_unsupported");
+                }
+                Object.defineProperty(skillCatalog, skill, { value, enumerable: true, configurable: true, writable: true });
+            }
+        }
+        return [name, { ...profile }];
+    }));
+    const first = executionProfiles[selected[0]];
+    executionProfiles["boundary-read-only"] = {
+        default: true, permissionProfile: "read-only", provider: first.provider,
+        model: first.model, thinkingLevel: first.thinkingLevel,
+    };
+    // The writer's own configuration is the single source of event delivery for the boundary: launch reads it.
+    const rendered = { ...(raw.events === undefined ? {} : { events: raw.events }), workspaces: { [alias]: clonePath }, executionProfiles, ...(Object.keys(skillCatalog).length === 0 ? {} : { skillCatalog }) };
+    const parsed = configSchema.safeParse(rendered);
+    if (!parsed.success)
+        throw new LifecycleError("container_profile_unsupported");
+    // Validate with the real schema without normalizing or resolving the raw profile objects.
+    return rendered;
+}
+// CommandRunner has no per-call environment option. Hooks are disabled even for injected runners.
+async function git(ctx, args, optional = false) {
+    ctx = leasedContext(ctx);
+    const result = await ctx.runner.run("git", ["-c", "core.hooksPath=/dev/null", "-C", ctx.checkout, ...args], AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    if (result.exitCode !== 0) {
+        if (optional)
+            return undefined;
+        throw new LifecycleError("writer_base_unavailable");
+    }
+    return args[0] === "config" ? result.stdout.replace(/\n$/, "") : result.stdout.trim();
+}
+async function operatorIdentity(ctx) {
+    const name = await git(ctx, ["config", "--get", "user.name"], true);
+    const email = await git(ctx, ["config", "--get", "user.email"], true);
+    const valid = (value) => value !== undefined && value.length >= 1 && value.length <= 256 && !value.startsWith("-") && !/[\p{Cc}]/u.test(value);
+    return valid(name) && valid(email) ? [name, email] : ["", ""];
+}
+function identityScript(name, email) {
+    return `if [ -n "$${name}" ] && [ -n "$${email}" ]; then\n${BOUNDARY_GIT} config user.name "$${name}"\n${BOUNDARY_GIT} config user.email "$${email}"\nelse\n${BOUNDARY_GIT} config --unset-all user.name || :\n${BOUNDARY_GIT} config --unset-all user.email || :\nfi`;
+}
+async function collectGit(ctx, args) {
+    try {
+        return await git(ctx, args);
+    }
+    catch {
+        throw new LifecycleError("writer_collect_failed");
+    }
+}
+function shortBranch(ref) {
+    const short = ref.startsWith("refs/heads/") ? ref.slice(11)
+        : ref.startsWith("refs/remotes/") ? ref.slice(13).split("/").slice(1).join("/") : ref;
+    if (!isSafeRefName(short))
+        throw new LifecycleError("base_ref_invalid");
+    return short;
+}
+async function resolveBase(ctx, requested) {
+    let ref = requested ?? await git(ctx, ["symbolic-ref", "refs/remotes/origin/HEAD"], true) ?? "refs/heads/main";
+    if (!isSafeRefName(ref) || ref === "HEAD" || /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(ref))
+        throw new LifecycleError("base_ref_invalid");
+    if (!ref.startsWith("refs/")) {
+        const resolved = await git(ctx, ["rev-parse", "--symbolic-full-name", "--verify", "--end-of-options", ref], true);
+        if (!resolved?.startsWith("refs/heads/"))
+            throw new LifecycleError("base_ref_invalid");
+        ref = resolved;
+    }
+    if (!/^refs\/heads\/.+/.test(ref) && !/^refs\/remotes\/[^/]+\/.+/.test(ref))
+        throw new LifecycleError("base_ref_invalid");
+    if (!isSafeRefName(ref))
+        throw new LifecycleError("base_ref_invalid");
+    const short = shortBranch(ref);
+    const commit = await git(ctx, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]);
+    if (!commit || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(commit))
+        throw new LifecycleError("writer_base_unavailable");
+    return { ref, short, commit };
+}
+/** The short branch name provisioning would record for `requested` (or its default base), normalized like the writer state. */
+export async function baseBranchName(ctx, requested) {
+    return (await resolveBase(ctx, requested)).short;
+}
+async function baseBundle(ctx, paths, ref, commit, tags) {
+    // for-each-ref prints one full ref per line; `git tag` honours column.ui/column.tag and can print several per line.
+    const reachable = tags === "reachable" ? (await git(ctx, ["for-each-ref", "--format=%(refname)", "--merged", commit, "refs/tags"]))?.split("\n").filter((ref) => ref.startsWith("refs/tags/")) ?? [] : [];
+    await rm(join(paths.bundles, "base.bundle"), { force: true });
+    await git(ctx, ["bundle", "create", join(paths.bundles, "base.bundle"), ref, ...reachable]);
+    await chmod(join(paths.bundles, "base.bundle"), 0o600);
+}
+async function cloneFromBundle(ctx, paths, imageId, base, remote, tags) {
+    // Clone only auto-fetches refs/heads; fetch the exact bundled ref before checkout.
+    const script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\n${BOUNDARY_GIT} clone --no-hardlinks /bundles/base.bundle "$1"\ncd "$1"\n${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle "$5"\n${BOUNDARY_GIT} checkout -B "$2" "$3"\nif [ -n "$4" ]; then ${BOUNDARY_GIT} remote set-url origin "$4"; else ${BOUNDARY_GIT} remote remove origin; fi\n${identityScript(6, 7)}\n${tags === "reachable" ? `${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle '+refs/tags/*:refs/tags/*'` : ""}`;
+    const clone = await ctx.runner.run("podman", throwawayArgs(basename(paths.root), paths, imageId, { clone: "rw", bundles: true }, script, [paths.clone, base.short, base.commit, remote ?? "", base.ref, ...await operatorIdentity(ctx)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    if (clone.exitCode !== 0)
+        throw new LifecycleError("writer_clone_failed");
+    await verifyCloneLayout(paths.clone);
+}
+async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    await chmod(path, 0o700);
+}
+async function jsonFile(path, value) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+}
+function rendered(alias, paths, input) {
+    const config = renderContainedConfig(alias, paths.clone, input.rawConfig, input.settings.profiles, input.overrideDirectory);
+    const selected = input.settings.profiles.map((profile) => config.executionProfiles[profile]);
+    const providers = selected.filter((profile, i, all) => all.findIndex((other) => other.provider === profile.provider) === i)
+        .map(({ provider, model }) => ({ provider, model }));
+    return { config, providers };
+}
+/** Key order carries no meaning in the operator's raw profile objects, so it never counts as a change. */
+function canonical(value) {
+    return JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item);
+}
+async function storedConfig(paths) {
+    try {
+        const handle = await open(join(paths.config, "pi-session-mcp.json"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            return (await handle.stat()).isFile() ? JSON.parse(await handle.readFile("utf8")) : undefined;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a provisioned writer still matches what provisioning would write now: its state's settings and the whole
+ * rendered configuration (profiles with model, thinking level and skills, event delivery). A missing or unreadable
+ * configuration never matches.
+ */
+async function sameSettings(paths, existing, settings, now) {
+    const stored = await storedConfig(paths);
+    return stored !== undefined && existing.imageId === now.imageId && existing.lifecycle === settings.lifecycle
+        && existing.network === settings.network && existing.cache === settings.cache && existing.tags === settings.tags
+        && JSON.stringify(existing.profiles) === JSON.stringify(settings.profiles)
+        && JSON.stringify(existing.providers) === JSON.stringify(now.providers) && canonical(withoutDeliveryOff(stored)) === canonical(withoutDeliveryOff(now.config));
+}
+/** `events: { delivery: "off" }` means the same as no `events` field, which writers of releases before 0.11.0 carry. */
+function withoutDeliveryOff(config) {
+    if (config === null || typeof config !== "object" || Array.isArray(config))
+        return config;
+    const { events, ...rest } = config;
+    return canonical(events) === canonical({ delivery: "off" }) ? rest : config;
+}
+/**
+ * Reconcile's check of a kept writer (#134): `undefined` while the writer matches the settings and configuration it
+ * would be provisioned from now; otherwise the finding, usually `writer_settings_changed`. A writer without
+ * provisioned state is only rendered, so the dry run shows a profile that provisioning would refuse. The image is
+ * resolved locally and never pulled: `podman_unavailable` when Podman cannot be asked, `image_unavailable` when it
+ * answers but cannot resolve the image.
+ */
+export async function writerSettingsDrift(ctx, input) {
+    ctx = leasedContext(ctx);
+    try {
+        const name = writerName(ctx.alias, input.index), paths = writerPaths(ctx.home, name);
+        const existing = await readWriterState(ctx.home, name);
+        const { config, providers } = rendered(ctx.alias, paths, input);
+        if (!existing || existing.phase === "provisioning")
+            return undefined;
+        if (!(await podmanInfo(ctx.runner)).usable)
+            return { status: "failed", code: "podman_unavailable" };
+        const imageId = await resolveImage(ctx.runner, input.settings.image, false);
+        return await sameSettings(paths, existing, input.settings, { config, providers, imageId }) ? undefined : { status: "failed", code: "writer_settings_changed" };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function provisionWriter(ctx, input) {
+    ctx = leasedContext(ctx);
+    try {
+        const { index, settings } = input;
+        const name = writerName(ctx.alias, index), paths = writerPaths(ctx.home, name);
+        let existing, restart = false;
+        try {
+            existing = await readWriterState(ctx.home, name);
+        }
+        catch (error) {
+            if (!(error instanceof WriterStateError) || error.code !== "writer_state_invalid")
+                throw error;
+            restart = true;
+        }
+        const { config, providers } = rendered(ctx.alias, paths, input);
+        const base = await resolveBase(ctx, input.baseRef);
+        const { ref, short, commit } = base;
+        const imageId = await resolveImage(ctx.runner, settings.image, true);
+        const remote = await git(ctx, ["remote", "get-url", "origin"], true);
+        if (remote && /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/]*@/.test(remote))
+            throw new LifecycleError("remote_url_refused");
+        if (existing && existing.phase !== "provisioning") {
+            const equal = await sameSettings(paths, existing, settings, { config, providers, imageId })
+                && (input.baseRef === undefined || (existing.base.ref === `refs/heads/${short}` && existing.base.commit === commit));
+            return { code: equal ? "writer_unchanged" : "writer_settings_changed", status: equal ? "unchanged" : "failed" };
+        }
+        if (!existing && !restart) {
+            try {
+                restart = (await readdir(paths.root)).length > 0;
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                    throw error;
+            }
+        }
+        if (restart || existing?.phase === "provisioning")
+            await rm(paths.root, { recursive: true, force: true });
+        // With spool delivery the spool directory exists from provisioning on: launch would otherwise add it to the
+        // writer root, a host directory the acceptance harness digests around its own first launch.
+        const spool = config.events?.delivery === "spool" ? [paths.events] : [];
+        const cache = settings.cache === "go" ? [paths.go] : settings.cache === "uv" ? [paths.uv] : [];
+        for (const path of [paths.root, paths.clone, paths.config, paths.agent, paths.bundles, ...spool, ...cache])
+            await privateDirectory(path);
+        const state = {
+            schemaVersion: 1, alias: ctx.alias, index, phase: "provisioning", lifecycle: settings.lifecycle,
+            profiles: [...settings.profiles], providers, network: settings.network, cache: settings.cache, tags: settings.tags, imageId,
+            base: { ref: `refs/heads/${short}`, commit },
+        };
+        await writeWriterState(ctx.home, name, state);
+        await baseBundle(ctx, paths, ref, commit, settings.tags);
+        await cloneFromBundle(ctx, paths, imageId, base, remote, settings.tags);
+        await jsonFile(join(paths.config, "pi-session-mcp.json"), config);
+        await jsonFile(join(paths.config, "execution-modes.json"), { schemaVersion: 1, workspaces: { [ctx.alias]: { mode: "host", acceptHostWrites: true } } });
+        await jsonFile(join(paths.config, "writer-guard.json"), { schemaVersion: 1, workspace: ctx.alias, baseRef: state.base.ref, baseCommit: commit });
+        await jsonFile(join(paths.agent, "auth.json"), {});
+        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" };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function inspectWork(ctx, name) {
+    ctx = leasedContext(ctx);
+    const state = await readWriterState(ctx.home, name);
+    if (!state || state.alias !== ctx.alias)
+        throw new LifecycleError("writer_state_invalid");
+    const paths = writerPaths(ctx.home, name);
+    await verifyCloneLayout(paths.clone);
+    const script = `set -eu\nexport GIT_CONFIG_NOSYSTEM=1\ncp .git/index /tmp/index\nmkdir /tmp/objects\nexport GIT_INDEX_FILE=/tmp/index GIT_OBJECT_DIRECTORY=/tmp/objects GIT_ALTERNATE_OBJECT_DIRECTORIES="$1/.git/objects"\n${BOUNDARY_GIT} add -A\n${BOUNDARY_GIT} rev-parse --verify HEAD\n${BOUNDARY_GIT} for-each-ref --format='%(refname) %(objectname)' refs/heads refs/stash\n${BOUNDARY_GIT} write-tree\n${BOUNDARY_GIT} rev-parse 'HEAD^{tree}'\n${BOUNDARY_GIT} rev-parse "$2^{tree}"`;
+    const result = await ctx.runner.run("podman", throwawayArgs(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)))
+        throw new LifecycleError("writer_inspect_failed");
+    const refs = lines.map((line) => {
+        const [name, commit, extra] = line.split(" ");
+        if (!name || !isSafeRefName(name) || !commit || !hash.test(commit) || extra !== undefined || !(name.startsWith("refs/heads/") || name === "refs/stash"))
+            throw new LifecycleError("writer_inspect_failed");
+        return { name, commit };
+    });
+    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")}`,
+    };
+}
+async function requiredState(ctx, name) {
+    const state = await readWriterState(ctx.home, name);
+    if (!state || state.alias !== ctx.alias)
+        throw new LifecycleError("writer_state_invalid");
+    return state;
+}
+async function writerBase(ctx, name, state, requested) {
+    if (requested !== undefined)
+        return resolveBase(ctx, requested);
+    // State normalizes remote branches to local heads. The original source ref remains
+    // in the single-ref base bundle, including when no corresponding host head exists.
+    const heads = await git(ctx, ["bundle", "list-heads", join(writerPaths(ctx.home, name).bundles, "base.bundle")], true);
+    const match = /^(?:[0-9a-f]{40}|[0-9a-f]{64}) (refs\/(?:heads\/.+|remotes\/[^/]+\/.+))$/m.exec(heads ?? "");
+    const source = match?.[1];
+    if (source && isSafeRefName(source) && shortBranch(source) === shortBranch(state.base.ref))
+        return resolveBase(ctx, source);
+    return resolveBase(ctx, state.base.ref);
+}
+async function requireCollected(ctx, name, state, discard) {
+    if (discard)
+        return;
+    const work = await inspectWork(ctx, name);
+    if (!work.baseline && state.collected?.digest !== work.digest)
+        throw new LifecycleError("writer_uncollected");
+}
+async function refreshPrivateFiles(ctx, name, state) {
+    const paths = writerPaths(ctx.home, name);
+    for (const path of [join(paths.config, "writer-guard.json"), join(paths.agent, "auth.json")])
+        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"), {});
+}
+export async function collectWriter(ctx, name) {
+    ctx = leasedContext(ctx);
+    const refs = [], findings = [];
+    try {
+        const paths = writerPaths(ctx.home, name);
+        // Check redirects before inspecting or running any Git command on the clone.
+        await verifyCloneLayout(paths.clone);
+        const { collected: previous, ...state } = await requiredState(ctx, name);
+        // Only this attempt's complete export may authorize a subsequent reset/recreate.
+        if (previous !== undefined)
+            await writeWriterState(ctx.home, name, state);
+        const bundle = join(paths.bundles, "collect.bundle");
+        await rm(bundle, { force: true });
+        try {
+            const script = `set -eu
+export GIT_CONFIG_NOSYSTEM=1
+${BOUNDARY_GIT} init --bare /tmp/scratch
+export GIT_ALTERNATE_OBJECT_DIRECTORIES="$1/.git/objects"
+${BOUNDARY_GIT} for-each-ref --format='%(refname) %(objectname)' refs/heads | while read -r ref commit; do
+  if [ "$ref" != "$2" ] || [ "$commit" != "$3" ]; then
+    ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "$ref" "$commit"
+  fi
+done
+cp .git/index /tmp/index
+export GIT_INDEX_FILE=/tmp/index GIT_OBJECT_DIRECTORY=/tmp/scratch/objects
+${BOUNDARY_GIT} add -A
+tree=$(${BOUNDARY_GIT} write-tree)
+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
+    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
+  printf '%s\\n' nothing_to_collect
+else
+  ${BOUNDARY_GIT} --git-dir=/tmp/scratch bundle create /bundles/collect.bundle --all
+fi`;
+            const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "ro", bundles: true }, script, [paths.clone, state.base.ref, state.base.commit, shortBranch(state.base.ref)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+            if (result.exitCode !== 0)
+                throw new LifecycleError("writer_collect_failed");
+            const messages = result.stdout.split("\n");
+            for (const message of messages)
+                if (message === "ref_name_refused")
+                    findings.push({ code: "ref_name_refused" });
+            if (!messages.includes("nothing_to_collect")) {
+                await collectGit(ctx, ["bundle", "verify", bundle]);
+                const heads = await collectGit(ctx, ["bundle", "list-heads", bundle]);
+                for (const line of heads?.split("\n") ?? []) {
+                    if (!line.trim())
+                        continue;
+                    const match = /^(?:[0-9a-f]{40}|[0-9a-f]{64}) (refs\/heads\/(.+))$/.exec(line.trim());
+                    if (!match || !isSafeRefName(match[1]) || !isSafeRefName(match[2])) {
+                        findings.push({ code: "ref_name_refused" });
+                        continue;
+                    }
+                    const source = match[1], destination = `refs/remotes/writer-${name}/${match[2]}`;
+                    await collectGit(ctx, ["fetch", "--no-tags", "--end-of-options", bundle, `+${source}:${destination}`]);
+                    refs.push(destination);
+                }
+            }
+            if (findings.length > 0) {
+                return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
+            }
+            const work = await inspectWork(ctx, name);
+            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 };
+        }
+        finally {
+            await rm(bundle, { force: true });
+        }
+    }
+    catch (error) {
+        return { ...failure(error), refs, refused: findings.length, findings };
+    }
+}
+async function recreate(ctx, name, state, base) {
+    const paths = writerPaths(ctx.home, name);
+    const remote = await git(ctx, ["remote", "get-url", "origin"], true);
+    if (remote && /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/]*@/.test(remote))
+        throw new LifecycleError("remote_url_refused");
+    await baseBundle(ctx, paths, base.ref, base.commit, state.tags);
+    const { collected: _collected, ...retained } = state;
+    const next = { ...retained, base: { ref: `refs/heads/${base.short}`, commit: base.commit } };
+    await writeWriterState(ctx.home, name, { ...next, phase: "provisioning" });
+    for (const path of [paths.clone, paths.agent]) {
+        await rm(path, { recursive: true, force: true });
+        await privateDirectory(path);
+    }
+    await cloneFromBundle(ctx, paths, state.imageId, base, remote, state.tags);
+    await refreshPrivateFiles(ctx, name, next);
+    await writeWriterState(ctx.home, name, next);
+    if (!(await inspectWork(ctx, name)).baseline)
+        throw new LifecycleError("writer_recreate_failed");
+    return { status: "ok", code: "writer_recreated" };
+}
+export async function recreateWriter(ctx, name, opts) {
+    ctx = leasedContext(ctx);
+    try {
+        const state = await requiredState(ctx, name);
+        await requireCollected(ctx, name, state, opts.discard);
+        return await recreate(ctx, name, state, await writerBase(ctx, name, state, opts.baseRef));
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function resetWriter(ctx, name, opts) {
+    ctx = leasedContext(ctx);
+    try {
+        const state = await requiredState(ctx, name);
+        const base = await writerBase(ctx, name, state, opts.baseRef);
+        await requireCollected(ctx, name, state, opts.discard);
+        const paths = writerPaths(ctx.home, name);
+        await verifyCloneLayout(paths.clone);
+        await baseBundle(ctx, paths, base.ref, base.commit, state.tags);
+        const script = `set -eu
+export GIT_CONFIG_NOSYSTEM=1
+${BOUNDARY_GIT} checkout -f --detach
+${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/tags | while read -r ref; do ${BOUNDARY_GIT} update-ref -d "$ref"; done
+${state.tags === "reachable" ? `${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle '+refs/tags/*:refs/tags/*'` : ""}
+${BOUNDARY_GIT} fetch --no-tags /bundles/base.bundle "+$1:$1"
+${BOUNDARY_GIT} checkout -f -B "$2" "$3"
+${BOUNDARY_GIT} reset --hard "$3"
+${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/heads | while read -r ref; do
+  if [ "$ref" != "refs/heads/$2" ]; then ${BOUNDARY_GIT} update-ref -d "$ref"; fi
+done
+${BOUNDARY_GIT} stash clear
+${BOUNDARY_GIT} clean -fd
+${identityScript(4, 5)}`;
+        const result = await ctx.runner.run("podman", throwawayArgs(name, paths, state.imageId, { clone: "rw", bundles: true }, script, [base.ref, base.short, base.commit, ...await operatorIdentity(ctx)]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+        if (result.exitCode !== 0)
+            throw new LifecycleError("writer_reset_failed");
+        const next = { ...state, base: { ref: `refs/heads/${base.short}`, commit: base.commit } };
+        await refreshPrivateFiles(ctx, name, next);
+        await writeWriterState(ctx.home, name, next);
+        try {
+            await verifyCloneLayout(paths.clone);
+            if (!(await inspectWork(ctx, name)).baseline)
+                throw new LifecycleError("writer_reset_failed");
+        }
+        catch {
+            return await recreate(ctx, name, next, base);
+        }
+        const { collected: _collected, ...cleared } = next;
+        await writeWriterState(ctx.home, name, cleared);
+        return { status: "ok", code: "writer_reset" };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function finishWriter(ctx, name, opts = {}) {
+    try {
+        const state = await requiredState(ctx, name);
+        const collected = await collectWriter(ctx, name);
+        if (collected.status === "failed")
+            return collected;
+        return state.lifecycle === "ephemeral" ? await recreateWriter(ctx, name, { discard: false, ...opts }) : await resetWriter(ctx, name, { discard: false, ...opts });
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function removeWriter(ctx, name, opts) {
+    try {
+        const paths = writerPaths(ctx.home, name);
+        const state = await readWriterState(ctx.home, name);
+        if (!state || state.alias !== ctx.alias)
+            throw new LifecycleError("writer_state_invalid");
+        if (!opts.discard) {
+            const work = await inspectWork(ctx, name);
+            if (!work.baseline && state.collected?.digest !== work.digest)
+                throw new LifecycleError("writer_uncollected");
+        }
+        await rm(paths.root, { recursive: true, force: true });
+        return { code: "writer_removed", status: "ok" };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}

package/dist/writer-relay.d.ts

@@ -0,0 +1,33 @@
+import { type Transport } from "@modelcontextprotocol/client";
+import type { WorkspaceModeEntry } from "./execution-modes.js";
+import type { ConfiguredExecutionProfile } from "./execution-profile.js";
+import { type PiSessionAdapter, type PiSessionHandle } from "./pi-adapter.js";
+export declare const RELAY_START_BUDGET_MS = 60000;
+export declare const RELAY_POLL_INTERVAL_MS = 1000;
+export declare const RELAY_CALL_TIMEOUT_MS = 10000;
+export declare const RELAY_PREFLIGHT_DEADLINE_MS = 15000;
+export declare const RELAY_ABORT_DEADLINE_MS = 15000;
+export declare const RELAY_CLEANUP_DEADLINE_MS = 10000;
+export declare const RELAY_MAX_RESPONSE_BYTES = 524288;
+export interface WriterProcessFactory {
+    spawn(wrapperPath: string, env: Record<string, string>): Transport;
+}
+export declare class WriterRelayAdapter implements PiSessionAdapter {
+    private readonly options;
+    constructor(options: {
+        home: string;
+        workspaceModes: ReadonlyMap<string, WorkspaceModeEntry>;
+        executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
+        spawn?: WriterProcessFactory;
+        now?: () => number;
+        pollIntervalMs?: number;
+    });
+    create(input: Parameters<PiSessionAdapter["create"]>[0]): Promise<PiSessionHandle>;
+}
+export declare class RoutingPiSessionAdapter implements PiSessionAdapter {
+    private readonly host;
+    private readonly relay;
+    private readonly workspaceModes;
+    constructor(host: PiSessionAdapter, relay: PiSessionAdapter, workspaceModes: ReadonlyMap<string, WorkspaceModeEntry>);
+    create(input: Parameters<PiSessionAdapter["create"]>[0]): Promise<PiSessionHandle>;
+}