pi-session-mcp 0.8.3 → 0.12.0

package/dist/writer-relay.js

@@ -0,0 +1,359 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { Client } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import { ChildStdioTransport } from "./child-stdio-transport.js";
+import { PiSessionCreationError, WriterUnavailableError } from "./pi-adapter.js";
+import { RegistryError } from "./session-registry.js";
+import { capabilitiesSchema, errorSchema, promptSuccessSchema, successSchema, turnSuccessSchema } from "./tool-schemas.js";
+import { writerPaths } from "./writer-state.js";
+export const RELAY_START_BUDGET_MS = 60_000;
+export const RELAY_POLL_INTERVAL_MS = 1_000;
+export const RELAY_CALL_TIMEOUT_MS = 10_000;
+export const RELAY_PREFLIGHT_DEADLINE_MS = 15_000;
+export const RELAY_ABORT_DEADLINE_MS = 15_000;
+export const RELAY_CLEANUP_DEADLINE_MS = 10_000;
+// The inner text cap is 64 KiB; JSON escaping can grow it up to sixfold.
+export const RELAY_MAX_RESPONSE_BYTES = 524_288;
+// Read the launch discriminator locally until all writer-state producers have migrated.
+// Unknown fields are deliberately tolerated; no clone inspection is an admission check.
+const relayStateSchema = z.object({
+    alias: z.string(), index: z.number().int(), phase: z.enum(["ready", "not_ready", "provisioning"]),
+    launch: z.enum(["legacy", "relay"]).default("legacy"),
+    acceptance: z.object({ verdict: z.literal("pass"), fingerprint: z.string(), at: z.string(), network: z.enum(["limited", "not_limited"]) }).optional(),
+    base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/) }),
+});
+async function readState(home, name) {
+    try {
+        const file = await open(writerPaths(home, name).state, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > RELAY_MAX_RESPONSE_BYTES)
+                return undefined;
+            const state = relayStateSchema.parse(JSON.parse(await file.readFile("utf8")));
+            return `${state.alias}-w${state.index}` === name ? state : undefined;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bounds even injected transports which ignore AbortSignal. The losing operation stays observed. */
+async function bounded(operation, ms, signal) {
+    const controller = new AbortController();
+    let timer;
+    let cancel;
+    try {
+        return await Promise.race([
+            new Promise((_, reject) => {
+                cancel = () => { controller.abort(); reject(new Error("Relay operation cancelled")); };
+                signal?.addEventListener("abort", cancel, { once: true });
+                timer = setTimeout(cancel, Math.max(0, ms));
+                if (signal?.aborted || ms <= 0)
+                    cancel();
+            }),
+            Promise.resolve().then(() => { controller.signal.throwIfAborted(); return operation(controller.signal); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (cancel)
+            signal?.removeEventListener("abort", cancel);
+    }
+}
+const creationCodes = new Set([
+    "unknown_provider", "unknown_model", "local_authentication_missing", "local_authentication_unavailable",
+    "model_unavailable", "thinking_level_unavailable", "execution_selection_mismatch", "external_mcp_unavailable",
+    "external_mcp_no_tools", "external_mcp_grant_tool_missing", "external_mcp_activation_mismatch",
+    "extension_not_installed", "extension_version_mismatch", "extension_load_failed", "extension_tool_conflict",
+    "extension_tool_missing", "skill_load_failed", "pi_session_creation_failed",
+]);
+class InnerError extends Error {
+    code;
+    constructor(code) {
+        super("Writer refused the operation");
+        this.code = code;
+    }
+}
+class Connection {
+    transport;
+    client = new Client({ name: "pi-session-mcp-relay", version: "1" }, { capabilities: {} });
+    lost = false;
+    onLost;
+    tools = [];
+    constructor(transport) {
+        this.transport = transport;
+        const lost = () => { this.lost = true; this.onLost?.(); };
+        this.client.onclose = lost;
+        this.client.onerror = lost;
+    }
+    async connect(ms, signal) {
+        await bounded(s => this.client.connect(this.transport, { signal: s, timeout: ms }), ms, signal);
+    }
+    async discover(ms, signal) {
+        const result = await bounded(s => this.client.listTools({}, { signal: s, timeout: ms }), ms, signal);
+        this.tools = result.tools;
+    }
+    async call(name, args, schema, ms = RELAY_CALL_TIMEOUT_MS, signal) {
+        const toolDefinition = this.tools.find(tool => tool.name === name);
+        if (!toolDefinition)
+            throw new Error("Writer tool missing");
+        const result = await bounded(s => this.client.callTool({ name, arguments: args }, { signal: s, timeout: ms, maxTotalTimeout: ms, resetTimeoutOnProgress: false, toolDefinition }), ms, signal);
+        try {
+            const raw = result.structuredContent;
+            const encoded = JSON.stringify(raw);
+            if (encoded === undefined || Buffer.byteLength(encoded) > RELAY_MAX_RESPONSE_BYTES)
+                throw new Error();
+            const refusal = errorSchema.safeParse(raw);
+            if (refusal.success)
+                throw new InnerError(refusal.data.error.code);
+            return schema.parse(raw);
+        }
+        catch (error) {
+            if (error instanceof InnerError)
+                throw error;
+            this.lost = true;
+            this.onLost?.();
+            throw new Error("Invalid writer response");
+        }
+    }
+    async cleanup(sessionId, ms = RELAY_CLEANUP_DEADLINE_MS) {
+        // One deadline covers the RPC AND transport close, not two consecutive deadlines.
+        const end = Date.now() + ms;
+        try {
+            if (sessionId && !this.lost)
+                await this.call("pi_session_close", { sessionId }, successSchema, Math.max(0, end - Date.now()));
+        }
+        catch { /* EOF still requests launcher cleanup. */ }
+        finally {
+            try {
+                const closing = this.transport.close();
+                void closing.catch(() => undefined);
+                await bounded(() => closing, Math.max(0, end - Date.now()));
+            }
+            catch { /* bounded shutdown */ }
+        }
+    }
+}
+class RelayHandle {
+    connection;
+    placement;
+    pollIntervalMs;
+    sdkSessionId;
+    appliedSelection;
+    deadlines = { preflightMs: RELAY_PREFLIGHT_DEADLINE_MS, abortMs: RELAY_ABORT_DEADLINE_MS, cleanupMs: RELAY_CLEANUP_DEADLINE_MS };
+    active;
+    disposed = false;
+    disposal;
+    constructor(connection, session, placement, pollIntervalMs) {
+        this.connection = connection;
+        this.placement = placement;
+        this.pollIntervalMs = pollIntervalMs;
+        this.sdkSessionId = session.id;
+        this.appliedSelection = { provider: session.provider, model: session.model, thinkingLevel: session.thinkingLevel };
+        connection.onLost = () => this.settle({ status: "failed" });
+    }
+    isLost() { return this.connection.lost; }
+    settle(outcome) { const active = this.active; this.active = undefined; active?.settle(outcome); }
+    lose() { this.connection.lost = true; this.settle({ status: "failed" }); }
+    observe(turn) {
+        const active = this.active;
+        if (!active || turn.turnId !== active.turnId || turn.sessionId !== this.sdkSessionId) {
+            this.lose();
+            return;
+        }
+        if (active.updatedAt !== undefined && active.updatedAt !== turn.updatedAt)
+            active.activity?.();
+        active.updatedAt = turn.updatedAt;
+        if (turn.state === "completed")
+            this.settle({ status: "completed", assistantText: turn.assistantText, truncated: turn.truncated });
+        else if (turn.state === "aborted" || turn.state === "failed")
+            this.settle({ status: turn.state });
+    }
+    async prompt(text, preflight, onActivity) {
+        if (this.isLost() || this.disposed)
+            throw new RegistryError("writer_session_lost");
+        if (this.active)
+            throw new Error("Relay turn already running");
+        let settle;
+        const outcome = new Promise(resolve => { settle = resolve; });
+        const active = { settle, activity: onActivity };
+        this.active = active;
+        try {
+            const result = await this.connection.call("pi_session_prompt", { sessionId: this.sdkSessionId, prompt: text }, promptSuccessSchema);
+            if (result.turn.state !== "running" || result.session.id !== this.sdkSessionId) {
+                this.lose();
+                preflight(false);
+            }
+            else if (this.active === active) {
+                active.turnId = result.turn.turnId;
+                active.updatedAt = result.turn.updatedAt;
+                preflight(true);
+                void this.poll(active);
+            }
+            else
+                preflight(false);
+        }
+        catch (error) {
+            preflight(false);
+            if (!(error instanceof InnerError) && !this.isLost()) {
+                // Acceptance is uncertain: ask the inner registry to settle before returning failure.
+                try {
+                    await this.abort();
+                }
+                catch {
+                    this.lose();
+                }
+            }
+            this.settle({ status: "failed" });
+        }
+        return outcome;
+    }
+    async poll(active) {
+        while (this.active === active && !this.isLost() && !this.disposed) {
+            await new Promise(resolve => setTimeout(resolve, this.pollIntervalMs));
+            if (this.active !== active || this.isLost() || this.disposed)
+                return;
+            try {
+                const { turn } = await this.connection.call("pi_turn_get", { sessionId: this.sdkSessionId, turnId: active.turnId }, turnSuccessSchema);
+                // An abort may have settled this turn and a new prompt may already be running.
+                if (this.active === active)
+                    this.observe(turn);
+            }
+            catch {
+                this.lose();
+            }
+        }
+    }
+    async abort() {
+        if (this.isLost())
+            throw new Error("Writer session lost");
+        const active = this.active;
+        try {
+            await bounded(async (signal) => {
+                const result = await this.connection.call("pi_session_abort", { sessionId: this.sdkSessionId }, successSchema, RELAY_CALL_TIMEOUT_MS, signal);
+                if (result.session.id !== this.sdkSessionId)
+                    throw new Error("Writer session mismatch");
+                if (!active || this.active !== active)
+                    return;
+                // A lost prompt response has no turn ID. It cannot be safely resumed.
+                if (!active.turnId)
+                    throw new Error("Writer turn unknown");
+                const { turn } = await this.connection.call("pi_turn_get", { sessionId: this.sdkSessionId, turnId: active.turnId }, turnSuccessSchema, RELAY_CALL_TIMEOUT_MS, signal);
+                if (turn.state === "running")
+                    throw new Error("Writer abort incomplete");
+                if (this.active === active)
+                    this.observe(turn);
+            }, RELAY_ABORT_DEADLINE_MS);
+        }
+        catch {
+            this.lose();
+            throw new Error("Writer abort failed");
+        }
+    }
+    dispose() {
+        if (!this.disposal) {
+            this.disposed = true;
+            this.settle({ status: "failed" });
+            this.disposal = this.connection.cleanup(this.sdkSessionId);
+        }
+        return this.disposal;
+    }
+}
+export class WriterRelayAdapter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async create(input) {
+        if (process.platform !== "linux")
+            throw new WriterUnavailableError("none_ready");
+        const now = this.options.now ?? Date.now, end = now() + RELAY_START_BUDGET_MS;
+        const left = () => Math.max(0, end - now());
+        const remaining = () => Math.min(RELAY_CALL_TIMEOUT_MS, left());
+        const settings = this.options.workspaceModes.get(input.workspace)?.container;
+        const ready = [];
+        for (let i = 1; i <= (settings?.writers ?? 0); i++) {
+            const name = `${input.workspace}-w${i}`, state = await readState(this.options.home, name);
+            if (state?.phase === "ready" && state.launch === "relay" && state.acceptance)
+                ready.push({ name, state });
+        }
+        if (!ready.length)
+            throw new WriterUnavailableError("none_ready");
+        const base = input.base ?? settings?.base;
+        const candidates = base === undefined ? [] : ready.filter(({ state }) => state.base.ref === `refs/heads/${base}`);
+        if (!candidates.length)
+            throw new WriterUnavailableError("none_at_base");
+        const counts = { busy: 0, notAtBaseline: 0, settingsChanged: 0 };
+        const env = { HOME: this.options.home };
+        for (const key of ["PATH", "XDG_RUNTIME_DIR"])
+            if (process.env[key] !== undefined)
+                env[key] = process.env[key];
+        const factory = this.options.spawn ?? { spawn: (wrapper, environment) => new ChildStdioTransport(wrapper, environment) };
+        for (const candidate of candidates) {
+            input.signal?.throwIfAborted();
+            if (left() <= 0)
+                break;
+            let connection, sessionId, admitted = false;
+            try {
+                connection = new Connection(factory.spawn(writerPaths(this.options.home, candidate.name).wrapper, env));
+                // The handshake waits for credential warm-up and the container start: it may use the whole budget.
+                await connection.connect(left(), input.signal);
+                await connection.discover(remaining(), input.signal);
+                const capabilities = await connection.call("pi_capabilities_get", {}, capabilitiesSchema, remaining(), input.signal);
+                const inner = capabilities.executionProfiles.find(profile => profile.alias === input.executionProfile.alias);
+                const host = this.options.executionProfiles.get(input.executionProfile.alias);
+                if (!host || !inner || ["permissionProfile", "provider", "model", "thinkingLevel"].some(key => inner[key] !== host[key])) {
+                    counts.settingsChanged++;
+                    continue;
+                }
+                const result = await connection.call("pi_session_start", { workspace: input.workspace, executionProfile: input.executionProfile.alias }, successSchema, remaining(), input.signal);
+                sessionId = result.session.id;
+                if (remaining() <= 0 || connection.lost)
+                    continue;
+                const state = await readState(this.options.home, candidate.name);
+                if (!state || state.base.ref !== candidate.state.base.ref || state.base.commit !== candidate.state.base.commit)
+                    continue;
+                input.signal?.throwIfAborted();
+                admitted = true;
+                return new RelayHandle(connection, result.session, { writer: candidate.name, base: state.base }, this.options.pollIntervalMs ?? RELAY_POLL_INTERVAL_MS);
+            }
+            catch (error) {
+                if (input.signal?.aborted)
+                    throw input.signal.reason;
+                if (error instanceof InnerError) {
+                    if (error.code === "writer_busy")
+                        counts.busy++;
+                    else if (error.code === "writer_uncollected")
+                        counts.notAtBaseline++;
+                    else if (!["writer_fenced", "writer_not_ready", "container_runtime_unavailable"].includes(error.code)) {
+                        const code = error.code;
+                        throw new PiSessionCreationError(creationCodes.has(code) ? code : "pi_session_creation_failed");
+                    }
+                }
+            }
+            finally {
+                // Own bound, not the start budget: a started inner session is always closed explicitly.
+                if (!admitted && connection)
+                    await connection.cleanup(sessionId);
+            }
+        }
+        throw new WriterUnavailableError("none_admitted", counts);
+    }
+}
+export class RoutingPiSessionAdapter {
+    host;
+    relay;
+    workspaceModes;
+    constructor(host, relay, workspaceModes) {
+        this.host = host;
+        this.relay = relay;
+        this.workspaceModes = workspaceModes;
+    }
+    create(input) {
+        return (input.executionProfile.permissionProfile === "coding" && this.workspaceModes.get(input.workspace)?.mode === "container" ? this.relay : this.host).create(input);
+    }
+}

package/dist/writer-state.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+export declare const WRITER_NAME_PATTERN: RegExp;
+export declare class WriterStateError extends Error {
+    readonly code: "writer_state_invalid" | "writer_state_unreadable";
+    constructor(code: "writer_state_invalid" | "writer_state_unreadable");
+}
+export declare const writerStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    alias: z.ZodString;
+    index: z.ZodNumber;
+    phase: z.ZodEnum<{
+        not_ready: "not_ready";
+        provisioning: "provisioning";
+        ready: "ready";
+    }>;
+    lifecycle: z.ZodEnum<{
+        ephemeral: "ephemeral";
+        persistent: "persistent";
+    }>;
+    launch: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        relay: "relay";
+    }>>;
+    profiles: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    providers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>>;
+    network: z.ZodEnum<{
+        none: "none";
+        pasta: "pasta";
+    }>;
+    cache: z.ZodEnum<{
+        go: "go";
+        none: "none";
+        uv: "uv";
+    }>;
+    tags: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        reachable: "reachable";
+    }>>;
+    imageId: z.ZodString;
+    base: z.ZodObject<{
+        ref: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strict>;
+    acceptance: z.ZodOptional<z.ZodObject<{
+        fingerprint: z.ZodString;
+        verdict: z.ZodLiteral<"pass">;
+        network: z.ZodEnum<{
+            limited: "limited";
+            not_limited: "not_limited";
+        }>;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+    collected: z.ZodOptional<z.ZodObject<{
+        digest: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WriterState = Omit<z.infer<typeof writerStateSchema>, "launch"> & {
+    launch?: "legacy" | "relay";
+};
+export declare function writerName(alias: string, index: number): string;
+export declare function writerRegistrationName(name: string): string;
+export declare function writersRoot(home: string): string;
+export declare function writerPaths(home: string, name: string): {
+    root: string;
+    clone: string;
+    agent: string;
+    bundles: string;
+    config: string;
+    events: string;
+    go: string;
+    uv: string;
+    wrapper: string;
+    state: string;
+    acceptanceFailure: string;
+};
+export declare function readWriterState(home: string, name: string): Promise<WriterState | undefined>;
+export declare function writeWriterState(home: string, name: string, state: WriterState): Promise<void>;
+/**
+ * Whether the writer's own server configuration (the one mounted at /pi/config) enables event delivery.
+ * Anything unreadable or unexpected counts as disabled, so a doubtful configuration never adds the spool mount.
+ */
+export declare function writerEventDeliveryEnabled(configDirectory: string): Promise<boolean>;
+/**
+ * The writer's own configuration sits next to its wrapper (`<root>/config`), so acceptance, launch
+ * and Doctor all read event delivery from the same place. Delivery is part of the fingerprint only
+ * when it is enabled: an accepted writer without delivery keeps its fingerprint, and enabling
+ * delivery (a new spool mount in the boundary) needs a new acceptance.
+ */
+export declare function currentAcceptanceFingerprint(wrapper: string, state: WriterState, podmanVersion: string): Promise<string>;
+/**
+ * Doctor's `writer_not_ready` predicate, shared with setup: a ready phase alone survives a package
+ * upgrade or another changed binding, so setup accepts such a writer again (#130).
+ */
+export declare function writerAcceptanceCurrent(wrapper: string, state: WriterState, runtime: {
+    podmanVersion?: string;
+    imageExists: (id: string) => Promise<boolean>;
+}): Promise<boolean>;
+export declare function acceptanceFingerprint(input: {
+    wrapperDigest: string;
+    packageVersion: string;
+    imageId: string;
+    podmanVersion: string;
+    network: string;
+    cache: string;
+    /** Present only for an enabled delivery; an absent value must not change the canonical text of earlier fingerprints. */
+    eventDelivery?: boolean;
+}): string;

package/dist/writer-state.js

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from "node:crypto";
+import { wrapperDigest } from "./writer-wrapper.js";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { PACKAGE_VERSION } from "./package-metadata.js";
+import { ALIAS_PATTERN } from "./execution-profile.js";
+export const WRITER_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}-w([1-9]|1[0-6])$/;
+export class WriterStateError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "WriterStateError";
+    }
+}
+const aliasSchema = z.string().regex(ALIAS_PATTERN);
+const indexSchema = z.number().int().min(1).max(16);
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
+export const writerStateSchema = z.object({
+    schemaVersion: z.literal(1),
+    alias: aliasSchema,
+    index: indexSchema,
+    phase: z.enum(["provisioning", "ready", "not_ready"]),
+    lifecycle: z.enum(["persistent", "ephemeral"]),
+    launch: z.enum(["legacy", "relay"]).default("legacy"),
+    profiles: z.array(aliasSchema).min(1).readonly(),
+    providers: z.array(z.object({
+        provider: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        model: z.string().min(1).max(200),
+    }).strict()).refine((providers) => new Set(providers.map(({ provider }) => provider)).size === providers.length).readonly(),
+    network: z.enum(["pasta", "none"]),
+    cache: z.enum(["none", "go", "uv"]),
+    tags: z.enum(["none", "reachable"]).default("none"),
+    imageId: hex64,
+    base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/) }).strict(),
+    acceptance: z.object({
+        fingerprint: z.string(), verdict: z.literal("pass"), network: z.enum(["limited", "not_limited"]), at: z.string(),
+    }).strict().optional(),
+    collected: z.object({ digest: z.string(), at: z.string() }).strict().optional(),
+}).strict();
+export function writerName(alias, index) {
+    if (!aliasSchema.safeParse(alias).success || !indexSchema.safeParse(index).success) {
+        throw new WriterStateError("writer_state_invalid");
+    }
+    return `${alias}-w${index}`;
+}
+function validateName(name) {
+    if (!WRITER_NAME_PATTERN.test(name))
+        throw new WriterStateError("writer_state_invalid");
+}
+export function writerRegistrationName(name) {
+    validateName(name);
+    return `pi-coding-${name}`;
+}
+export function writersRoot(home) {
+    return join(home, ".local", "state", "pi-session-mcp", "writers");
+}
+export function writerPaths(home, name) {
+    validateName(name);
+    const root = join(writersRoot(home), name);
+    return {
+        root, clone: join(root, "clone"), agent: join(root, "agent"), bundles: join(root, "bundles"),
+        config: join(root, "config"), events: join(root, "events"), go: join(root, "go"), uv: join(root, "uv"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
+        acceptanceFailure: join(root, "acceptance-failure.json"),
+    };
+}
+function validateState(raw, name) {
+    const parsed = writerStateSchema.safeParse(raw);
+    if (!parsed.success || writerName(parsed.data.alias, parsed.data.index) !== name) {
+        throw new WriterStateError("writer_state_invalid");
+    }
+    return parsed.data;
+}
+export async function readWriterState(home, name) {
+    const path = writerPaths(home, name).state;
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new WriterStateError("writer_state_unreadable");
+    }
+    if (!stat.isFile())
+        throw new WriterStateError("writer_state_invalid");
+    try {
+        // Recheck the opened file and do not follow a symlink swapped in after lstat.
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            if (!(await handle.stat()).isFile())
+                throw new WriterStateError("writer_state_invalid");
+            return validateState(JSON.parse(await handle.readFile("utf8")), name);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof WriterStateError)
+            throw error;
+        if (error instanceof SyntaxError)
+            throw new WriterStateError("writer_state_invalid");
+        if (error instanceof Error && "code" in error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            if (error.code === "ELOOP")
+                throw new WriterStateError("writer_state_invalid");
+        }
+        throw new WriterStateError("writer_state_unreadable");
+    }
+}
+export async function writeWriterState(home, name, state) {
+    const paths = writerPaths(home, name);
+    const validated = validateState(state, name);
+    await mkdir(paths.root, { recursive: true, mode: 0o700 });
+    const temporary = join(paths.root, `.state-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        const handle = await open(temporary, "wx", 0o600);
+        created = true;
+        try {
+            await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, paths.state);
+        const directory = await open(paths.root, "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        if (created)
+            await unlink(temporary).catch((error) => {
+                if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                    throw error;
+            });
+    }
+}
+/**
+ * Whether the writer's own server configuration (the one mounted at /pi/config) enables event delivery.
+ * Anything unreadable or unexpected counts as disabled, so a doubtful configuration never adds the spool mount.
+ */
+export async function writerEventDeliveryEnabled(configDirectory) {
+    try {
+        const handle = await open(join(configDirectory, "pi-session-mcp.json"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            if (!(await handle.stat()).isFile())
+                return false;
+            const config = JSON.parse(await handle.readFile("utf8"));
+            if (config === null || typeof config !== "object" || Array.isArray(config))
+                return false;
+            const events = config.events;
+            return events !== null && typeof events === "object" && !Array.isArray(events)
+                && Object.keys(events).length === 1 && events.delivery === "spool";
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The writer's own configuration sits next to its wrapper (`<root>/config`), so acceptance, launch
+ * and Doctor all read event delivery from the same place. Delivery is part of the fingerprint only
+ * when it is enabled: an accepted writer without delivery keeps its fingerprint, and enabling
+ * delivery (a new spool mount in the boundary) needs a new acceptance.
+ */
+export async function currentAcceptanceFingerprint(wrapper, state, podmanVersion) {
+    const eventDelivery = await writerEventDeliveryEnabled(join(dirname(wrapper), "config"));
+    return acceptanceFingerprint({ wrapperDigest: wrapperDigest(await readFile(wrapper, "utf8")), packageVersion: PACKAGE_VERSION,
+        imageId: state.imageId, podmanVersion, network: state.network, cache: state.cache, ...(eventDelivery ? { eventDelivery } : {}) });
+}
+/**
+ * Doctor's `writer_not_ready` predicate, shared with setup: a ready phase alone survives a package
+ * upgrade or another changed binding, so setup accepts such a writer again (#130).
+ */
+export async function writerAcceptanceCurrent(wrapper, state, runtime) {
+    return state.phase === "ready" && !!state.acceptance && !!runtime.podmanVersion
+        && state.acceptance.fingerprint === await currentAcceptanceFingerprint(wrapper, state, runtime.podmanVersion)
+        && await runtime.imageExists(state.imageId);
+}
+export function acceptanceFingerprint(input) {
+    const canonical = JSON.stringify({
+        cache: input.cache, ...(input.eventDelivery ? { eventDelivery: true } : {}), imageId: input.imageId, network: input.network,
+        packageVersion: input.packageVersion, podmanVersion: input.podmanVersion, wrapperDigest: input.wrapperDigest,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}

package/dist/writer-wrapper.d.ts

@@ -0,0 +1,3 @@
+/** Pure wrapper rendering and hashing; safe to import from operator CLIs. */
+export declare function renderWrapper(nodePath: string, releaseRoot: string, name: string): string;
+export declare function wrapperDigest(text: string): string;