pi-session-mcp 0.13.0 → 0.14.0

package/dist/profile-probe.js

@@ -0,0 +1,164 @@
+import { toResolvedExecutionProfile } from "./execution-profile.js";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { GLOBAL_ERRORS } from "./setup-writers-common.js";
+export const PROBE_PROMPT = "Reply with exactly the word PONG and nothing else.";
+export const PROBE_DEADLINES = { startMs: 60_000, turnMs: 120_000, cleanupMs: 10_000 };
+export function isPong(reply) {
+    return reply.trim().replace(/\.$/, "").toUpperCase() === "PONG";
+}
+class ProbeTimeout extends Error {
+}
+class ProbeInterrupted extends Error {
+}
+/** Always detach the timer and listener, including when the operation rejects. */
+async function bounded(operation, ms, signal) {
+    if (signal?.aborted)
+        throw new ProbeInterrupted();
+    let timer;
+    let interrupt;
+    const stop = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new ProbeTimeout()), ms);
+        interrupt = () => reject(new ProbeInterrupted());
+        signal?.addEventListener("abort", interrupt, { once: true });
+    });
+    try {
+        return await Promise.race([Promise.resolve().then(operation), stop]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (interrupt)
+            signal?.removeEventListener("abort", interrupt);
+    }
+}
+async function dispose(handle, ms, abort) {
+    // An uncooperative abort must not prevent disposal or directory removal.
+    if (abort)
+        await bounded(() => handle.abort(), ms).catch(() => undefined);
+    await bounded(() => handle.dispose(), ms).catch(() => undefined);
+}
+async function probe(profile, adapter, deps) {
+    const deadlines = deps.deadlines ?? PROBE_DEADLINES;
+    const now = deps.now ?? Date.now;
+    const started = now();
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    deps.signal?.addEventListener("abort", interrupt, { once: true });
+    if (deps.signal?.aborted)
+        controller.abort();
+    let cwd;
+    let handle;
+    let abandoned = false;
+    let providerTurn = false;
+    let code = "probe_start_failed";
+    let startCode;
+    let abort = false;
+    try {
+        cwd = await deps.makeTempDir();
+        const input = { cwd, workspace: "profile-probe", executionProfile: toResolvedExecutionProfile(profile), signal: controller.signal };
+        handle = await bounded(async () => {
+            const created = await adapter.create(input);
+            // A create that ignores cancellation may finish after its deadline.
+            if (abandoned) {
+                await dispose(created, deadlines.cleanupMs, true);
+                throw new ProbeTimeout();
+            }
+            return created;
+        }, deadlines.startMs, deps.signal);
+        code = "probe_turn_failed";
+        const outcome = await bounded(() => handle.prompt(PROBE_PROMPT, (accepted) => {
+            if (accepted)
+                providerTurn = true;
+        }), deadlines.turnMs, deps.signal);
+        code = outcome.status === "completed"
+            ? isPong(outcome.assistantText) ? "probe_passed" : "probe_unexpected_reply"
+            : "probe_turn_failed";
+    }
+    catch (error) {
+        if (error instanceof ProbeTimeout || error instanceof ProbeInterrupted) {
+            abandoned = true;
+            controller.abort();
+            abort = true;
+            if (error instanceof ProbeTimeout)
+                code = "probe_timeout";
+        }
+        else if (handle === undefined) {
+            startCode = error instanceof PiSessionCreationError ? error.code : "pi_session_creation_failed";
+        }
+    }
+    finally {
+        deps.signal?.removeEventListener("abort", interrupt);
+        try {
+            if (handle)
+                await dispose(handle, deadlines.cleanupMs, abort || deps.signal?.aborted === true);
+        }
+        finally {
+            if (cwd !== undefined)
+                await deps.removeDir(cwd);
+        }
+    }
+    return {
+        profile: profile.alias, status: code === "probe_passed" ? "ok" : "failed", code,
+        ...(startCode === undefined ? {} : { startCode }), providerTurn, durationMs: Math.max(0, now() - started),
+    };
+}
+export async function runProfileProbe(request, deps) {
+    const profiles = [...new Set(request.profiles)];
+    const doctor = { blocking: [], other: [] };
+    const findings = [];
+    const report = (refusal) => {
+        const status = refusal !== undefined || findings.some((finding) => finding.status === "failed")
+            ? "failed" : request.apply ? "ok" : "planned";
+        return {
+            schemaVersion: 1, operation: request.apply ? "apply" : "dry-run", status,
+            ...(refusal === undefined ? {} : { refusal }), doctor, findings, usage: "unknown",
+            exitCode: refusal === "operation_interrupted" ? 130 : status === "failed" ? 1 : 0,
+        };
+    };
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    const diagnosis = await deps.doctor();
+    for (const check of diagnosis.checks) {
+        if (check.severity === "ok")
+            continue;
+        const list = check.severity === "error" && (GLOBAL_ERRORS.has(check.id) || profiles.includes(check.subject.split(":")[0]))
+            ? doctor.blocking : doctor.other;
+        if (!list.includes(check.id))
+            list.push(check.id);
+    }
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    if (doctor.blocking.length)
+        return report("doctor_failed");
+    let config;
+    try {
+        config = await deps.loadConfig(deps.configPath);
+    }
+    catch {
+        return report(deps.signal?.aborted ? "operation_interrupted" : "config_unusable");
+    }
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    const catalog = await deps.catalog();
+    let adapter;
+    for (const alias of profiles) {
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+        const profile = config.executionProfiles.get(alias);
+        const provider = profile && catalog.providers().find((entry) => entry.id === profile.provider);
+        const code = !profile ? "probe_profile_unknown"
+            : !provider ? "probe_provider_unknown"
+                : !provider.models.includes(profile.model) ? "probe_model_unknown"
+                    : !provider.authConfigured ? "probe_auth_missing" : "probe_planned";
+        if (code !== "probe_planned" || !request.apply) {
+            findings.push({ profile: alias, status: code === "probe_planned" ? "planned" : "failed", code, providerTurn: false });
+            continue;
+        }
+        adapter ??= await deps.adapter();
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+        findings.push(await probe(profile, adapter, deps));
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+    }
+    return report();
+}

package/dist/sdk-pi-adapter.js

@@ -1,4 +1,4 @@
-import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { homedir, userInfo } from "node:os";
 import { join } from "node:path";
 import { allowedReadRoots, createConfinedReadOnlyTools } from "./confined-tools.js";
@@ -347,7 +347,8 @@ export class SdkPiSessionAdapter {
         catch {
             return homedir();
         } })();
-        this.protectedReadPaths = [home, join(home, ".pi"), ...(options.protectedReadPaths ?? [])];
+        // Pi's agent directory holds its credentials; the SDK resolves it from `PI_CODING_AGENT_DIR` or below `~/.pi`.
+        this.protectedReadPaths = [home, join(home, ".pi"), getAgentDir(), ...(options.protectedReadPaths ?? [])];
     }
     async create(input) {
         const extensions = input.executionProfile.extensions ?? [];

package/dist/setup-cli.d.ts

@@ -1,4 +1,4 @@
-import { SetupOrchestrator, type SetupRequest } from "./setup.js";
+import type { SetupRequest } from "./setup.js";
 import type { SetupResult } from "./setup-result.js";
 import type { ModeRequest } from "./setup-modes.js";
 import type { WriterOperation } from "./setup-writers.js";
@@ -19,9 +19,15 @@ export interface SetupCliRequest extends SetupRequest {
         alias: string;
         apply: boolean;
     };
+    /** `--list-models`: prints the offline provider/model catalog. */
+    readonly listModels?: true;
+    /** `--probe-profile <alias>[,<alias>...]`: checks profiles offline, then probes them with `--apply`. */
+    readonly probe?: {
+        readonly profiles: readonly string[];
+        readonly apply: boolean;
+    };
 }
 export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
-export declare function runSetupCli(argv: readonly string[], orchestrator: SetupOrchestrator): Promise<SetupResult>;
 /** Both report modes are projections of the same sanitized result. */
 export declare function formatSetupResult(setupResult: SetupResult): string;
 export declare function formatSetupHuman(setupResult: SetupResult): string;

package/dist/setup-cli.js

@@ -1,5 +1,6 @@
 import { cpusSchema, cpuSharesSchema, memorySchema } from "./writer-limits.js";
 import { WRITER_NAME_PATTERN } from "./writer-state.js";
+import { ALIAS_PATTERN } from "./execution-profile.js";
 export function parseSetupArgs(argv) {
     let operation;
     let json = false;
@@ -10,6 +11,8 @@ export function parseSetupArgs(argv) {
     let acceptHostWrites = false;
     let writer, writerOperation, baseRef;
     let discard = false, codex = false, isolationControl = false;
+    let listModels = false;
+    let probeProfiles;
     const container = {};
     const modeFlags = new Set();
     const clearLimits = [];
@@ -60,6 +63,24 @@ export function parseSetupArgs(argv) {
             json = true;
             continue;
         }
+        if (argument === "--list-models") {
+            if (listModels)
+                throw new Error("usage_invalid");
+            listModels = true;
+            continue;
+        }
+        if (argument === "--probe-profile") {
+            if (probeProfiles !== undefined)
+                throw new Error("usage_invalid");
+            const value = argv[++index];
+            if (value === undefined || value === "")
+                throw new Error("usage_invalid");
+            const aliases = value.split(",");
+            if (aliases.some((alias) => !ALIAS_PATTERN.test(alias)))
+                throw new Error("usage_invalid");
+            probeProfiles = [...new Set(aliases)];
+            continue;
+        }
         if (argument === "--dry-run" || argument === "--apply" || argument === "--verify" || argument === "--rollback" || argument === "--remove") {
             if (operation)
                 throw new Error("operation_repeated");
@@ -173,6 +194,21 @@ export function parseSetupArgs(argv) {
         }
         throw new Error("argument_unsupported");
     }
+    if (listModels || probeProfiles !== undefined) {
+        if (listModels && probeProfiles !== undefined)
+            throw new Error("usage_invalid");
+        if (targets.length > 0 || modeFlags.size > 0 || customizeSkill !== undefined || writer !== undefined || writerOperation !== undefined || isolationControl || discard || baseRef || codex) {
+            throw new Error(listModels ? "list_models_combination" : "probe_combination");
+        }
+        if (listModels) {
+            if (operation !== undefined && operation !== "dry-run")
+                throw new Error("list_models_combination");
+            return { ...(operation ? { operation } : {}), targets, json, listModels: true };
+        }
+        if (operation !== undefined && operation !== "dry-run" && operation !== "apply")
+            throw new Error("probe_combination");
+        return { ...(operation ? { operation } : {}), targets, json, probe: { profiles: probeProfiles, apply: operation === "apply" } };
+    }
     if (writer !== undefined) {
         if (operation === "remove" || operation === "verify") {
             if (writerOperation)
@@ -210,9 +246,6 @@ export function parseSetupArgs(argv) {
     }
     return operation ? { operation, targets, json } : { targets, json };
 }
-export async function runSetupCli(argv, orchestrator) {
-    return orchestrator.run(parseSetupArgs(argv));
-}
 /** Both report modes are projections of the same sanitized result. */
 export function formatSetupResult(setupResult) {
     return JSON.stringify(setupResult);

package/dist/setup-main.js

@@ -26,9 +26,14 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     const failureTargets = request.writer ? [{ client: "writer", scope: request.writer.name.slice(0, request.writer.name.lastIndexOf("-w")), alias: request.writer.name }] : request.isolationControl ? [{ client: "writer", scope: "host", alias: "control" }] : request.repo !== undefined ? [{ client: "modes", scope: "workspace", alias: request.repo.alias }] : request.customizeSkill === undefined ? request.targets : [skillTarget(request.customizeSkill)];
     if (!currentSetupPlatform())
         return write(cliFailure(operation, failureTargets, "platform_unsupported", 1), request.json);
+    if (request.listModels)
+        return (await import("./setup-probe-main.js")).runListModels(request.json);
     const config = process.env.PI_SESSION_MCP_CONFIG;
-    if (!config)
+    if (!config) {
+        if (request.probe)
+            return (await import("./setup-probe-main.js")).runProbe(request.probe, request.json, "", new AbortController().signal);
         return write(cliFailure(operation, failureTargets, "config_required", 1), request.json);
+    }
     if (request.customizeSkill !== undefined) {
         const name = request.customizeSkill;
         try {
@@ -41,12 +46,14 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     const root = dependencies.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
     const controller = new AbortController();
     let interrupted;
-    const onInterrupt = () => { interrupted ??= 130; controller.abort(); };
-    const onTerminate = () => { interrupted ??= 143; controller.abort(); };
+    const onInterrupt = () => { interrupted ??= 130; controller.abort(interrupted); };
+    const onTerminate = () => { interrupted ??= 143; controller.abort(interrupted); };
     process.on("SIGINT", onInterrupt);
     process.on("SIGTERM", onTerminate);
     let setup;
     try {
+        if (request.probe)
+            return await (await import("./setup-probe-main.js")).runProbe(request.probe, request.json, resolve(config), controller.signal, { packageRoot: root });
         const writerDeps = { configPath: resolve(config), releaseRoot: root, signal: controller.signal };
         if (request.repo !== undefined) {
             try {

package/dist/setup-probe-main.d.ts

@@ -0,0 +1,14 @@
+import { type DoctorResult } from "./doctor.js";
+import { type ModelCatalog } from "./model-catalog.js";
+import type { PiSessionAdapter } from "./pi-adapter.js";
+export interface ProbeMainDependencies {
+    readonly catalog?: () => Promise<ModelCatalog>;
+    readonly adapter?: () => Promise<PiSessionAdapter>;
+    readonly doctor?: () => Promise<DoctorResult>;
+    readonly packageRoot?: string;
+}
+export declare function runListModels(json: boolean, deps?: ProbeMainDependencies): Promise<number>;
+export declare function runProbe(request: {
+    profiles: readonly string[];
+    apply: boolean;
+}, json: boolean, configPath: string, signal: AbortSignal, deps?: ProbeMainDependencies): Promise<number>;

package/dist/setup-probe-main.js

@@ -0,0 +1,76 @@
+import { stdoutGuard } from "./stdout-guard-install.js";
+import { chmod, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { createModelCatalog } from "./model-catalog.js";
+import { runProfileProbe } from "./profile-probe.js";
+import { SdkPiSessionAdapter } from "./sdk-pi-adapter.js";
+import { catalogReport, formatCatalogHuman, formatProbeHuman } from "./setup-probe-result.js";
+export async function runListModels(json, deps = {}) {
+    let report;
+    try {
+        report = catalogReport(await (deps.catalog ?? createModelCatalog)());
+    }
+    catch {
+        report = catalogReport(undefined);
+    }
+    stdoutGuard.transportStdout.write(json ? JSON.stringify(report) + "\n" : formatCatalogHuman(report));
+    return report.exitCode;
+}
+function refused(apply, refusal) {
+    return {
+        schemaVersion: 1, operation: apply ? "apply" : "dry-run", status: "failed", refusal,
+        doctor: { blocking: [], other: [] }, findings: [], usage: "unknown", exitCode: refusal === "operation_interrupted" ? 130 : 1,
+    };
+}
+export async function runProbe(request, json, configPath, signal, deps = {}) {
+    let report;
+    let catalogFailed = false;
+    try {
+        if (!configPath)
+            report = refused(request.apply, "config_required");
+        else {
+            const configFile = resolve(configPath);
+            const packageRoot = deps.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
+            report = await runProfileProbe(request, {
+                configPath: configFile, loadConfig, signal,
+                doctor: deps.doctor ?? (() => runDoctor({ packageRoot, configPath: configFile, loadConfig: () => loadConfig(configFile) })),
+                catalog: async () => {
+                    try {
+                        return await (deps.catalog ?? createModelCatalog)();
+                    }
+                    catch (error) {
+                        catalogFailed = true;
+                        throw error;
+                    }
+                },
+                adapter: deps.adapter ?? (async () => new SdkPiSessionAdapter({
+                    diagnosticSink: (diagnostic) => { process.stderr.write(JSON.stringify(diagnostic) + "\n"); },
+                    protectedReadPaths: [dirname(configFile), dirname(await realpath(configFile))],
+                })),
+                makeTempDir: async () => {
+                    const directory = await mkdtemp(join(tmpdir(), "pi-session-mcp-probe-"));
+                    try {
+                        await chmod(directory, 0o700);
+                        return directory;
+                    }
+                    catch (error) {
+                        await rm(directory, { recursive: true, force: true });
+                        throw error;
+                    }
+                },
+                removeDir: (directory) => rm(directory, { recursive: true, force: true }),
+            });
+        }
+    }
+    catch {
+        report = refused(request.apply, signal.aborted ? "operation_interrupted" : catalogFailed ? "catalog_unavailable" : "operation_failed");
+    }
+    if (signal.aborted)
+        report = { ...report, status: "failed", refusal: "operation_interrupted", exitCode: signal.reason === 143 ? 143 : 130 };
+    stdoutGuard.transportStdout.write(json ? JSON.stringify(report) + "\n" : formatProbeHuman(report));
+    return report.exitCode;
+}

package/dist/setup-probe-result.d.ts

@@ -0,0 +1,39 @@
+import { type CatalogProvider, type ModelCatalog } from "./model-catalog.js";
+import type { PiSessionCreationErrorCode } from "./pi-adapter.js";
+/** Public, path-free `--list-models` report. */
+export interface ModelCatalogReport {
+    readonly schemaVersion: 1;
+    readonly status: "ok" | "failed";
+    readonly code?: "catalog_unavailable";
+    readonly providers: readonly CatalogProvider[];
+    readonly omittedIds: number;
+    readonly note: "extension_providers_not_listed";
+    readonly exitCode: 0 | 1;
+}
+/** Fails closed when no catalog could be created; drops ids that are not plain catalog ids. */
+export declare function catalogReport(catalog: ModelCatalog | undefined): ModelCatalogReport;
+/** One line per provider with its auth presence and model ids, then the fixed extension note. */
+export declare function formatCatalogHuman(report: ModelCatalogReport): string;
+export type ProbeCode = "probe_planned" | "probe_profile_unknown" | "probe_provider_unknown" | "probe_model_unknown" | "probe_auth_missing" | "probe_passed" | "probe_unexpected_reply" | "probe_turn_failed" | "probe_start_failed" | "probe_timeout";
+export interface ProbeFinding {
+    readonly profile: string;
+    readonly status: "planned" | "ok" | "failed";
+    readonly code: ProbeCode;
+    readonly startCode?: PiSessionCreationErrorCode;
+    readonly providerTurn: boolean;
+    readonly durationMs?: number;
+}
+export interface ProbeReport {
+    readonly schemaVersion: 1;
+    readonly operation: "dry-run" | "apply";
+    readonly status: "planned" | "ok" | "failed";
+    readonly refusal?: "doctor_failed" | "config_required" | "config_unusable" | "operation_interrupted" | "catalog_unavailable" | "operation_failed";
+    readonly doctor: {
+        readonly blocking: readonly string[];
+        readonly other: readonly string[];
+    };
+    readonly findings: readonly ProbeFinding[];
+    readonly usage: "unknown";
+    readonly exitCode: 0 | 1 | 130 | 143;
+}
+export declare function formatProbeHuman(report: ProbeReport): string;

package/dist/setup-probe-result.js

@@ -0,0 +1,62 @@
+import { CATALOG_ID_PATTERN } from "./model-catalog.js";
+const compareIds = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const providersOf = (catalog) => {
+    let omittedIds = 0;
+    const providers = [];
+    for (const provider of [...catalog.providers()].sort((left, right) => compareIds(left.id, right.id))) {
+        if (!CATALOG_ID_PATTERN.test(provider.id)) {
+            omittedIds += 1;
+            continue;
+        }
+        const models = new Set();
+        for (const model of provider.models) {
+            if (!CATALOG_ID_PATTERN.test(model)) {
+                omittedIds += 1;
+                continue;
+            }
+            models.add(model);
+        }
+        providers.push(Object.freeze({
+            id: provider.id,
+            authConfigured: provider.authConfigured === true,
+            models: Object.freeze([...models].sort(compareIds)),
+        }));
+    }
+    return Object.freeze({ providers: Object.freeze(providers), omittedIds });
+};
+/** Fails closed when no catalog could be created; drops ids that are not plain catalog ids. */
+export function catalogReport(catalog) {
+    if (catalog === undefined) {
+        return Object.freeze({
+            schemaVersion: 1,
+            status: "failed",
+            code: "catalog_unavailable",
+            providers: Object.freeze([]),
+            omittedIds: 0,
+            note: "extension_providers_not_listed",
+            exitCode: 1,
+        });
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        status: "ok",
+        ...providersOf(catalog),
+        note: "extension_providers_not_listed",
+        exitCode: 0,
+    });
+}
+/** One line per provider with its auth presence and model ids, then the fixed extension note. */
+export function formatCatalogHuman(report) {
+    const lines = report.providers.map((provider) => `${provider.id} (auth: ${provider.authConfigured ? "yes" : "no"}): ${provider.models.join(", ")}`);
+    if (report.status === "failed")
+        lines.unshift("Model catalog unavailable.");
+    lines.push("Providers registered only by Pi extensions are not listed.");
+    return `${lines.join("\n")}\n`;
+}
+export function formatProbeHuman(report) {
+    const lines = report.findings.map((finding) => `${finding.profile}: ${finding.status} (${finding.code}${finding.startCode === undefined ? "" : ` ${finding.startCode}`})`);
+    if (report.refusal !== undefined)
+        lines.unshift(`Probe refused: ${report.refusal}`);
+    lines.push(`provider turns: ${report.findings.filter((finding) => finding.providerTurn).length}, usage: unknown`);
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,78 @@
+import { runDoctor } from "./doctor.js";
+import { type WorkspaceModeEntry } from "./execution-modes.js";
+import { acquireOverrideLock } from "./override-lock.js";
+import { createCommandMcpStdioLauncher } from "./setup-process.js";
+import { DurableOwnershipStore, type OwnershipStore } from "./setup-ownership.js";
+import { type WakeHookOutcome } from "./setup-hooks.js";
+import type { SetupFinding, SetupTarget } from "./setup-result.js";
+import { type WriterRegistrationIntent, 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";
+/** Services, fencing, the Doctor gate and removal shared by mode changes, reconciliation and single-writer operations. */
+export declare const SETUP_LEASE_WAIT_MS = 10000;
+export declare const FENCE_CODES: readonly string[];
+/**
+ * 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 declare const INFRASTRUCTURE_CODE: RegExp;
+export declare const GLOBAL_ERRORS: Set<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>;
+}
+export declare const targetFor: (alias: string, name: string) => SetupTarget;
+export declare const modesTarget: (alias: string) => SetupTarget;
+export declare const codeFor: (error: unknown) => string;
+export declare function services(deps: WriterSetupDependencies): {
+    home: string;
+    runner: import("./client-adapters/types.js").CommandRunner;
+    life: typeof lifecycle;
+    accept: typeof acceptance;
+    ownership: DurableOwnershipStore | OwnershipStore;
+    adapter: WriterRegistrationAdapter;
+};
+export declare function context(alias: string, deps: WriterSetupDependencies): Promise<lifecycle.WriterContext>;
+export declare function locked<T>(deps: WriterSetupDependencies, action: () => Promise<T>): Promise<T>;
+export declare function fenced<T>(ctx: lifecycle.WriterContext, name: string, deps: WriterSetupDependencies, action: (ctx: lifecycle.WriterContext) => Promise<T>): Promise<T>;
+export declare function intent(ctx: lifecycle.WriterContext, name: string, client: "claude-code" | "codex"): WriterRegistrationIntent;
+/**
+ * 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 declare function writerHook(ctx: lifecycle.WriterContext, name: string, deps: WriterSetupDependencies, operation: "apply" | "dry-run" | "verify" | "remove", enabled: boolean): Promise<WakeHookOutcome | undefined>;
+export declare class DoctorGateError extends Error {
+    readonly findings: readonly SetupFinding[];
+    constructor(findings: readonly SetupFinding[]);
+}
+export declare function doctorGate(ctx: lifecycle.WriterContext, deps: WriterSetupDependencies): Promise<void>;
+export declare function preflight(ctx: lifecycle.WriterContext, names: readonly string[], discard: boolean, deps: WriterSetupDependencies): Promise<void>;
+export declare function remove(ctx: lifecycle.WriterContext, name: string, discard: boolean, deps: WriterSetupDependencies, extras?: WakeHookOutcome[]): Promise<lifecycle.WriterOutcome>;
+export declare const writerIndex: (name: string) => number;
+/** Which writers a mode entry keeps, which of those still need provisioning, and which existing writers it no longer wants. */
+export declare function plan(ctx: lifecycle.WriterContext, entry: WorkspaceModeEntry): Promise<{
+    keep: string[];
+    missing: string[];
+    surplus: string[];
+}>;
+export type WriterPlan = Awaited<ReturnType<typeof plan>>;