pi-session-mcp 0.13.0 → 0.14.0

package/dist/setup-writers-common.js

@@ -0,0 +1,177 @@
+import { chmod, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { ALIAS_PATTERN } from "./execution-profile.js";
+import { runDoctor } from "./doctor.js";
+import { MAX_WRITERS } from "./execution-modes.js";
+import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
+import { createProcessRunner } from "./setup-process.js";
+import { DurableOwnershipStore } from "./setup-ownership.js";
+import { localHookNeededByOthers, ownsWakeHook, runWakeHook } from "./setup-hooks.js";
+import { createWriterRegistrationAdapter, unregisterWriter } from "./client-adapters/writer-registration.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 { readWriterState, writerName, writerPaths, writerRegistrationName, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
+/** Services, fencing, the Doctor gate and removal shared by mode changes, reconciliation and single-writer operations. */
+export const SETUP_LEASE_WAIT_MS = 10_000;
+export const FENCE_CODES = ["writer_busy", "writer_fenced", "writer_lease_unavailable"];
+/**
+ * Failures of shared setup state rather than of one writer: they end the whole reconciliation (#180). The ownership
+ * store's own failures count; `ownership_unavailable` and `ownership_diverged` concern one writer's registration.
+ */
+export const INFRASTRUCTURE_CODE = /^(?:ownership_(?!unavailable$|diverged$)[a-z_]+|config_[a-z_]+|operation_aborted|platform_unsupported)$/;
+export const GLOBAL_ERRORS = new Set(["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "skill_controller_selected"]);
+const safeAlias = (alias) => ALIAS_PATTERN.test(alias) ? alias : "invalid";
+export const targetFor = (alias, name) => ({ client: "writer", scope: safeAlias(alias), alias: WRITER_NAME_PATTERN.test(name) || (alias === "host" && name === "control") ? name : "invalid" });
+export const modesTarget = (alias) => ({ client: "modes", scope: "workspace", alias: safeAlias(alias) });
+export 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";
+export 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 } : {}) });
+    return { home, runner, life: deps.lifecycle ?? lifecycle, accept: deps.acceptance ?? acceptance,
+        ownership: deps.ownership ?? new DurableOwnershipStore(join(home, ".local", "state", "pi-session-mcp", "ownership.json"), { ...(deps.signal ? { signal: deps.signal } : {}) }),
+        adapter: deps.adapter ?? createWriterRegistrationAdapter(runner) };
+}
+export async function context(alias, deps) {
+    const config = await loadConfig(deps.configPath);
+    const checkout = config.workspaces.get(alias);
+    if (!checkout)
+        throw new Error("alias_unknown");
+    const { home, runner } = services(deps);
+    return { home, runner, checkout, alias, releaseRoot: deps.releaseRoot, nodePath: process.execPath };
+}
+export async function locked(deps, action) {
+    const directory = writersRoot(deps.home ?? homedir());
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const lock = await (deps.lock ?? acquireOverrideLock)(directory, { ...(deps.signal ? { signal: deps.signal } : {}) });
+    try {
+        return await action();
+    }
+    finally {
+        await lock.release();
+    }
+}
+export 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();
+    }
+}
+export function intent(ctx, name, client) {
+    return { client, name: writerRegistrationName(name), wrapperPath: writerPaths(ctx.home, name).wrapper, projectDir: ctx.checkout };
+}
+/**
+ * The wake hook of a writer's Claude Code registration, in the local settings of the operator's
+ * project. Claude Code only: a Codex writer has no hook. The writer's own configuration decides
+ * whether delivery is wanted; the entry is shared per project, see `localHookNeededByOthers`.
+ * Findings without news (`hook_not_enabled`, `hook_not_owned`) are not reported.
+ */
+export async function writerHook(ctx, name, deps, operation, enabled) {
+    const { ownership } = services(deps);
+    const roots = { packageRoot: deps.releaseRoot, home: ctx.home, cwd: ctx.checkout, env: process.env, nodePath: ctx.nodePath };
+    // Nothing wanted and nothing owned: not even the project's settings are looked at.
+    if (!enabled && !await ownsWakeHook("local", roots, ownership))
+        return undefined;
+    const request = (access, op) => runWakeHook({
+        operation: op, scope: "local", enabled, ownership: access,
+        roots,
+        keep: () => localHookNeededByOthers({ ownership: access, home: ctx.home, cwd: ctx.checkout, configPath: deps.configPath, except: { writer: name } }),
+    });
+    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;
+}
+export class DoctorGateError extends Error {
+    findings;
+    constructor(findings) {
+        super("doctor_failed");
+        this.findings = findings;
+    }
+}
+export async function doctorGate(ctx, deps) {
+    const doctor = await (deps.doctor ?? runDoctor)({ home: ctx.home, packageRoot: deps.releaseRoot, configPath: deps.configPath, loadConfig: () => loadConfig(deps.configPath) });
+    const ownSubjects = new Set([ctx.alias, ...Array.from({ length: 16 }, (_, index) => writerName(ctx.alias, index + 1))]);
+    // A refused profile of this repository is its own finding: collect, finish and the profile change that fixes it must stay possible (#141).
+    // Another repository's writer that is not ready is untouched by this step and expected after an upgrade; counting it would deadlock
+    // the repository steps of two container repositories (#148).
+    const own = (check) => ownSubjects.has(check.subject)
+        || (check.id === "container_profile_refused" && check.subject.startsWith(`${ctx.alias}:`))
+        || (check.id === "writer_not_ready" && WRITER_NAME_PATTERN.test(check.subject));
+    const blocking = doctor.checks.filter((check) => check.severity === "error" && !own(check));
+    // One finding per check and alias: several `config_invalid` locations (#173) all map to the alias `invalid`.
+    const findings = blocking.map((check) => ({ status: "failed", code: check.id, target: { client: "doctor", scope: "check", alias: gateAlias(check.id, check.subject) } }));
+    const unique = findings.filter((finding, index) => findings.findIndex((other) => other.code === finding.code && other.target.alias === finding.target.alias) === index);
+    if (unique.length)
+        throw new DoctorGateError(unique);
+}
+/** The alias that leads a Doctor subject: `<profile>:<package>` and writer names report their alias part; global checks have none. */
+function gateAlias(id, subject) {
+    if (GLOBAL_ERRORS.has(id))
+        return "invalid";
+    const head = subject.split(":")[0] ?? "";
+    return safeAlias(WRITER_NAME_PATTERN.test(head) ? head.slice(0, head.lastIndexOf("-w")) : head);
+}
+export async function preflight(ctx, names, discard, deps) {
+    if (discard)
+        return;
+    for (const name of names) {
+        const state = await readWriterState(ctx.home, name);
+        const work = await (deps.lifecycle ?? lifecycle).inspectWork(ctx, name);
+        if (!work.baseline && state?.collected?.digest !== work.digest)
+            throw new Error("writer_uncollected");
+    }
+}
+export async function remove(ctx, name, discard, deps, extras = []) {
+    await preflight(ctx, [name], discard, deps);
+    const { adapter, ownership, life } = services(deps);
+    // Remove registrations before deleting the wrapper used to prove ownership.
+    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 });
+        if (owned)
+            await unregisterWriter(ownership, adapter, expected);
+        else if (["equivalent", "divergent"].includes(await adapter.inspect(expected)))
+            throw new Error("ownership_unavailable");
+    }
+    // After the registration is gone. A hook that cannot be edited is reported, not a reason to keep the
+    // writer: the operator's settings are not the writer's to hold hostage, and the record keeps the entry owned.
+    const hook = await writerHook(ctx, name, deps, "remove", false).catch(() => ({ status: "failed", code: "hook_install_failed" }));
+    if (hook)
+        extras.push(hook);
+    return life.removeWriter(ctx, name, { discard });
+}
+export const writerIndex = (name) => Number(name.slice(name.lastIndexOf("-w") + 2));
+/** Which writers a mode entry keeps, which of those still need provisioning, and which existing writers it no longer wants. */
+export async function plan(ctx, entry) {
+    const keep = [], missing = [], surplus = [];
+    for (let index = 1; index <= MAX_WRITERS; index++) {
+        const name = writerName(ctx.alias, index), state = await readWriterState(ctx.home, name);
+        if (entry.mode === "container" && index <= entry.container.writers) {
+            keep.push(name);
+            if (!state || state.phase === "provisioning")
+                missing.push(name);
+        }
+        else if (state)
+            surplus.push(name);
+    }
+    return { keep, missing, surplus };
+}

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>;