pi-session-mcp 0.11.9 → 0.12.0

package/dist/setup-writers.js

@@ -1,4 +1,5 @@
-import { chmod, lstat, mkdir, readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
@@ -11,17 +12,22 @@ import { createCommandMcpStdioLauncher, createProcessRunner } from "./setup-proc
 import { DurableOwnershipStore } from "./setup-ownership.js";
 import { localHookNeededByOthers, ownsWakeHook, runWakeHook } from "./setup-hooks.js";
 import { result } from "./setup-result.js";
-import { createWriterRegistrationAdapter, registerWriter, unregisterWriter } from "./client-adapters/writer-registration.js";
+import { createWriterRegistrationAdapter, unregisterWriter } from "./client-adapters/writer-registration.js";
 import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
 import { IMAGE_PULL_TIMEOUT_MS } from "./writer-boundary.js";
+import { acquireWriterLease, WriterLeaseError } from "./writer-lease.js";
+import { ensureWriterAbsent } from "./writer-fence.js";
 import * as lifecycle from "./writer-lifecycle.js";
 import * as acceptance from "./writer-acceptance.js";
 import { skillOverrideDirectory } from "./skill-library.js";
-import { readWriterState, writerEventDeliveryEnabled, writerName, writerPaths, writerRegistrationName, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
+import { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
+import { readWriterState, writeWriterState, writerName, writerPaths, writerRegistrationName, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
+export const SETUP_LEASE_WAIT_MS = 10_000;
+const FENCE_CODES = ["writer_busy", "writer_fenced", "writer_lease_unavailable"];
 const safeAlias = (alias) => ALIAS_PATTERN.test(alias) ? alias : "invalid";
 const targetFor = (alias, name) => ({ client: "writer", scope: safeAlias(alias), alias: WRITER_NAME_PATTERN.test(name) || (alias === "host" && name === "control") ? name : "invalid" });
 const modesTarget = (alias) => ({ client: "modes", scope: "workspace", alias: safeAlias(alias) });
-const codeFor = (error) => error instanceof OverrideLockError ? error.code : error instanceof Error && /^[a-z][a-z0-9_]{0,63}$/.test(error.message) ? error.message : "writer_operation_failed";
+const codeFor = (error) => error instanceof OverrideLockError || error instanceof WriterLeaseError ? error.code : error instanceof Error && /^[a-z][a-z0-9_]{0,63}$/.test(error.message) ? error.message : "writer_operation_failed";
 function services(deps) {
     const home = deps.home ?? homedir();
     const runner = deps.runner ?? createProcessRunner({ timeoutMs: IMAGE_PULL_TIMEOUT_MS, maxOutputBytes: 1_048_576, ...(deps.signal ? { signal: deps.signal } : {}) });
@@ -49,6 +55,27 @@ async function locked(deps, action) {
         await lock.release();
     }
 }
+async function fenced(ctx, name, deps, action) {
+    let lease;
+    try {
+        lease = await (deps.lease ?? acquireWriterLease)(ctx.home, name, { waitMs: SETUP_LEASE_WAIT_MS, ...(deps.signal ? { signal: deps.signal } : {}) });
+    }
+    catch (error) {
+        throw new Error(error instanceof WriterLeaseError && error.code === "writer_busy" ? "writer_busy" : "writer_lease_unavailable");
+    }
+    try {
+        try {
+            await (deps.ensureAbsent ?? ensureWriterAbsent)(ctx.runner, writerPaths(ctx.home, name), name, { leaseFd: lease.fd });
+        }
+        catch {
+            throw new Error("writer_fenced");
+        }
+        return await action({ ...ctx, leaseFd: lease.fd });
+    }
+    finally {
+        await lease.release();
+    }
+}
 function intent(ctx, name, client) {
     return { client, name: writerRegistrationName(name), wrapperPath: writerPaths(ctx.home, name).wrapper, projectDir: ctx.checkout };
 }
@@ -72,10 +99,6 @@ async function writerHook(ctx, name, deps, operation, enabled) {
     const outcome = operation === "apply" || operation === "remove" ? await ownership.transaction((access) => request(access, operation)) : await request(ownership, operation);
     return outcome.code === "hook_not_enabled" || outcome.code === "hook_not_owned" ? undefined : outcome;
 }
-/** Whether a provisioned writer's own configuration enables delivery; before provisioning the host configuration decides, as provisioning copies it. */
-async function writerDelivery(ctx, name, hostDelivery) {
-    return await readWriterState(ctx.home, name) ? writerEventDeliveryEnabled(writerPaths(ctx.home, name).config) : hostDelivery;
-}
 class DoctorGateError extends Error {
     findings;
     constructor(findings) {
@@ -154,62 +177,121 @@ async function reconcileUnlocked(configPath, alias, request, deps) {
     const planned = await plan(ctx, entry), { life, accept, ownership, adapter } = services(deps);
     const add = (name, outcome) => { findings.push({ target: targetFor(alias, name), ...outcome }); };
     await doctorGate(ctx, deps);
-    await preflight(ctx, planned.surplus, request.discard, deps);
-    const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
-    const failedProvision = new Set();
-    for (const name of planned.missing) {
-        const outcome = await life.provisionWriter(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory, ...(request.baseRef ? { baseRef: request.baseRef } : {}) });
-        add(name, outcome);
-        if (outcome.status === "failed")
-            failedProvision.add(name);
-    }
-    // Writers left exactly as they are: neither accepted nor registered in this run.
-    const held = new Set();
-    for (const name of planned.keep) {
-        if (failedProvision.has(name))
-            continue;
-        if (!planned.missing.includes(name)) {
-            // Settings first: a writer that no longer matches its configuration is not accepted or registered again (#134).
-            const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory });
-            if (drift) {
-                held.add(name);
-                add(name, drift);
-                continue;
-            }
+    // A surplus writer that cannot be fenced is reported on its own target and left in place; the others proceed.
+    const unfenced = new Set();
+    for (const name of planned.surplus) {
+        try {
+            await fenced(ctx, name, deps, (leased) => preflight(leased, [name], request.discard, deps));
         }
-        // A ready phase with a stale binding (package upgrade, new image, Podman version) is accepted again (#130).
-        const current = await accept.acceptanceCurrent(ctx, name);
-        if (current === "stale")
-            add(name, await accept.acceptWriter(ctx, name));
-        else if (current === "unknown") {
-            held.add(name);
-            add(name, { status: "failed", code: "podman_unavailable" });
+        catch (error) {
+            if (!FENCE_CODES.includes(codeFor(error)))
+                throw error;
+            unfenced.add(name);
+            add(name, { status: "failed", code: codeFor(error) });
         }
     }
+    const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
+    // Each writer's reconciliation, including first provisioning and acceptance, owns one fence.
     for (const name of planned.keep) {
-        if (failedProvision.has(name) || held.has(name) || (await readWriterState(ctx.home, name))?.phase !== "ready")
-            continue;
-        for (const client of request.codex ? ["claude-code", "codex"] : ["claude-code"]) {
-            const expected = intent(ctx, name, client), before = await adapter.inspect(expected);
-            try {
-                await registerWriter(ownership, adapter, expected);
-                add(name, { status: before === "equivalent" ? "unchanged" : "ok", code: "writer_registered" });
-            }
-            catch (error) {
-                add(name, { status: "failed", code: codeFor(error) });
-                continue;
-            }
-            if (client === "claude-code") {
-                const hook = await writerHook(ctx, name, deps, "apply", await writerEventDeliveryEnabled(writerPaths(ctx.home, name).config));
+        try {
+            await fenced(ctx, name, deps, async (ctx) => {
+                if (planned.missing.includes(name)) {
+                    const outcome = await life.provisionWriter(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory, ...(request.baseRef ? { baseRef: request.baseRef } : {}) });
+                    add(name, outcome);
+                    if (outcome.status === "failed")
+                        return;
+                }
+                // Settings first: a drifted writer is left exactly as it is, neither migrated nor accepted again (#134).
+                if (!planned.missing.includes(name)) {
+                    const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory });
+                    if (drift) {
+                        add(name, drift);
+                        return;
+                    }
+                }
+                // Decide for both clients before removing anything, so a divergent registration of one client never
+                // costs the writer its owned registration of the other. A client that is not installed has nothing to keep.
+                let divergent = false;
+                const owned = [];
+                for (const client of ["claude-code", "codex"]) {
+                    const expected = intent(ctx, name, client);
+                    const record = await ownership.get({ client, scope: client === "codex" ? "user" : "local", alias: expected.name });
+                    const current = await adapter.inspect(expected);
+                    if (record ? current === "divergent" : current === "equivalent" || current === "divergent")
+                        divergent = true;
+                    else if (record)
+                        owned.push(expected);
+                }
+                if (!divergent) {
+                    for (const expected of owned) {
+                        try {
+                            await unregisterWriter(ownership, adapter, expected);
+                        }
+                        catch (error) {
+                            if (codeFor(error) !== "ownership_diverged")
+                                throw error;
+                            divergent = true;
+                        }
+                    }
+                }
+                const hook = await writerHook(ctx, name, deps, "remove", false);
                 if (hook)
                     findings.push({ target: targetFor(alias, name), ...hook });
-            }
+                const state = await readWriterState(ctx.home, name);
+                if (!state)
+                    throw new Error("writer_state_invalid");
+                if (divergent) {
+                    if (state.launch !== "legacy")
+                        await writeWriterState(ctx.home, name, { ...state, launch: "legacy" });
+                    add(name, { status: "failed", code: "registration_divergent" });
+                    return;
+                }
+                const paths = writerPaths(ctx.home, name), wrapper = renderWrapper(ctx.nodePath, ctx.releaseRoot, name);
+                if (!(await lstat(paths.wrapper)).isFile())
+                    throw new Error("writer_state_invalid");
+                const wrapperChanged = wrapperDigest(await readFile(paths.wrapper, "utf8")) !== wrapperDigest(wrapper);
+                if (wrapperChanged) {
+                    const temporary = join(paths.root, `.wrapper-${randomUUID()}.tmp`);
+                    try {
+                        await writeFile(temporary, wrapper, { flag: "wx", mode: 0o700 });
+                        await rename(temporary, paths.wrapper);
+                    }
+                    finally {
+                        await rm(temporary, { force: true });
+                    }
+                }
+                // A launch change also needs fresh provider-free acceptance, even when wrapper bytes match.
+                const migrated = state.launch !== "relay";
+                if (migrated || wrapperChanged) {
+                    const { acceptance: _oldAcceptance, ...unaccepted } = state;
+                    await writeWriterState(ctx.home, name, { ...unaccepted, launch: "relay", phase: "not_ready" });
+                }
+                // A ready phase with a stale binding (package upgrade, new image, Podman version) is accepted again (#130).
+                const current = await accept.acceptanceCurrent(ctx, name);
+                if (current === "stale") {
+                    const outcome = await accept.acceptWriter(ctx, name);
+                    add(name, outcome);
+                    if (outcome.status === "failed")
+                        return;
+                }
+                else if (current === "unknown") {
+                    add(name, { status: "failed", code: "podman_unavailable" });
+                    return;
+                }
+            });
+        }
+        catch (error) {
+            if (!FENCE_CODES.includes(codeFor(error)))
+                throw error;
+            add(name, { status: "failed", code: codeFor(error) });
         }
     }
     for (const name of planned.surplus) {
+        if (unfenced.has(name))
+            continue;
         const extras = [];
         try {
-            add(name, await remove(ctx, name, request.discard, deps, extras));
+            add(name, await fenced(ctx, name, deps, (leased) => remove(leased, name, request.discard, deps, extras)));
         }
         catch (error) {
             add(name, { status: "failed", code: codeFor(error) });
@@ -263,15 +345,62 @@ export async function changeWriterMode(configPath, request, deps) {
     }
     const action = async () => {
         let proposed;
-        return changeExecutionMode(configPath, request, {
+        // Record the base as provisioning resolves it, so a refused or remote-tracking form never reaches the modes file.
+        let recorded = request;
+        if (request.baseRef !== undefined) {
+            try {
+                recorded = { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps), request.baseRef) };
+            }
+            catch (error) {
+                return failed(codeFor(error));
+            }
+        }
+        else if (request.mode === "container" || request.mode === undefined && await containerRuntime()) {
+            const config = await loadConfig(configPath);
+            if (!config.workspaceModes.get(request.alias)?.container?.base) {
+                const bases = new Set();
+                for (let index = 1; index <= 16; index++) {
+                    const state = await readWriterState(deps.home ?? homedir(), writerName(request.alias, index));
+                    if (state)
+                        bases.add(state.base.ref);
+                }
+                if (bases.size > 1)
+                    return result(operation, [{ target: modesTarget(request.alias), status: "failed", code: "workspace_base_ambiguous" }]);
+                if (bases.size === 1)
+                    recorded = { ...request, baseRef: [...bases][0].replace(/^refs\/heads\//, "") };
+                // First provisioning: record the base it will resolve (origin/HEAD, else main), so default starts find writers.
+                else if (request.mode === "container") {
+                    try {
+                        recorded = { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps)) };
+                    }
+                    catch (error) {
+                        return failed(codeFor(error));
+                    }
+                }
+            }
+        }
+        return changeExecutionMode(configPath, recorded, {
             ...modeDependencies,
             beforeWrite: async (entry) => {
                 proposed = entry;
                 const ctx = await context(request.alias, deps), planned = await plan(ctx, entry);
                 try {
-                    if (request.apply)
+                    if (request.apply) {
                         await doctorGate(ctx, deps);
-                    await preflight(ctx, planned.surplus, request.discard ?? false, deps);
+                        for (const name of planned.surplus) {
+                            try {
+                                await fenced(ctx, name, deps, (leased) => preflight(leased, [name], request.discard ?? false, deps));
+                            }
+                            catch (error) {
+                                // Refuse the mode change, but name the writer that could not be fenced.
+                                if (FENCE_CODES.includes(codeFor(error)))
+                                    return result(operation, [{ target: targetFor(request.alias, name), status: "failed", code: codeFor(error) }]);
+                                throw error;
+                            }
+                        }
+                    }
+                    else
+                        await preflight(ctx, planned.surplus, request.discard ?? false, deps);
                 }
                 catch (error) {
                     return error instanceof DoctorGateError ? result(operation, [...failed(error.message).findings, ...error.findings]) : failed(codeFor(error));
@@ -282,32 +411,22 @@ export async function changeWriterMode(configPath, request, deps) {
                 let writers;
                 try {
                     if (request.apply)
-                        writers = await reconcileUnlocked(configPath, request.alias, { discard: request.discard ?? false, codex: request.codex ?? false, ...(request.baseRef ? { baseRef: request.baseRef } : {}) }, deps);
+                        writers = await reconcileUnlocked(configPath, request.alias, { discard: request.discard ?? false, ...(request.baseRef ? { baseRef: request.baseRef } : {}) }, deps);
                     else {
                         const ctx = await context(request.alias, deps), planned = await plan(ctx, proposed), { life } = services(deps);
-                        const hostDelivery = (await loadConfig(configPath)).eventDelivery === "spool", hooks = [], kept = [];
+                        const kept = [];
                         const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
                         for (const name of planned.keep) {
                             // The same settings check as apply, so a drifted writer shows before anything is applied (#134).
                             const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: proposed.container, rawConfig, overrideDirectory });
                             kept.push({ target: targetFor(request.alias, name), ...(drift ?? { status: "planned", code: "writer_planned" }) });
                         }
-                        for (const name of planned.keep) {
-                            const hook = await writerHook(ctx, name, deps, "dry-run", await writerDelivery(ctx, name, hostDelivery));
-                            if (hook)
-                                hooks.push({ target: targetFor(request.alias, name), ...hook });
-                        }
-                        for (const name of planned.surplus) {
-                            const hook = await writerHook(ctx, name, deps, "dry-run", false);
-                            if (hook)
-                                hooks.push({ target: targetFor(request.alias, name), ...hook });
-                        }
-                        const refused = [...kept, ...hooks].some((finding) => finding.status === "failed" || finding.status === "divergent");
-                        writers = result("dry-run", [...kept, ...planned.surplus.map((name) => ({ target: targetFor(request.alias, name), status: "planned", code: "writer_remove_planned" })), ...hooks], refused ? "failed" : "planned");
+                        const refused = kept.some((finding) => finding.status === "failed" || finding.status === "divergent");
+                        writers = result("dry-run", [...kept, ...planned.surplus.map((name) => ({ target: targetFor(request.alias, name), status: "planned", code: "writer_remove_planned" }))], refused ? "failed" : "planned");
                     }
                 }
                 catch (error) {
-                    writers = error instanceof DoctorGateError ? result(operation, [...failed(error.message).findings, ...error.findings]) : failed("writer_reconcile_failed");
+                    writers = error instanceof DoctorGateError ? result(operation, [...failed(error.message).findings, ...error.findings]) : failed(FENCE_CODES.includes(codeFor(error)) ? codeFor(error) : "writer_reconcile_failed");
                 }
                 const findings = [...modes.findings, ...writers.findings].filter((f) => f.code !== "controllers_restart_required");
                 if (request.apply && findings.some((f) => f.status === "ok"))
@@ -329,12 +448,9 @@ export async function runWriterOperation(name, operation, opts, deps) {
     if (!WRITER_NAME_PATTERN.test(name))
         return result(reportOperation, [{ target: { client: "invalid", scope: "invalid", alias: "invalid" }, status: "failed", code: "usage_invalid" }], "failed", 64);
     const alias = name.slice(0, name.lastIndexOf("-w")), target = targetFor(alias, name);
-    // A reset, recreate or finish clears the writer's projected credentials; its running server keeps stale ones until reconnected (#136).
-    const reconnectRequired = (outcome) => opts.apply && outcome.status === "ok" && (operation === "reset" || operation === "recreate" || operation === "finish");
     const done = (outcome, hooks = []) => result(reportOperation, [
         { target, ...outcome },
         ...hooks.map((hook) => ({ target, ...hook })),
-        ...(reconnectRequired(outcome) ? [{ target, status: "ok", code: "writer_reconnect_required" }] : []),
     ], outcome.status === "planned" ? "planned" : undefined);
     if ((deps.platform ?? process.platform) !== "linux")
         return done({ status: "failed", code: "platform_unsupported" });
@@ -343,27 +459,16 @@ export async function runWriterOperation(name, operation, opts, deps) {
             await context(alias, deps);
             return done({ status: "planned", code: `writer_${operation}_planned` });
         }
-        return await locked(deps, async () => {
-            const ctx = await context(alias, deps), { life, ownership, adapter } = services(deps);
+        return await locked(deps, async () => fenced(await context(alias, deps), name, deps, async (ctx) => {
+            const { life } = services(deps);
             if (operation === "verify") {
                 const doctor = await (deps.doctor ?? runDoctor)({ home: ctx.home, packageRoot: deps.releaseRoot, configPath: deps.configPath, loadConfig: () => loadConfig(deps.configPath) });
                 if (doctor.checks.some((check) => check.severity === "error" && (check.subject === name || GLOBAL_ERRORS.has(check.id))))
                     return done({ status: "failed", code: "doctor_failed" });
-                for (const client of ["claude-code", "codex"]) {
-                    const expected = intent(ctx, name, client);
-                    const owned = await ownership.get({ client, scope: client === "codex" ? "user" : "local", alias: expected.name });
-                    const current = await adapter.inspect(expected);
-                    if ((client === "claude-code" || owned || current !== "absent") && current !== "equivalent")
-                        return done({ status: "failed", code: "registration_not_equivalent" });
-                }
-                const checked = await (deps.verify ?? verifyMcpCapabilities)({ launch: (deps.launch ?? createCommandMcpStdioLauncher)([writerPaths(ctx.home, name).wrapper], { HOME: ctx.home, PATH: process.env.PATH ?? "", PI_WRITER_NO_CREDENTIAL_REFRESH: "1", ...(process.env.XDG_RUNTIME_DIR === undefined ? {} : { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR }) }) });
+                const checked = await (deps.verify ?? verifyMcpCapabilities)({ launch: (deps.launch ?? createCommandMcpStdioLauncher)([writerPaths(ctx.home, name).wrapper], { HOME: ctx.home, PATH: process.env.PATH ?? "", PI_WRITER_NO_CREDENTIAL_REFRESH: "1", PI_WRITER_LEASE_FD: "3", ...(process.env.XDG_RUNTIME_DIR === undefined ? {} : { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR }) }, { inheritFds: [ctx.leaseFd] }) });
                 if (checked.status !== "verified")
                     return done({ status: "failed", code: `mcp_${checked.status}` });
-                // The hook is part of the Claude Code registration: verified after it, from the writer's own configuration.
-                const hook = await writerHook(ctx, name, deps, "verify", await writerEventDeliveryEnabled(writerPaths(ctx.home, name).config));
-                if (hook?.status === "failed" || hook?.status === "divergent")
-                    return done({ status: "failed", code: hook.code });
-                return done({ status: "ok", code: "mcp_verified" }, hook ? [hook] : []);
+                return done({ status: "ok", code: "mcp_verified" });
             }
             try {
                 await doctorGate(ctx, deps);
@@ -373,14 +478,17 @@ export async function runWriterOperation(name, operation, opts, deps) {
                     return result(reportOperation, [...done({ status: "failed", code: error.message }).findings, ...error.findings]);
                 throw error;
             }
+            const entry = (await loadConfig(deps.configPath)).workspaceModes.get(alias);
+            const baseRef = opts.baseRef ?? entry?.container?.base;
+            const baseOptions = baseRef === undefined ? {} : { baseRef };
             const extras = [];
             const outcome = operation === "remove" ? await remove(ctx, name, opts.discard, deps, extras)
                 : operation === "collect" ? await life.collectWriter(ctx, name)
                     : operation === "reset" ? await life.resetWriter(ctx, name, opts)
-                        : operation === "recreate" ? await life.recreateWriter(ctx, name, opts)
-                            : await life.finishWriter(ctx, name);
+                        : operation === "recreate" ? await life.recreateWriter(ctx, name, { ...opts, ...baseOptions })
+                            : await life.finishWriter(ctx, name, baseOptions);
             return done(outcome, extras);
-        });
+        }));
     }
     catch (error) {
         return done({ status: "failed", code: codeFor(error) });