pi-session-mcp 0.11.9 → 0.12.1

package/dist/writer-launch.js

@@ -5,12 +5,15 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isEntryPoint } from "./entry-point.js";
 import { serveRefusal } from "./refusal-server.js";
+import { acquireWriterLease, adoptInheritedLease, WriterLeaseError } from "./writer-lease.js";
+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 { currentAcceptanceFingerprint, readWriterState, WRITER_NAME_PATTERN, writerEventDeliveryEnabled, writerPaths } from "./writer-state.js";
 export { currentAcceptanceFingerprint } from "./writer-state.js";
 export { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
+export const LAUNCHER_CLEANUP_BOUND_MS = 40_000;
 function launchFailure(stage) {
     process.stderr.write(JSON.stringify({ level: "error", event: "writer_launch_failed", stage, code: "writer_launch_failed" }) + "\n");
 }
@@ -27,10 +30,35 @@ export async function launchEntry(argv, deps) {
     }
 }
 export async function launch(argv, deps) {
-    const refuse = async (code) => { await serveRefusal(code); return 0; };
     const name = argv[0];
-    if (!name || !WRITER_NAME_PATTERN.test(name))
-        return refuse("writer_not_ready");
+    if (!name || !WRITER_NAME_PATTERN.test(name)) {
+        await serveRefusal("writer_not_ready");
+        return 0;
+    }
+    const inherited = deps.env.PI_WRITER_LEASE_FD;
+    if (inherited !== undefined && (!Number.isSafeInteger(Number(inherited)) || Number(inherited) < 0 || String(Number(inherited)) !== inherited)) {
+        await serveRefusal("writer_not_ready");
+        return 0;
+    }
+    let lease;
+    try {
+        lease = inherited === undefined
+            ? await (deps.lease?.acquire ?? acquireWriterLease)(deps.home, name, { waitMs: 0 })
+            : await (deps.lease?.adopt ?? adoptInheritedLease)(deps.home, name, Number(inherited));
+    }
+    catch (error) {
+        await serveRefusal(error instanceof WriterLeaseError && error.code === "writer_busy" ? "writer_busy" : "writer_not_ready");
+        return 0;
+    }
+    try {
+        return await launchLeased(argv, deps, name, lease);
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function launchLeased(argv, deps, name, lease) {
+    const refuse = async (code) => { await serveRefusal(code); return 0; };
     const info = await podmanInfo(deps.runner);
     if (!info.usable || !info.version)
         return refuse("container_runtime_unavailable");
@@ -48,8 +76,15 @@ export async function launch(argv, deps) {
     catch {
         return refuse("writer_not_ready");
     }
+    const ensureAbsent = () => (deps.ensureAbsent ?? ensureWriterAbsent)(deps.runner, paths, name, { leaseFd: lease.fd });
+    try {
+        await ensureAbsent();
+    }
+    catch {
+        return refuse("writer_fenced");
+    }
     let eventsDir;
-    if (await writerEventDeliveryEnabled(paths.config)) {
+    if (state.launch !== "relay" && await writerEventDeliveryEnabled(paths.config)) {
         try {
             eventsDir = await ensureWriterEventsDirectory(deps.home, name, (deps.uid ?? (() => process.getuid()))());
         }
@@ -90,46 +125,108 @@ export async function launch(argv, deps) {
     const command = argv.length > 1 ? argv.slice(1) : ["node", "/opt/pi-session-mcp/dist/main.js"];
     let child;
     try {
-        child = deps.spawnPodman(serveArgs(paths, state, command, deps.releaseRoot, eventsDir));
+        child = deps.spawnPodman(serveArgs(paths, state, command, deps.releaseRoot, eventsDir, { name }), [lease.fd]);
     }
     catch {
         launchFailure("spawn");
+        await ensureAbsent();
         return 1;
     }
-    let busy = false;
+    let outstanding;
+    let stopping = false;
     const timer = enabled ? deps.setInterval(() => {
-        if (busy)
+        if (stopping || outstanding)
             return;
-        busy = true;
-        void refresh().catch(() => {
+        outstanding = refresh().catch(() => {
             process.stderr.write(JSON.stringify({ level: "warning", event: "writer_refresh_failed", code: "writer_refresh_failed" }) + "\n");
-        }).finally(() => { busy = false; });
+        }).finally(() => { outstanding = undefined; });
     }, REFRESH_INTERVAL_MS) : undefined;
-    return new Promise((resolveExit) => {
-        const interrupt = () => { child.kill("SIGINT"); };
-        const terminate = () => { child.kill("SIGTERM"); };
-        let finished = false;
-        const finish = (code) => {
-            if (finished)
-                return;
-            finished = true;
-            if (timer !== undefined)
-                deps.clearInterval(timer);
-            process.off("SIGINT", interrupt);
-            process.off("SIGTERM", terminate);
-            resolveExit(code);
+    let closed = false;
+    let exitCode = 1;
+    let spawnFailed = false;
+    let resolveClosed;
+    const childClosed = new Promise((resolve) => { resolveClosed = resolve; });
+    let cleanup;
+    let resolveExit;
+    let rejectExit;
+    const finished = new Promise((resolve, reject) => { resolveExit = resolve; rejectExit = reject; });
+    const stop = (signal) => {
+        if (cleanup)
+            return cleanup;
+        stopping = true;
+        if (timer !== undefined)
+            deps.clearInterval(timer);
+        cleanup = (async () => {
+            let timeout;
+            const bounded = new Promise((resolve) => { timeout = setTimeout(resolve, LAUNCHER_CLEANUP_BOUND_MS); });
+            try {
+                await outstanding;
+                await Promise.race([childClosed, bounded]);
+                if (!closed) {
+                    await deps.runner.run("podman", ["rm", "-f", "-t", "0", writerContainerName(name)], AbortSignal.timeout(20_000), { inheritFds: [lease.fd] }).catch(() => undefined);
+                }
+                await ensureAbsent();
+                return exitCode;
+            }
+            finally {
+                clearTimeout(timeout);
+                process.off("SIGINT", interrupt);
+                process.off("SIGTERM", terminate);
+                process.off("SIGHUP", terminate);
+                process.stdin.off("end", endOfInput);
+                if (child.stdin) {
+                    process.stdin.unpipe(child.stdin);
+                    child.stdin.destroy();
+                    process.stdin.pause();
+                }
+                // A wedged Podman client still retains its inherited lease, but must not pin this launcher.
+                if (!closed)
+                    child.unref?.();
+            }
+        })();
+        void cleanup.then(resolveExit, rejectExit);
+        // Publish the shared cleanup promise before forwarding a signal can produce close.
+        if (signal && !closed)
+            child.kill(signal);
+        return cleanup;
+    };
+    const interrupt = () => { void stop("SIGINT"); };
+    const terminate = () => { void stop("SIGTERM"); };
+    // End of input is passed on through the pipe, not as a signal: a relayed server shuts down on EOF and a
+    // finite acceptance probe needs EOF to run at all. Cleanup starts and waits, bounded, for the child to close.
+    const endOfInput = () => { void stop(); };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    process.on("SIGHUP", terminate);
+    process.stdin.once("end", endOfInput);
+    {
+        // Signal/EOF cleanup and child-exit cleanup share exactly one completion.
+        const complete = () => { void stop(); };
+        const onClose = (code, signal) => {
+            closed = true;
+            exitCode = spawnFailed ? 1 : code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1);
+            resolveClosed();
+            complete();
         };
-        process.on("SIGINT", interrupt);
-        process.on("SIGTERM", terminate);
-        child.once("error", () => { if (!finished)
-            launchFailure("spawn"); finish(1); });
-        child.once("close", (code, signal) => finish(code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1)));
-    });
+        child.once("error", () => { spawnFailed = true; launchFailure("spawn"); complete(); });
+        child.once("close", onClose);
+        // Attach before piping: EOF can arrive immediately, and must not steal MCP input.
+        if (child.stdin) {
+            // Podman can close its pipe before the host notices; cleanup still owns the fence.
+            child.stdin.once("error", terminate);
+            process.stdin.pipe(child.stdin);
+        }
+        if (process.stdin.readableEnded) {
+            child.stdin?.end();
+            endOfInput();
+        }
+    }
+    return finished;
 }
 if (isEntryPoint(import.meta.url, process.argv[1])) {
     void launchEntry(process.argv.slice(2), {
         home: homedir(), releaseRoot: resolve(dirname(fileURLToPath(import.meta.url)), ".."),
-        runner: createProcessRunner(), spawnPodman: (args) => spawn("podman", args, { stdio: "inherit" }),
+        runner: createProcessRunner(), spawnPodman: (args, inheritFds) => spawn("podman", args, { stdio: ["pipe", "inherit", "inherit", ...inheritFds] }),
         env: process.env, now: Date.now, setInterval, clearInterval,
     }).then((code) => { process.exitCode = code; });
 }

package/dist/writer-lease.d.ts

@@ -0,0 +1,28 @@
+import { type StatfsReader } from "./setup-platform.js";
+export declare const LEASE_DIRECTORY: readonly [".local", "state", "pi-session-mcp", "leases"];
+export declare class WriterLeaseError extends Error {
+    readonly code: "writer_busy" | "writer_lease_unavailable";
+    constructor(code: "writer_busy" | "writer_lease_unavailable");
+}
+export interface WriterLease {
+    readonly fd: number;
+    release(): Promise<void>;
+}
+interface LeaseSeams {
+    readonly signal?: AbortSignal;
+    readonly flockCandidates?: readonly string[];
+    readonly isTrustedBinary?: (path: string) => boolean;
+    readonly readStatfs?: StatfsReader;
+}
+export declare function writerLeasePath(home: string, name: string): string;
+export declare function acquireWriterLease(home: string, name: string, options: LeaseSeams & {
+    waitMs: number;
+}): Promise<WriterLease>;
+/**
+ * Adopts a descriptor a parent passed down while it holds the lease. A fresh open must find the
+ * lock busy before the descriptor is touched; if the holder released in between, the descriptor's
+ * own `flock -n` takes the lock instead, which still leaves exactly one exclusive holder. Adopt the
+ * same descriptor once: `release()` closes that descriptor number.
+ */
+export declare function adoptInheritedLease(home: string, name: string, fd: number, options?: LeaseSeams): Promise<WriterLease>;
+export {};

package/dist/writer-lease.js

@@ -0,0 +1,140 @@
+import { close, constants, fstat } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { flockBinary, lockWithFlock, OverrideLockError } from "./override-lock.js";
+import { assertSupportedFilesystem } from "./setup-platform.js";
+import { WRITER_NAME_PATTERN } from "./writer-state.js";
+export const LEASE_DIRECTORY = [".local", "state", "pi-session-mcp", "leases"];
+export class WriterLeaseError extends Error {
+    code;
+    constructor(code) {
+        super("Writer lease is not available");
+        this.code = code;
+        this.name = "WriterLeaseError";
+    }
+}
+export function writerLeasePath(home, name) {
+    if (!WRITER_NAME_PATTERN.test(name))
+        throw new WriterLeaseError("writer_lease_unavailable");
+    return join(home, ...LEASE_DIRECTORY, `${name}.lock`);
+}
+function checkFile(file) {
+    if (!file.isFile() || file.uid !== process.getuid() || (file.mode & 0o7777) !== 0o600) {
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+}
+async function checkPath(path, descriptor) {
+    checkFile(descriptor);
+    const linked = await lstat(path);
+    checkFile(linked);
+    if (descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+        throw new WriterLeaseError("writer_lease_unavailable");
+}
+async function prepare(home, name, options, create) {
+    if (process.platform !== "linux" || options.signal?.aborted)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const path = writerLeasePath(home, name);
+    const binary = flockBinary(options);
+    if (!binary)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const directory = join(home, ...LEASE_DIRECTORY);
+    // The umask may narrow the requested modes; a directory this call created gets its exact mode.
+    if (create && await mkdir(directory, { recursive: true, mode: 0o700 }) !== undefined)
+        await chmod(directory, 0o700);
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.uid !== process.getuid() || (info.mode & 0o7777) !== 0o700)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    await assertSupportedFilesystem(directory, "linux", options.readStatfs);
+    return { path, binary };
+}
+/** Creates the file exclusively and sets its exact mode, or opens the existing one; never follows a link. */
+async function openLeaseFile(path) {
+    try {
+        const created = await open(path, constants.O_NOFOLLOW | constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+        try {
+            await created.chmod(0o600);
+        }
+        catch (error) {
+            await created.close().catch(() => undefined);
+            throw error;
+        }
+        return created;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+    }
+}
+function lease(fd, closeDescriptor) {
+    let released = false;
+    return {
+        fd,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Never unlock explicitly: mutating children can still hold this open file description.
+            await closeDescriptor().catch(() => undefined);
+        },
+    };
+}
+export async function acquireWriterLease(home, name, options) {
+    let handle;
+    try {
+        if (!Number.isFinite(options.waitMs) || options.waitMs < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, true);
+        handle = await openLeaseFile(path);
+        checkFile(await handle.stat());
+        await lockWithFlock(binary, handle.fd, options.waitMs, options.signal, options.waitMs === 0);
+        await checkPath(path, await handle.stat());
+        const held = handle;
+        return lease(held.fd, () => held.close());
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw new WriterLeaseError(error instanceof OverrideLockError && error.code === "override_lock_busy" ? "writer_busy" : "writer_lease_unavailable");
+    }
+}
+/**
+ * Adopts a descriptor a parent passed down while it holds the lease. A fresh open must find the
+ * lock busy before the descriptor is touched; if the holder released in between, the descriptor's
+ * own `flock -n` takes the lock instead, which still leaves exactly one exclusive holder. Adopt the
+ * same descriptor once: `release()` closes that descriptor number.
+ */
+export async function adoptInheritedLease(home, name, fd, options = {}) {
+    let probe;
+    try {
+        if (!Number.isInteger(fd) || fd < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, false);
+        await checkPath(path, await promisify(fstat)(fd));
+        probe = await open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+        await checkPath(path, await probe.stat());
+        // A fresh open must be excluded BEFORE touching the inherited description; otherwise
+        // flock on an unlocked inherited fd would itself acquire a lock and falsely prove ownership.
+        let busy = false;
+        try {
+            await lockWithFlock(binary, probe.fd, 0, options.signal, true);
+        }
+        catch (error) {
+            if (!(error instanceof OverrideLockError) || error.code !== "override_lock_busy")
+                throw error;
+            busy = true;
+        }
+        if (!busy)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        await lockWithFlock(binary, fd, 0, options.signal, true);
+        await checkPath(path, await promisify(fstat)(fd));
+        return lease(fd, () => promisify(close)(fd));
+    }
+    catch {
+        // Rejection does not take ownership of the caller's descriptor.
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+    finally {
+        await probe?.close().catch(() => undefined);
+    }
+}

package/dist/writer-lifecycle.d.ts

@@ -7,6 +7,7 @@ export interface WriterContext {
     runner: CommandRunner;
     checkout: string;
     alias: string;
+    leaseFd?: number;
 }
 export type WriterOutcome = {
     code: string;
@@ -37,6 +38,8 @@ export declare function renderContainedConfig(alias: string, clonePath: string,
         skills?: string[] | undefined;
     }>;
 };
+/** The short branch name provisioning would record for `requested` (or its default base), normalized like the writer state. */
+export declare function baseBranchName(ctx: WriterContext, requested?: string): Promise<string>;
 type ProvisionInput = {
     settings: ContainerSettings;
     rawConfig: unknown;
@@ -78,12 +81,15 @@ export type CollectOutcome = WriterOutcome & {
 export declare function collectWriter(ctx: WriterContext, name: string): Promise<CollectOutcome>;
 export declare function recreateWriter(ctx: WriterContext, name: string, opts: {
     discard: boolean;
+    baseRef?: string;
 }): Promise<WriterOutcome>;
 export declare function resetWriter(ctx: WriterContext, name: string, opts: {
     discard: boolean;
     baseRef?: string;
 }): Promise<WriterOutcome>;
-export declare function finishWriter(ctx: WriterContext, name: string): Promise<WriterOutcome>;
+export declare function finishWriter(ctx: WriterContext, name: string, opts?: {
+    baseRef?: string;
+}): Promise<WriterOutcome>;
 export declare function removeWriter(ctx: WriterContext, name: string, opts: {
     discard: boolean;
 }): Promise<WriterOutcome>;

package/dist/writer-lifecycle.js

@@ -1,13 +1,19 @@
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, mkdir, open, readdir, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+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) {
@@ -100,13 +106,23 @@ function buildContainedConfig(alias, clonePath, rawConfig, selected, availableBu
 }
 // 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 result.stdout.trim();
+    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 {
@@ -143,15 +159,21 @@ async function resolveBase(ctx, requested) {
         throw new LifecycleError("writer_base_unavailable");
     return { ref, short, commit };
 }
-async function baseBundle(ctx, paths, ref) {
+/** 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]);
+    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) {
+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`;
-    const clone = await ctx.runner.run("podman", throwawayArgs(paths, imageId, { clone: "rw", bundles: true }, script, [paths.clone, base.short, base.commit, remote ?? "", base.ref]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    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);
@@ -198,7 +220,7 @@ async function storedConfig(paths) {
 async function sameSettings(paths, existing, settings, now) {
     const stored = await storedConfig(paths);
     return stored !== undefined && existing.imageId === now.imageId && existing.lifecycle === settings.lifecycle
-        && existing.network === settings.network && existing.cache === settings.cache
+        && existing.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));
 }
@@ -217,6 +239,7 @@ function withoutDeliveryOff(config) {
  * 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);
@@ -233,6 +256,7 @@ export async function writerSettingsDrift(ctx, input) {
     }
 }
 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);
@@ -271,16 +295,17 @@ export async function provisionWriter(ctx, input) {
         // With spool delivery the spool directory exists from provisioning on: launch would otherwise add it to the
         // writer root, a host directory the acceptance harness digests around its own first launch.
         const spool = config.events?.delivery === "spool" ? [paths.events] : [];
-        for (const path of [paths.root, paths.clone, paths.config, paths.agent, paths.bundles, ...spool, ...(settings.cache === "go" ? [paths.go] : [])])
+        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, imageId,
+            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);
-        await cloneFromBundle(ctx, paths, imageId, base, remote);
+        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 });
@@ -294,13 +319,14 @@ export async function provisionWriter(ctx, input) {
     }
 }
 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(paths, state.imageId, { clone: "ro", bundles: false }, script, [paths.clone, state.base.commit]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+    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");
@@ -332,7 +358,7 @@ async function writerBase(ctx, name, state, 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\/[^/]+\/.+))$/.exec(heads ?? "");
+    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);
@@ -353,6 +379,7 @@ async function refreshPrivateFiles(ctx, name, state) {
     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);
@@ -394,7 +421,7 @@ if [ -z "$(${BOUNDARY_GIT} --git-dir=/tmp/scratch for-each-ref --format='%(refna
 else
   ${BOUNDARY_GIT} --git-dir=/tmp/scratch bundle create /bundles/collect.bundle --all
 fi`;
-            const result = await ctx.runner.run("podman", throwawayArgs(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));
+            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");
@@ -437,7 +464,7 @@ async function recreate(ctx, name, state, base) {
     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);
+    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" });
@@ -445,7 +472,7 @@ async function recreate(ctx, name, state, base) {
         await rm(path, { recursive: true, force: true });
         await privateDirectory(path);
     }
-    await cloneFromBundle(ctx, paths, state.imageId, base, remote);
+    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)
@@ -453,26 +480,30 @@ async function recreate(ctx, name, state, base) {
     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));
+        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);
+        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"
@@ -480,8 +511,9 @@ ${BOUNDARY_GIT} for-each-ref --format='%(refname)' refs/heads | while read -r re
   if [ "$ref" != "refs/heads/$2" ]; then ${BOUNDARY_GIT} update-ref -d "$ref"; fi
 done
 ${BOUNDARY_GIT} stash clear
-${BOUNDARY_GIT} clean -fd`;
-        const result = await ctx.runner.run("podman", throwawayArgs(paths, state.imageId, { clone: "rw", bundles: true }, script, [base.ref, base.short, base.commit]), AbortSignal.timeout(IMAGE_PULL_TIMEOUT_MS));
+${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 } };
@@ -503,13 +535,13 @@ ${BOUNDARY_GIT} clean -fd`;
         return failure(error);
     }
 }
-export async function finishWriter(ctx, name) {
+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 }) : await resetWriter(ctx, name, { discard: false });
+        return state.lifecycle === "ephemeral" ? await recreateWriter(ctx, name, { discard: false, ...opts }) : await resetWriter(ctx, name, { discard: false, ...opts });
     }
     catch (error) {
         return failure(error);