pi-session-mcp 0.13.0 → 0.13.1

package/dist/setup-writers-plan.d.ts

@@ -0,0 +1,34 @@
+import { type ContainerSettings, type WorkspaceModeEntry } from "./execution-modes.js";
+import type { ModeRequest } from "./setup-modes.js";
+import { type SetupOperation, type SetupResult } from "./setup-result.js";
+import type * as lifecycle from "./writer-lifecycle.js";
+import { type WriterPlan, type WriterSetupDependencies } from "./setup-writers-common.js";
+/** Base inference, the settings check and the plans a mode change shows or checks before it writes the modes file. */
+export type SettingsDrift = (name: string, ctx?: lifecycle.WriterContext) => Promise<lifecycle.WriterOutcome | undefined>;
+/** What a writer's configuration is rendered from: the raw configuration file and the skill override directory. */
+export interface RenderInputs {
+    readonly rawConfig: unknown;
+    readonly overrideDirectory: string;
+}
+export declare function renderInputs(configPath: string): Promise<RenderInputs>;
+/**
+ * The one settings check (#134, #163) of the pre-write gate, the dry run and reconciliation: whether a writer's
+ * provisioned settings or rendered configuration differ from `settings`. Reconcile passes its fenced context per writer.
+ */
+export declare function settingsDriftCheck(inputs: RenderInputs, ctx: lifecycle.WriterContext, settings: ContainerSettings, deps: WriterSetupDependencies): SettingsDrift;
+/**
+ * The request as the modes file should record it: `--base` as provisioning resolves it, so a refused or
+ * remote-tracking form never reaches the modes file; without `--base`, the one base the existing writers share, or
+ * for a first provisioning the base it will resolve (origin/HEAD, else main), so default starts find writers.
+ * Returns a refusal instead when the base cannot be resolved or existing writers disagree.
+ */
+export declare function inferBase(configPath: string, request: ModeRequest, deps: WriterSetupDependencies, containerRuntime: () => Promise<boolean>, failed: (code: string) => SetupResult): Promise<ModeRequest | SetupResult>;
+/**
+ * Apply only: the Doctor gate, a fence and the destructive-work refusal for each surplus writer, and the settings
+ * check of kept writers before the write, so a kept writer with changed settings refuses the mode change itself and
+ * the modes file never records a mode no writer matches (#163). Read-only like the dry run, which fences nothing;
+ * reconcile re-checks under its fence. Missing writers have no settings yet. Returns a refusal or `undefined`.
+ */
+export declare function gateBeforeWrite(configPath: string, ctx: lifecycle.WriterContext, entry: WorkspaceModeEntry, planned: WriterPlan, discard: boolean, operation: SetupOperation, deps: WriterSetupDependencies): Promise<SetupResult | undefined>;
+/** The dry run's writer plan: kept writers with the same settings check as apply (#134), then the surplus to remove. */
+export declare function plannedWriters(configPath: string, ctx: lifecycle.WriterContext, proposed: WorkspaceModeEntry, planned: WriterPlan, deps: WriterSetupDependencies): Promise<SetupResult>;

package/dist/setup-writers-plan.js

@@ -0,0 +1,105 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { loadConfig } from "./config.js";
+import { MAX_WRITERS } from "./execution-modes.js";
+import { result } from "./setup-result.js";
+import { skillOverrideDirectory } from "./skill-library.js";
+import { sameWriterLimits, writerLimits } from "./writer-limits.js";
+import { readWriterState, writerName } from "./writer-state.js";
+import { codeFor, context, doctorGate, FENCE_CODES, fenced, modesTarget, preflight, services, targetFor, writerIndex } from "./setup-writers-common.js";
+export async function renderInputs(configPath) {
+    return { rawConfig: JSON.parse(await readFile(configPath, "utf8")), overrideDirectory: skillOverrideDirectory(configPath) };
+}
+/**
+ * The one settings check (#134, #163) of the pre-write gate, the dry run and reconciliation: whether a writer's
+ * provisioned settings or rendered configuration differ from `settings`. Reconcile passes its fenced context per writer.
+ */
+export function settingsDriftCheck(inputs, ctx, settings, deps) {
+    const { life } = services(deps);
+    return (name, scoped = ctx) => life.writerSettingsDrift(scoped, { index: writerIndex(name), settings, ...inputs });
+}
+/**
+ * The request as the modes file should record it: `--base` as provisioning resolves it, so a refused or
+ * remote-tracking form never reaches the modes file; without `--base`, the one base the existing writers share, or
+ * for a first provisioning the base it will resolve (origin/HEAD, else main), so default starts find writers.
+ * Returns a refusal instead when the base cannot be resolved or existing writers disagree.
+ */
+export async function inferBase(configPath, request, deps, containerRuntime, failed) {
+    const operation = request.apply ? "apply" : "dry-run";
+    if (request.baseRef !== undefined) {
+        try {
+            return { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps), request.baseRef) };
+        }
+        catch (error) {
+            return failed(codeFor(error));
+        }
+    }
+    if (!(request.mode === "container" || request.mode === undefined && await containerRuntime()))
+        return request;
+    const config = await loadConfig(configPath);
+    if (config.workspaceModes.get(request.alias)?.container?.base)
+        return request;
+    const bases = new Set();
+    for (let index = 1; index <= MAX_WRITERS; 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)
+        return { ...request, baseRef: [...bases][0].replace(/^refs\/heads\//, "") };
+    if (request.mode !== "container")
+        return request;
+    try {
+        return { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps)) };
+    }
+    catch (error) {
+        return failed(codeFor(error));
+    }
+}
+/**
+ * Apply only: the Doctor gate, a fence and the destructive-work refusal for each surplus writer, and the settings
+ * check of kept writers before the write, so a kept writer with changed settings refuses the mode change itself and
+ * the modes file never records a mode no writer matches (#163). Read-only like the dry run, which fences nothing;
+ * reconcile re-checks under its fence. Missing writers have no settings yet. Returns a refusal or `undefined`.
+ */
+export async function gateBeforeWrite(configPath, ctx, entry, planned, discard, operation, deps) {
+    await doctorGate(ctx, deps);
+    for (const name of planned.surplus) {
+        try {
+            await fenced(ctx, name, deps, (leased) => preflight(leased, [name], discard, 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(ctx.alias, name), status: "failed", code: codeFor(error) }]);
+            throw error;
+        }
+    }
+    if (entry.mode !== "container")
+        return undefined;
+    const drift = settingsDriftCheck(await renderInputs(configPath), ctx, entry.container, deps);
+    const drifted = [];
+    for (const name of planned.keep) {
+        if (planned.missing.includes(name))
+            continue;
+        const outcome = await drift(name);
+        if (outcome)
+            drifted.push({ target: targetFor(ctx.alias, name), ...outcome });
+    }
+    return drifted.length ? result(operation, drifted) : undefined;
+}
+/** The dry run's writer plan: kept writers with the same settings check as apply (#134), then the surplus to remove. */
+export async function plannedWriters(configPath, ctx, proposed, planned, deps) {
+    const drift = settingsDriftCheck(await renderInputs(configPath), ctx, proposed.container, deps);
+    const kept = [];
+    for (const name of planned.keep) {
+        const outcome = await drift(name);
+        const state = await readWriterState(ctx.home, name);
+        const updatingLimits = state && state.phase !== "provisioning" && !sameWriterLimits(state.limits, writerLimits(proposed.container));
+        kept.push({ target: targetFor(ctx.alias, name), ...(outcome ?? { status: "planned", code: updatingLimits ? "writer_limits_update_planned" : "writer_planned" }) });
+    }
+    const refused = kept.some((finding) => finding.status === "failed" || finding.status === "divergent");
+    return result("dry-run", [...kept, ...planned.surplus.map((name) => ({ target: targetFor(ctx.alias, name), status: "planned", code: "writer_remove_planned" }))], refused ? "failed" : "planned");
+}

package/dist/setup-writers-reconcile.d.ts

@@ -0,0 +1,8 @@
+import { type SetupResult } from "./setup-result.js";
+import { type WriterSetupDependencies } from "./setup-writers-common.js";
+/** Writer reconciliation after a mode change is written: provisioning, migration to the relay launch, acceptance and removal. */
+export type ReconcileRequest = {
+    discard: boolean;
+    baseRef?: string;
+};
+export declare function reconcileUnlocked(configPath: string, alias: string, request: ReconcileRequest, deps: WriterSetupDependencies): Promise<SetupResult>;

package/dist/setup-writers-reconcile.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { result } from "./setup-result.js";
+import { unregisterWriter } from "./client-adapters/writer-registration.js";
+import { sameWriterLimits, writerLimits } from "./writer-limits.js";
+import { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
+import { readWriterState, writeWriterState, writerPaths } from "./writer-state.js";
+import { codeFor, context, doctorGate, FENCE_CODES, fenced, INFRASTRUCTURE_CODE, intent, plan, preflight, remove, services, targetFor, writerHook, writerIndex } from "./setup-writers-common.js";
+import { renderInputs, settingsDriftCheck } from "./setup-writers-plan.js";
+/**
+ * Moves a kept writer to the relay launch: its owned registrations are removed (both clients are decided before
+ * anything is removed, 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), and so is its wake hook; the wrapper is rebound to this
+ * release. A changed launch or wrapper leaves the writer unaccepted. Returns a refusal outcome or `undefined`.
+ */
+async function migrateToRelay(ctx, name, deps, findings) {
+    const { ownership, adapter } = services(deps);
+    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(ctx.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" });
+        return { status: "failed", code: "registration_divergent" };
+    }
+    const paths = writerPaths(ctx.home, name), wrapper = renderWrapper(ctx.nodePath, ctx.releaseRoot, name);
+    if (!(await lstat(paths.wrapper).catch(() => undefined))?.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.
+    if (state.launch !== "relay" || wrapperChanged) {
+        const { acceptance: _oldAcceptance, ...unaccepted } = state;
+        await writeWriterState(ctx.home, name, { ...unaccepted, launch: "relay", phase: "not_ready" });
+    }
+    return undefined;
+}
+export async function reconcileUnlocked(configPath, alias, request, deps) {
+    const findings = [];
+    const ctx = await context(alias, { ...deps, configPath });
+    const config = await loadConfig(configPath), entry = config.workspaceModes.get(alias);
+    const planned = await plan(ctx, entry), { life, accept } = services(deps);
+    const add = (name, outcome) => { findings.push({ target: targetFor(alias, name), ...outcome }); };
+    await doctorGate(ctx, deps);
+    // 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));
+        }
+        catch (error) {
+            if (!FENCE_CODES.includes(codeFor(error)))
+                throw error;
+            unfenced.add(name);
+            add(name, { status: "failed", code: codeFor(error) });
+        }
+    }
+    const inputs = await renderInputs(configPath), drift = settingsDriftCheck(inputs, ctx, entry.container, deps);
+    // Each writer's reconciliation, including first provisioning and acceptance, owns one fence.
+    // A writer added without --base joins the recorded default base, so default starts find it. A recorded base that is
+    // the repository default stays unset: provisioning then resolves origin/HEAD, as the first provisioning did.
+    let baseRef = request.baseRef;
+    const recordedBase = entry.container?.base;
+    if (baseRef === undefined && recordedBase !== undefined && recordedBase !== await life.baseBranchName(ctx).catch(() => undefined))
+        baseRef = recordedBase;
+    for (const name of planned.keep) {
+        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, ...inputs, ...(baseRef ? { 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 drifted = await drift(name, ctx);
+                    if (drifted) {
+                        add(name, drifted);
+                        return;
+                    }
+                    const state = await readWriterState(ctx.home, name);
+                    if (!state)
+                        throw new Error("writer_state_invalid");
+                    const limits = writerLimits(entry.container);
+                    if (!sameWriterLimits(state.limits, limits)) {
+                        const { limits: _previous, ...rest } = state;
+                        await writeWriterState(ctx.home, name, { ...rest, ...(limits ? { limits } : {}) });
+                        add(name, { status: "ok", code: "writer_limits_updated" });
+                    }
+                }
+                const refused = await migrateToRelay(ctx, name, deps, findings);
+                if (refused) {
+                    add(name, refused);
+                    return;
+                }
+                // 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) {
+            // A broken writer is reported on its own target and the others are still reconciled.
+            if (INFRASTRUCTURE_CODE.test(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 fenced(ctx, name, deps, (leased) => remove(leased, name, request.discard, deps, extras)));
+        }
+        catch (error) {
+            add(name, { status: "failed", code: codeFor(error) });
+        }
+        for (const extra of extras)
+            findings.push({ target: targetFor(alias, name), ...extra });
+    }
+    return result("apply", findings);
+}

package/dist/setup-writers.d.ts

@@ -1,41 +1,17 @@
-import { runDoctor } from "./doctor.js";
 import { type ModeRequest } from "./setup-modes.js";
-import { acquireOverrideLock } from "./override-lock.js";
-import { createCommandMcpStdioLauncher } from "./setup-process.js";
-import { type OwnershipStore } from "./setup-ownership.js";
 import { type SetupResult } from "./setup-result.js";
-import { type WriterRegistrationAdapter } from "./client-adapters/writer-registration.js";
-import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
-import { acquireWriterLease } from "./writer-lease.js";
-import { ensureWriterAbsent } from "./writer-fence.js";
-import * as lifecycle from "./writer-lifecycle.js";
-import * as acceptance from "./writer-acceptance.js";
-export declare const SETUP_LEASE_WAIT_MS = 10000;
+import { type WriterSetupDependencies } from "./setup-writers-common.js";
+/**
+ * Writer setup entry points: a repository's mode change with its writers (planning and base inference in
+ * `setup-writers-plan.ts`, reconciliation in `setup-writers-reconcile.ts`), single-writer operations and the isolation control.
+ */
+export { SETUP_LEASE_WAIT_MS, type WriterSetupDependencies } from "./setup-writers-common.js";
 export type WriterOperation = "collect" | "reset" | "recreate" | "finish" | "remove" | "verify";
 export interface WriterOptions {
     apply: boolean;
     discard: boolean;
     baseRef?: string;
 }
-export interface WriterSetupDependencies {
-    configPath: string;
-    releaseRoot: string;
-    home?: string;
-    platform?: NodeJS.Platform;
-    signal?: AbortSignal;
-    runner?: lifecycle.WriterContext["runner"];
-    lifecycle?: typeof lifecycle;
-    acceptance?: typeof acceptance;
-    ownership?: OwnershipStore;
-    adapter?: WriterRegistrationAdapter;
-    doctor?: typeof runDoctor;
-    verify?: typeof verifyMcpCapabilities;
-    launch?: typeof createCommandMcpStdioLauncher;
-    lock?: typeof acquireOverrideLock;
-    lease?: typeof acquireWriterLease;
-    ensureAbsent?: typeof ensureWriterAbsent;
-    containerRuntime?: () => Promise<boolean>;
-}
 /** Serializes planning, destructive-work refusal, mode commit and writer reconciliation. */
 export declare function changeWriterMode(configPath: string, request: ModeRequest, deps: WriterSetupDependencies): Promise<SetupResult>;
 export declare function runWriterOperation(name: string, operation: WriterOperation, opts: WriterOptions, deps: WriterSetupDependencies): Promise<SetupResult>;