pi-session-mcp 0.11.9 → 0.12.0

package/dist/tool-schemas.d.ts

@@ -0,0 +1,339 @@
+import { z } from "zod";
+export declare const thinkingLevelSchema: z.ZodEnum<{
+    high: "high";
+    low: "low";
+    max: "max";
+    medium: "medium";
+    minimal: "minimal";
+    off: "off";
+    xhigh: "xhigh";
+}>;
+export declare const viewSchema: z.ZodObject<{
+    id: z.ZodString;
+    workspace: z.ZodString;
+    executionProfile: z.ZodString;
+    profile: z.ZodEnum<{
+        coding: "coding";
+        "read-only": "read-only";
+    }>;
+    provider: z.ZodString;
+    model: z.ZodString;
+    thinkingLevel: z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        off: "off";
+        xhigh: "xhigh";
+    }>;
+    state: z.ZodEnum<{
+        closed: "closed";
+        closing: "closing";
+        failed: "failed";
+        idle: "idle";
+        running: "running";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    lastError: z.ZodOptional<z.ZodString>;
+    writer: z.ZodOptional<z.ZodString>;
+    base: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const aliasSchema: z.ZodString;
+export declare const idInputSchema: z.ZodPipe<z.ZodString, z.ZodString>;
+export declare const successSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    session: z.ZodObject<{
+        id: z.ZodString;
+        workspace: z.ZodString;
+        executionProfile: z.ZodString;
+        profile: z.ZodEnum<{
+            coding: "coding";
+            "read-only": "read-only";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodString;
+        thinkingLevel: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>;
+        state: z.ZodEnum<{
+            closed: "closed";
+            closing: "closing";
+            failed: "failed";
+            idle: "idle";
+            running: "running";
+        }>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        lastError: z.ZodOptional<z.ZodString>;
+        writer: z.ZodOptional<z.ZodString>;
+        base: z.ZodOptional<z.ZodObject<{
+            ref: z.ZodString;
+            commit: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const turnBase: {
+    turnId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+};
+export declare const turnSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    turnId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    state: z.ZodLiteral<"running">;
+}, z.core.$strip>, z.ZodObject<{
+    turnId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    state: z.ZodLiteral<"completed">;
+    completedAt: z.ZodString;
+    assistantText: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    turnId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    state: z.ZodLiteral<"failed">;
+    completedAt: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"turn_failed">;
+        message: z.ZodLiteral<"Pi turn failed">;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    turnId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    state: z.ZodLiteral<"aborted">;
+    completedAt: z.ZodString;
+}, z.core.$strip>], "state">;
+export declare const promptSuccessSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    session: z.ZodObject<{
+        id: z.ZodString;
+        workspace: z.ZodString;
+        executionProfile: z.ZodString;
+        profile: z.ZodEnum<{
+            coding: "coding";
+            "read-only": "read-only";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodString;
+        thinkingLevel: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>;
+        state: z.ZodEnum<{
+            closed: "closed";
+            closing: "closing";
+            failed: "failed";
+            idle: "idle";
+            running: "running";
+        }>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        lastError: z.ZodOptional<z.ZodString>;
+        writer: z.ZodOptional<z.ZodString>;
+        base: z.ZodOptional<z.ZodObject<{
+            ref: z.ZodString;
+            commit: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    turn: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"running">;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"completed">;
+        completedAt: z.ZodString;
+        assistantText: z.ZodString;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"failed">;
+        completedAt: z.ZodString;
+        error: z.ZodObject<{
+            code: z.ZodLiteral<"turn_failed">;
+            message: z.ZodLiteral<"Pi turn failed">;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"aborted">;
+        completedAt: z.ZodString;
+    }, z.core.$strip>], "state">;
+}, z.core.$strip>;
+export declare const turnSuccessSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    turn: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"running">;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"completed">;
+        completedAt: z.ZodString;
+        assistantText: z.ZodString;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"failed">;
+        completedAt: z.ZodString;
+        error: z.ZodObject<{
+            code: z.ZodLiteral<"turn_failed">;
+            message: z.ZodLiteral<"Pi turn failed">;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        turnId: z.ZodString;
+        sessionId: z.ZodString;
+        startedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        state: z.ZodLiteral<"aborted">;
+        completedAt: z.ZodString;
+    }, z.core.$strip>], "state">;
+}, z.core.$strip>;
+export declare const listSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    sessions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        workspace: z.ZodString;
+        executionProfile: z.ZodString;
+        profile: z.ZodEnum<{
+            coding: "coding";
+            "read-only": "read-only";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodString;
+        thinkingLevel: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>;
+        state: z.ZodEnum<{
+            closed: "closed";
+            closing: "closing";
+            failed: "failed";
+            idle: "idle";
+            running: "running";
+        }>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        lastError: z.ZodOptional<z.ZodString>;
+        writer: z.ZodOptional<z.ZodString>;
+        base: z.ZodOptional<z.ZodObject<{
+            ref: z.ZodString;
+            commit: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const errorSchema: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        reason: z.ZodOptional<z.ZodEnum<{
+            none_admitted: "none_admitted";
+            none_at_base: "none_at_base";
+            none_ready: "none_ready";
+        }>>;
+        counts: z.ZodOptional<z.ZodObject<{
+            busy: z.ZodNumber;
+            notAtBaseline: z.ZodNumber;
+            settingsChanged: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const capabilitiesSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    server: z.ZodObject<{
+        name: z.ZodLiteral<string>;
+        version: z.ZodLiteral<string>;
+    }, z.core.$strict>;
+    configuration: z.ZodObject<{
+        fingerprint: z.ZodString;
+        reloadPolicy: z.ZodLiteral<"restart-required">;
+    }, z.core.$strict>;
+    events: z.ZodObject<{
+        delivery: z.ZodEnum<{
+            off: "off";
+            spool: "spool";
+        }>;
+    }, z.core.$strict>;
+    workspaces: z.ZodArray<z.ZodObject<{
+        alias: z.ZodString;
+        mode: z.ZodEnum<{
+            container: "container";
+            host: "host";
+            "read-only": "read-only";
+            unset: "unset";
+        }>;
+        writers: z.ZodOptional<z.ZodNumber>;
+        defaultBase: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    executionProfiles: z.ZodArray<z.ZodObject<{
+        alias: z.ZodString;
+        default: z.ZodBoolean;
+        permissionProfile: z.ZodEnum<{
+            coding: "coding";
+            "read-only": "read-only";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodString;
+        thinkingLevel: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>;
+        extensions: z.ZodArray<z.ZodString>;
+        grantedExtensionTools: z.ZodArray<z.ZodString>;
+        skills: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/tool-schemas.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import packageMetadata from "../package.json" with { type: "json" };
+import { CONFIGURATION_FINGERPRINT_PATTERN, RELOAD_POLICY } from "./config.js";
+import { ALIAS_PATTERN } from "./execution-profile.js";
+export const thinkingLevelSchema = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+export const viewSchema = z.object({
+    id: z.string(), workspace: z.string(), executionProfile: z.string(), profile: z.enum(["read-only", "coding"]),
+    provider: z.string(), model: z.string(), thinkingLevel: thinkingLevelSchema,
+    state: z.enum(["idle", "running", "failed", "closing", "closed"]), createdAt: z.string(), updatedAt: z.string(),
+    lastError: z.string().optional(),
+    writer: z.string().optional(), base: z.object({ ref: z.string(), commit: z.string() }).optional(),
+});
+export const aliasSchema = z.string().regex(ALIAS_PATTERN);
+// Input IDs: tools/list keeps `format: "uuid"` but omits zod's long repeated `pattern`; the
+// server still validates with the unchanged `z.string().uuid()`, so accepted values and issues are identical.
+export const idInputSchema = z.string().meta({ format: "uuid" }).pipe(z.string().uuid());
+export const successSchema = z.object({ ok: z.literal(true), session: viewSchema });
+export const turnBase = { turnId: z.string().uuid(), sessionId: z.string().uuid(), startedAt: z.string(), updatedAt: z.string() };
+export const turnSchema = z.discriminatedUnion("state", [
+    z.object({ ...turnBase, state: z.literal("running") }),
+    z.object({ ...turnBase, state: z.literal("completed"), completedAt: z.string(), assistantText: z.string(), truncated: z.boolean() }),
+    z.object({ ...turnBase, state: z.literal("failed"), completedAt: z.string(), error: z.object({ code: z.literal("turn_failed"), message: z.literal("Pi turn failed") }) }),
+    z.object({ ...turnBase, state: z.literal("aborted"), completedAt: z.string() }),
+]);
+export const promptSuccessSchema = z.object({ ok: z.literal(true), session: viewSchema, turn: turnSchema });
+export const turnSuccessSchema = z.object({ ok: z.literal(true), turn: turnSchema });
+export const listSchema = z.object({ ok: z.literal(true), sessions: z.array(viewSchema) });
+export const errorSchema = z.object({ ok: z.literal(false), error: z.object({ code: z.string(), message: z.string(), reason: z.enum(["none_ready", "none_at_base", "none_admitted"]).optional(), counts: z.object({ busy: z.number().int().nonnegative(), notAtBaseline: z.number().int().nonnegative(), settingsChanged: z.number().int().nonnegative() }).optional() }) });
+export const capabilitiesSchema = z.object({
+    ok: z.literal(true),
+    server: z.object({ name: z.literal(packageMetadata.name), version: z.literal(packageMetadata.version) }).strict(),
+    configuration: z.object({
+        fingerprint: z.string().regex(CONFIGURATION_FINGERPRINT_PATTERN),
+        reloadPolicy: z.literal(RELOAD_POLICY),
+    }).strict(),
+    events: z.object({ delivery: z.enum(["spool", "off"]) }).strict(),
+    workspaces: z.array(z.object({ alias: aliasSchema, mode: z.enum(["unset", "host", "container", "read-only"]), writers: z.number().int().nonnegative().optional(), defaultBase: z.string().nullable().optional() }).strict()),
+    executionProfiles: z.array(z.object({
+        alias: aliasSchema,
+        default: z.boolean(),
+        permissionProfile: z.enum(["read-only", "coding"]),
+        provider: z.string(),
+        model: z.string(),
+        thinkingLevel: thinkingLevelSchema,
+        extensions: z.array(z.string()),
+        grantedExtensionTools: z.array(z.string()),
+        skills: z.array(aliasSchema),
+    }).strict()),
+}).strict();

package/dist/wake-hook.d.ts

@@ -8,11 +8,10 @@ import { type TurnEvent } from "./turn-events.js";
  * Trust model. An event is a wake trigger only; it carries no instruction and no content. Writer
  * namespaces (`<home>/.local/state/pi-session-mcp/writers/<name>/events/`, see `writerEventsDir`) are writable by the
  * worker inside that writer's container, which can create any file, directory or symlink there. The spool is therefore read defensively:
- * - The accepted namespace follows from the arming tool name: `mcp__pi-session-mcp__*` reads the top-level
- *   `<events>/inst-*` directories only; `mcp__pi-coding-<name>-wN__*` reads exactly `inst-*` below
- *   `writerEventsDir(home, "<name>-wN")`. The old `<events>/writer-<name>/` location is not read, no other writer's
- *   directory is listed, and the claim key carries the namespace, so a forged event in
- *   one namespace can neither take nor block a claim of another.
+ * - Only `mcp__pi-session-mcp__*` arms the hook (ADR 0012: relayed writer sessions report through the host
+ *   spool), and it reads the top-level `<events>/inst-*` directories only. No writer directory and no old
+ *   `<events>/writer-<name>/` location is read. The writer namespace type and its scan remain for spools that
+ *   writers of older releases may still hold; the claim key carries the namespace.
  * - Every directory is opened with `O_NOFOLLOW|O_DIRECTORY`, checked on the handle (a directory of this user)
  *   and read through that handle (`/proc/self/fd/<fd>/<name>`). Event delivery is Linux-only (ADR 0011): without
  *   `/proc/self/fd` the program does nothing (see `isSupportedPlatform`). Event files are opened with `O_NOFOLLOW`, must be regular and small.

package/dist/wake-hook.js

@@ -16,7 +16,7 @@ export const CAPPED_SCAN_GAP_MS = 1000;
 export const NO_SPOOL_GRACE_MS = 2000;
 export const CLAIM_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 export const CLAIM_CLEANUP_MAX_ENTRIES = 4096;
-const WAKE_TOOL_PATTERN = /^mcp__(?:(pi-session-mcp)|pi-coding-([a-z][a-z0-9_-]{0,63}-w(?:[1-9]|1[0-6])))__(pi_session_prompt|pi_turn_get)$/;
+const WAKE_TOOL_PATTERN = /^mcp__pi-session-mcp__(pi_session_prompt|pi_turn_get)$/;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const INSTANCE_DIR_PATTERN = /^inst-[0-9a-f]{16}$/;
 const MAX_CONTENT_BLOCKS = 32;
@@ -88,11 +88,8 @@ export function parseHookInput(text) {
     const match = WAKE_TOOL_PATTERN.exec(input.tool_name);
     if (!match)
         return undefined;
-    const isPrompt = match[3] === "pi_session_prompt";
-    const writer = match[2];
-    if (writer !== undefined && !WRITER_NAME_PATTERN.test(writer))
-        return undefined;
-    const namespace = writer === undefined ? HOST_NAMESPACE : { kind: "writer", name: writer };
+    const isPrompt = match[1] === "pi_session_prompt";
+    const namespace = HOST_NAMESPACE;
     for (const payload of payloadCandidates(input.tool_response)) {
         if (payload.ok !== true || !isObject(payload.turn) || payload.turn.state !== "running")
             continue;

package/dist/writer-acceptance.js

@@ -3,6 +3,12 @@ import { mkdir, mkdtemp, open, readFile, rm, writeFile } from "node:fs/promises"
 import { join } from "node:path";
 import { podmanInfo } from "./writer-boundary.js";
 import { currentAcceptanceFingerprint, readWriterState, writerAcceptanceCurrent, writerPaths, writersRoot, 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] }) } };
+}
 export function controlStatePath(home) {
     return join(home, ".local", "state", "pi-session-mcp", "isolation-control.json");
 }
@@ -72,6 +78,7 @@ async function recordFailure(root, file, code, result) {
     catch { /* Diagnostics only. */ }
 }
 export async function runIsolationControl(ctx) {
+    ctx = leasedContext(ctx);
     const record = async (verdict) => {
         await writeFile(controlStatePath(ctx.home), JSON.stringify({ schemaVersion: 1, verdict, at: new Date().toISOString() }) + "\n", { mode: 0o600 });
     };
@@ -107,6 +114,7 @@ export async function runIsolationControl(ctx) {
  * would downgrade a ready writer before it found that out, so setup leaves the writer as it is.
  */
 export async function acceptanceCurrent(ctx, name) {
+    ctx = leasedContext(ctx);
     let state;
     try {
         state = await readWriterState(ctx.home, name);
@@ -135,6 +143,7 @@ export async function acceptanceCurrent(ctx, name) {
     }
 }
 export async function acceptWriter(ctx, name) {
+    ctx = leasedContext(ctx);
     let paths; // Set once the writer state is accepted; failures after it leave a record.
     let ran;
     const fail = async (code) => {
@@ -165,7 +174,7 @@ export async function acceptWriter(ctx, name) {
         // Acceptance makes no provider request: a launch-time refresh of an expired host token would change
         // the host agent directory inside the harness's digest window (#131).
         ran = await harness(ctx, ["--mode", "contained", "--agent-dir-copy-writable", "--agent-dir-copy", paths.agent,
-            "--launch", `${quote(paths.wrapper)} node`, "--workspace", paths.clone], { PI_WRITER_NO_CREDENTIAL_REFRESH: "1" });
+            "--launch", `${quote(paths.wrapper)} node`, "--workspace", paths.clone], { PI_WRITER_NO_CREDENTIAL_REFRESH: "1", ...(ctx.leaseFd === undefined ? {} : { PI_WRITER_LEASE_FD: "3" }) });
         const network = networkOf(ran.data);
         if (ran.exitCode !== 0 || ran.report !== "present" || ran.data.verdict !== "pass" || (network !== "limited" && network !== "not_limited"))
             return await fail("acceptance_harness_failed");

package/dist/writer-boundary.d.ts

@@ -5,11 +5,13 @@ 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";
 type WriterPaths = ReturnType<typeof writerPaths>;
 export declare class BoundaryError extends Error {
-    readonly code: "image_unavailable" | "clone_verification_failed";
-    constructor(code: "image_unavailable" | "clone_verification_failed");
+    readonly code: "image_unavailable" | "clone_verification_failed" | "writer_fenced";
+    constructor(code: "image_unavailable" | "clone_verification_failed" | "writer_fenced");
 }
 /** `eventsDir` is the dedicated host spool directory of this writer; pass it only when event delivery is enabled for the writer. */
-export declare function serveArgs(paths: WriterPaths, state: WriterState, command: readonly string[], releaseRoot: string, eventsDir?: string): string[];
+export declare function serveArgs(paths: WriterPaths, state: WriterState, command: readonly string[], releaseRoot: string, eventsDir?: string, options?: {
+    name?: string;
+}): string[];
 export declare class EventsDirectoryError extends Error {
     readonly code = "events_directory_unavailable";
     constructor();
@@ -36,7 +38,7 @@ export type EventsCleanupSeam = (stage: "inspected" | "emptied", logicalPath: st
  * (`procDirectory` lets a test stand in for a system without it; writers are Linux-only).
  */
 export declare function ensureWriterEventsDirectory(home: string, name: string, uid: number, now?: number, seam?: EventsCleanupSeam, procDirectory?: string): Promise<string>;
-export declare function throwawayArgs(paths: WriterPaths, imageId: string, opts: {
+export declare function throwawayArgs(name: string, paths: WriterPaths, imageId: string, opts: {
     clone: "ro" | "rw";
     bundles: boolean;
 }, script: string, args: readonly string[]): string[];

package/dist/writer-boundary.js

@@ -1,8 +1,9 @@
 import { constants } from "node:fs";
 import { chmod, lstat, mkdir, open, opendir, readdir, rmdir, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./client-adapters/command.js";
 import { CONTAINER_EVENTS_DIR, EVENTS_DIR_ENV, writerEventsDir } from "./turn-events.js";
+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";
@@ -15,10 +16,11 @@ export class BoundaryError extends Error {
     }
 }
 /** `eventsDir` is the dedicated host spool directory of this writer; pass it only when event delivery is enabled for the writer. */
-export function serveArgs(paths, state, command, releaseRoot, eventsDir) {
+export function serveArgs(paths, state, command, releaseRoot, eventsDir, options) {
     const args = [
         "run", "-i", "--rm", "--pull=never", "--userns=keep-id", "--read-only",
         "--cap-drop=all", "--security-opt=no-new-privileges", `--network=${state.network}`,
+        "--label", writerLabel(options?.name ?? basename(paths.root)),
         "--tmpfs", "/tmp:rw,nosuid,nodev,size=512m",
         "--tmpfs", "/pi/home:rw,nosuid,nodev,mode=0700,size=64m,U",
         "-v", `${paths.clone}:${paths.clone}:rw`,
@@ -33,10 +35,14 @@ export function serveArgs(paths, state, command, releaseRoot, eventsDir) {
         "-e", "PI_CODING_AGENT_DIR=/pi/agent",
         "-e", "PI_SESSION_MCP_WRITER_GUARD=/pi/config/writer-guard.json",
     ];
+    if (options?.name !== undefined)
+        args.push("--name", writerContainerName(options.name));
     if (eventsDir !== undefined)
         args.push("-v", `${eventsDir}:${CONTAINER_EVENTS_DIR}:rw`, "-e", `${EVENTS_DIR_ENV}=${CONTAINER_EVENTS_DIR}`);
     if (state.cache === "go")
         args.push("-v", `${paths.go}:/pi/go:rw`, "-e", "GOPATH=/pi/go", "-e", "GOCACHE=/pi/go/cache", "-e", "GOTOOLCHAIN=local");
+    if (state.cache === "uv")
+        args.push("-v", `${paths.uv}:/pi/uv:rw`, "-e", "UV_CACHE_DIR=/pi/uv/cache", "-e", "npm_config_cache=/pi/uv/npm");
     return [...args, state.imageId, ...command];
 }
 export class EventsDirectoryError extends Error {
@@ -225,10 +231,10 @@ export async function ensureWriterEventsDirectory(home, name, uid, now = Date.no
     }
     return target;
 }
-export function throwawayArgs(paths, imageId, opts, script, args) {
+export function throwawayArgs(name, paths, imageId, opts, script, args) {
     const result = [
         "run", "--rm", "-i", "--pull=never", "--network=none", "--userns=keep-id", "--read-only",
-        "--cap-drop=all", "--security-opt=no-new-privileges",
+        "--cap-drop=all", "--security-opt=no-new-privileges", "--label", writerLabel(name),
         "--tmpfs", "/tmp:rw,nosuid,nodev,size=1g", "-e", "HOME=/tmp",
         "-v", `${paths.clone}:${paths.clone}:${opts.clone}`,
         "--workdir", paths.clone,

package/dist/writer-fence.d.ts

@@ -0,0 +1,12 @@
+import type { CommandRunner } from "./client-adapters/types.js";
+import type { writerPaths } from "./writer-state.js";
+type WriterPaths = ReturnType<typeof writerPaths>;
+export declare const FENCE_STOP_TIMEOUT_MS = 20000;
+export declare function writerContainerName(name: string): string;
+export declare function writerLabel(name: string): string;
+/** The caller holds the lease; no writer data may change until both inventories are empty. */
+export declare function ensureWriterAbsent(runner: CommandRunner, paths: WriterPaths, name: string, options: {
+    leaseFd: number;
+    stopTimeoutMs?: number;
+}): Promise<void>;
+export {};

package/dist/writer-fence.js

@@ -0,0 +1,50 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { BoundaryError } from "./writer-boundary.js";
+export const FENCE_STOP_TIMEOUT_MS = 20_000;
+const containersSchema = z.array(z.object({ Id: z.string().min(1), Names: z.array(z.string()) }));
+export function writerContainerName(name) { return `pi-writer-${name}`; }
+export function writerLabel(name) { return `pi-session-mcp.writer=${name}`; }
+/** The caller holds the lease; no writer data may change until both inventories are empty. */
+export async function ensureWriterAbsent(runner, paths, name, options) {
+    try {
+        const timeoutMs = options.stopTimeoutMs ?? FENCE_STOP_TIMEOUT_MS;
+        if (process.platform !== "linux" || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+            throw new BoundaryError("writer_fenced");
+        const deadline = performance.now() + timeoutMs;
+        const remaining = () => {
+            const left = Math.ceil(deadline - performance.now());
+            if (left <= 0)
+                throw new BoundaryError("writer_fenced");
+            return left;
+        };
+        const podman = async (args) => {
+            const result = await runner.run("podman", args, AbortSignal.timeout(remaining()), { inheritFds: [options.leaseFd] });
+            remaining();
+            if (result.exitCode !== 0 || result.stderr === "output_limit")
+                throw new BoundaryError("writer_fenced");
+            return result.stdout;
+        };
+        const list = async (filter) => containersSchema.parse(JSON.parse(await podman(["ps", "-a", "--filter", filter, "--format", "json"])));
+        const removed = new Set();
+        for (;;) {
+            const labelled = await list(`label=${writerLabel(name)}`);
+            // Podman's volume filter matches the mount destination; every writer container, old releases
+            // included, mounts the clone at its own host path, so this also finds unlabelled ones.
+            const mounted = await list(`volume=${paths.clone}`);
+            const ids = new Set([...labelled, ...mounted].map((container) => container.Id));
+            if (ids.size === 0)
+                return;
+            for (const id of ids) {
+                if (removed.has(id))
+                    continue;
+                await podman(["rm", "-f", "-t", String(Math.ceil(remaining() / 1000)), id]);
+                removed.add(id);
+            }
+            await delay(Math.min(100, remaining()));
+        }
+    }
+    catch {
+        throw new BoundaryError("writer_fenced");
+    }
+}

package/dist/writer-launch.d.ts

@@ -1,13 +1,21 @@
 import { type ChildProcess } from "node:child_process";
 import type { CommandRunner } from "./client-adapters/types.js";
+import { acquireWriterLease, adoptInheritedLease } from "./writer-lease.js";
+import { ensureWriterAbsent } from "./writer-fence.js";
 import { type HostCredentialRefresh } from "./writer-credentials.js";
 export { currentAcceptanceFingerprint } from "./writer-state.js";
 export { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
+export declare const LAUNCHER_CLEANUP_BOUND_MS = 40000;
 export interface LaunchDependencies {
     home: string;
     releaseRoot: string;
     runner: CommandRunner;
-    spawnPodman(args: string[]): ChildProcess;
+    spawnPodman(args: string[], inheritFds: readonly number[]): ChildProcess;
+    lease?: {
+        acquire: typeof acquireWriterLease;
+        adopt: typeof adoptInheritedLease;
+    };
+    ensureAbsent?: typeof ensureWriterAbsent;
     env: NodeJS.ProcessEnv;
     /** The user id that must own the event spool directory; defaults to the process user. */
     uid?: () => number;