pi-session-mcp 0.12.1 → 0.13.1

package/dist/sdk-pi-adapter.js

@@ -1,11 +1,15 @@
-import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, 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";
 import { PiExtensionError } from "./extension-spec.js";
 import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-tools.js";
 import { createStdioMcpConnection } from "./mcp-stdio-client.js";
 import { PiSessionCreationError, } from "./pi-adapter.js";
 import { resolvePiExtension } from "./pi-extensions.js";
 import { loadSelectedSkills, PiSkillError } from "./pi-skills.js";
-import { composeSessionTools, PROFILE_TOOLS } from "./session-tools.js";
+import { createSandboxedBashOperations, probeSandbox } from "./sandbox-shell.js";
+import { composeSessionTools, profileTools } from "./session-tools.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 export const AUTH_OPERATION_TIMEOUT_MS = 5_000;
 /** Server-side bound for SDK session construction. The SDK does not document cancellation. */
@@ -326,6 +330,8 @@ export class SdkPiSessionAdapter {
     mcpConnectionFactory;
     resolveExtension;
     extensionSdk;
+    sandbox;
+    protectedReadPaths;
     constructor(options = {}) {
         this.modelRuntimeFactory = options.modelRuntimeFactory ?? (() => ModelRuntime.create({ refreshOnCreate: false }));
         this.createSession = options.createSession ?? createAgentSession;
@@ -333,6 +339,16 @@ export class SdkPiSessionAdapter {
         this.mcpConnectionFactory = options.mcpConnectionFactory ?? createStdioMcpConnection;
         this.resolveExtension = options.resolveExtension ?? ((extension) => resolvePiExtension(extension));
         this.extensionSdk = options.extensionSdk ?? DEFAULT_EXTENSION_SDK;
+        this.sandbox = options.sandbox ?? {};
+        // The account database's home, not `$HOME`, which a caller's environment could point elsewhere.
+        const home = (() => { try {
+            return userInfo().homedir;
+        }
+        catch {
+            return homedir();
+        } })();
+        // 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 ?? [];
@@ -356,8 +372,10 @@ export class SdkPiSessionAdapter {
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
         }
+        const confined = await this.confinedTools(input, skills);
         const mcpTools = await this.connectMcpTools(input);
-        const tools = [...PROFILE_TOOLS[executionProfile.permissionProfile], ...mcpTools.tools.map((tool) => tool.name)];
+        const tools = [...profileTools(executionProfile.permissionProfile, executionProfile.shell), ...mcpTools.tools.map((tool) => tool.name)];
+        const customTools = [...confined, ...mcpTools.tools];
         let session;
         try {
             ({ session } = await withCreationDeadline(() => this.createSession({
@@ -370,14 +388,14 @@ export class SdkPiSessionAdapter {
                 resourceLoader,
                 // With an explicit tools list, Pi also needs custom tool names here to activate them.
                 tools,
-                ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+                ...(customTools.length === 0 ? {} : { customTools }),
             }), (late) => disposeSdkSession(late.session)));
         }
         catch {
             await mcpTools.close();
             throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
         }
-        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills);
+        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills, [], confined);
     }
     async createWithExtensions(input, extensions) {
         const { cwd, executionProfile } = input;
@@ -423,9 +441,11 @@ export class SdkPiSessionAdapter {
             throw this.failure(executionProfile, "extension_load", "extension_load_failed");
         }
         const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
+        const confined = await this.confinedTools(input, skills);
         const mcpTools = await this.connectMcpTools(input);
+        const customTools = [...confined, ...mcpTools.tools];
         const grantedTools = executionProfile.grantedExtensionTools ?? [];
-        const composed = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools, grantedTools);
+        const composed = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools, grantedTools, executionProfile.shell);
         if (!composed.ok) {
             await mcpTools.close();
             throw this.failure(executionProfile, "extension_load", composed.code);
@@ -440,7 +460,7 @@ export class SdkPiSessionAdapter {
                     model,
                     thinkingLevel: executionProfile.thinkingLevel,
                     tools,
-                    ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+                    ...(customTools.length === 0 ? {} : { customTools }),
                 })),
                 services,
                 diagnostics: services.diagnostics,
@@ -474,7 +494,7 @@ export class SdkPiSessionAdapter {
             // A `session_start` handler may register a tool that replaces a built-in or granted tool.
             // Tools an extension registers later, during a turn, are not re-checked: allowlisted
             // extensions are trusted code.
-            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services), grantedTools);
+            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services), grantedTools, executionProfile.shell);
             if (!recheck.ok)
                 throw this.failure(executionProfile, "extension_bind", recheck.code);
             if (recheck.tools.length !== tools.length || recheck.tools.some((name, index) => name !== tools[index]))
@@ -490,7 +510,35 @@ export class SdkPiSessionAdapter {
             await cleanUp();
             throw this.failure(executionProfile, "extension_bind", "extension_tool_conflict");
         }
-        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills, grantedTools);
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills, grantedTools, confined);
+    }
+    /**
+     * The server's own tool definitions of a read-only session (ADR 0013); none for coding. The workspace
+     * root is the session directory: a root that cannot be resolved fails the start. With a sandboxed shell
+     * the sandbox is probed first, and a profile whose sandbox cannot start never gets a session.
+     */
+    async confinedTools(input, skills) {
+        const { executionProfile } = input;
+        if (executionProfile.permissionProfile !== "read-only")
+            return [];
+        let roots;
+        try {
+            roots = await allowedReadRoots(input.cwd, skills, this.protectedReadPaths);
+        }
+        catch {
+            throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
+        }
+        const tools = createConfinedReadOnlyTools(input.cwd, roots);
+        if (executionProfile.shell === "sandboxed") {
+            // The first root is the real path of the workspace.
+            if (!(await probeSandbox(roots[0], this.sandbox, input.signal)))
+                throw this.failure(executionProfile, "sandbox", "sandbox_unavailable");
+            tools.push(createBashToolDefinition(input.cwd, {
+                operations: createSandboxedBashOperations(roots[0], this.sandbox),
+                exposeSessionEnvironment: false,
+            }));
+        }
+        return tools;
     }
     async loadSkills(input) {
         try {
@@ -581,9 +629,16 @@ export class SdkPiSessionAdapter {
     /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
     async admit(session, executionProfile, tools, mcpTools, disposeSession, toolMismatch, 
     // `subset` lets an extension narrow its own active tools; nothing outside the allowlist may be active.
-    toolCheck = "exact", skills = [], requiredTools = []) {
+    toolCheck = "exact", skills = [], requiredTools = [], 
+    // The server's own definitions must be the ones the session resolves for their names.
+    ownDefinitions = []) {
         try {
             this.checkResources(session.resourceLoader, skills, executionProfile, "postcheck");
+            for (const definition of ownDefinitions) {
+                if (session.getToolDefinition(definition.name) !== definition) {
+                    throw this.failure(executionProfile, "postcheck", "pi_session_creation_failed");
+                }
+            }
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
                 throw this.failure(executionProfile, "postcheck", "execution_selection_mismatch");
             }

package/dist/session-tools.d.ts

@@ -1,5 +1,7 @@
-import type { PermissionProfile } from "./execution-profile.js";
+import type { PermissionProfile, ShellMode } from "./execution-profile.js";
 export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly string[]>>;
+/** The built-in tools of a profile: a read-only profile with a sandboxed shell also has `bash`. */
+export declare function profileTools(permissionProfile: PermissionProfile, shell?: ShellMode): readonly string[];
 export declare const MAX_GRANTED_EXTENSION_TOOLS = 32;
 export declare function isAcceptableExtensionToolName(name: string): boolean;
 export type ComposedSessionTools = {
@@ -15,4 +17,4 @@ export type ComposedSessionTools = {
  * in both profiles so an extension can never shadow a built-in or granted MCP tool.
  * Unsafe names and names the SDK treats as MCP tools also fail closed.
  */
-export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[], grantedExtensionTools?: readonly string[]): ComposedSessionTools;
+export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[], grantedExtensionTools?: readonly string[], shell?: ShellMode): ComposedSessionTools;

package/dist/session-tools.js

@@ -2,6 +2,10 @@ export const PROFILE_TOOLS = {
     "read-only": ["read", "grep", "find", "ls"],
     coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
 };
+/** The built-in tools of a profile: a read-only profile with a sandboxed shell also has `bash`. */
+export function profileTools(permissionProfile, shell) {
+    return permissionProfile === "read-only" && shell === "sandboxed" ? [...PROFILE_TOOLS["read-only"], "bash"] : PROFILE_TOOLS[permissionProfile];
+}
 export const MAX_GRANTED_EXTENSION_TOOLS = 32;
 /**
  * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
@@ -27,7 +31,7 @@ export function isAcceptableExtensionToolName(name) {
  * in both profiles so an extension can never shadow a built-in or granted MCP tool.
  * Unsafe names and names the SDK treats as MCP tools also fail closed.
  */
-export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = []) {
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = [], shell) {
     const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
     const extensionTools = [];
     for (const names of extensionToolNames) {
@@ -41,5 +45,5 @@ export function composeSessionTools(permissionProfile, mcpToolNames, extensionTo
     if (permissionProfile === "read-only" && grantedExtensionTools.some((name) => !extensionTools.includes(name))) {
         return { ok: false, code: "extension_tool_missing" };
     }
-    return { ok: true, tools: [...PROFILE_TOOLS[permissionProfile], ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
+    return { ok: true, tools: [...profileTools(permissionProfile, shell), ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
 }

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";
@@ -21,7 +21,6 @@ export interface SetupCliRequest extends SetupRequest {
     };
 }
 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,3 +1,4 @@
+import { cpusSchema, cpuSharesSchema, memorySchema } from "./writer-limits.js";
 import { WRITER_NAME_PATTERN } from "./writer-state.js";
 export function parseSetupArgs(argv) {
     let operation;
@@ -11,6 +12,7 @@ export function parseSetupArgs(argv) {
     let discard = false, codex = false, isolationControl = false;
     const container = {};
     const modeFlags = new Set();
+    const clearLimits = [];
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (["--collect", "--reset", "--recreate", "--finish"].includes(argument)) {
@@ -81,7 +83,7 @@ export function parseSetupArgs(argv) {
             customizeSkill = value;
             continue;
         }
-        if (["--repo", "--mode", "--accept-host-writes", "--writers", "--lifecycle", "--profiles", "--image", "--network", "--cache", "--tags"].includes(argument)) {
+        if (["--repo", "--mode", "--accept-host-writes", "--writers", "--lifecycle", "--profiles", "--image", "--network", "--cache", "--tags", "--clean", "--cpus", "--cpu-shares", "--memory"].includes(argument)) {
             if (modeFlags.has(argument))
                 throw new Error("repo_argument_repeated");
             modeFlags.add(argument);
@@ -89,8 +91,8 @@ export function parseSetupArgs(argv) {
                 acceptHostWrites = true;
                 continue;
             }
-            const value = argv[++index];
-            if (!value || value.startsWith("-"))
+            const value = argv[++index] ?? "";
+            if ((!value || value.startsWith("-")) && !["--cpus", "--cpu-shares", "--memory"].includes(argument))
                 throw new Error("repo_argument_invalid");
             switch (argument) {
                 case "--repo":
@@ -129,8 +131,40 @@ export function parseSetupArgs(argv) {
                         throw new Error("tags_invalid");
                     container.tags = value;
                     break;
+                case "--clean":
+                    if (value !== "untracked" && value !== "all")
+                        throw new Error("clean_invalid");
+                    container.clean = value;
+                    break;
+                case "--cpus":
+                    if (value === "none") {
+                        clearLimits.push("cpus");
+                        break;
+                    }
+                    if (!value || !/^[0-9]+(?:\.[0-9]{1,2})?$/.test(value) || !cpusSchema.safeParse(Number(value)).success)
+                        throw new Error("cpus_invalid");
+                    container.cpus = Number(value);
+                    break;
+                case "--cpu-shares":
+                    if (value === "none") {
+                        clearLimits.push("cpuShares");
+                        break;
+                    }
+                    if (!value || !/^[0-9]+$/.test(value) || !cpuSharesSchema.safeParse(Number(value)).success)
+                        throw new Error("cpu_shares_invalid");
+                    container.cpuShares = Number(value);
+                    break;
+                case "--memory":
+                    if (value === "none") {
+                        clearLimits.push("memory");
+                        break;
+                    }
+                    if (!memorySchema.safeParse(value).success)
+                        throw new Error("memory_invalid");
+                    container.memory = value;
+                    break;
                 case "--cache":
-                    if (value !== "none" && value !== "go" && value !== "uv")
+                    if (value !== "none" && value !== "go" && value !== "uv" && value !== "npm")
                         throw new Error("cache_invalid");
                     container.cache = value;
                     break;
@@ -163,9 +197,9 @@ export function parseSetupArgs(argv) {
     if (modeFlags.size > 0) {
         if (repo === undefined || targets.length > 0 || customizeSkill !== undefined || (operation !== undefined && operation !== "dry-run" && operation !== "apply"))
             throw new Error("repo_combination");
-        if ((mode === "host" || mode === "read-only") && Object.keys(container).length > 0)
+        if ((mode === "host" || mode === "read-only") && (Object.keys(container).length > 0 || clearLimits.length > 0))
             throw new Error("repo_combination");
-        const request = { alias: repo, acceptHostWrites, apply: operation === "apply", discard, codex, ...(baseRef ? { baseRef } : {}), ...(mode === undefined ? {} : { mode }), ...(Object.keys(container).length === 0 ? {} : { container }) };
+        const request = { alias: repo, acceptHostWrites, apply: operation === "apply", discard, codex, ...(baseRef ? { baseRef } : {}), ...(mode === undefined ? {} : { mode }), ...(Object.keys(container).length === 0 ? {} : { container }), ...(clearLimits.length === 0 ? {} : { clearLimits }) };
         return { ...(operation === undefined ? {} : { operation }), targets, json, repo: request };
     }
     if (customizeSkill !== undefined) {
@@ -176,9 +210,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-modes.d.ts

@@ -9,9 +9,12 @@ export interface ModeRequest {
     readonly discard?: boolean;
     readonly baseRef?: string;
     readonly codex?: boolean;
+    /** Limits to remove (`--cpus none` and so on); an omitted limit keeps the recorded one (#166). */
+    readonly clearLimits?: readonly ("cpus" | "cpuShares" | "memory")[];
 }
 /** A dry run writes nothing; apply serializes the entire read/validate/replace transaction. */
 export declare function changeExecutionMode(configPath: string, request: ModeRequest, dependencies?: {
+    cgroupControllers?: () => Promise<readonly string[]>;
     containerRuntime?: () => Promise<boolean>;
     beforeWrite?: (entry: import("./execution-modes.js").WorkspaceModeEntry) => Promise<SetupResult | undefined>;
     afterChange?: (output: SetupResult) => Promise<SetupResult>;

package/dist/setup-modes.js

@@ -1,3 +1,6 @@
+import { podmanCgroupControllers } from "./writer-boundary.js";
+import { createProcessRunner } from "./setup-process.js";
+import { writerLimits } from "./writer-limits.js";
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -65,7 +68,14 @@ export async function changeExecutionMode(configPath, request, dependencies = {}
             const previousBase = existing?.mode === "container" ? existing.base : undefined;
             const requestedBase = request.baseRef?.replace(/^refs\/heads\//, "");
             const base = requestedBase ?? previousBase ?? request.container?.base;
-            return { ...request.container, mode, ...(base === undefined ? {} : { base }) };
+            // Limits are outside the settings drift check, so an omitted flag must not drop one silently (#166).
+            const limits = Object.fromEntries(["cpus", "cpuShares", "memory"].flatMap((key) => {
+                if (request.clearLimits?.includes(key))
+                    return [];
+                const value = request.container?.[key] ?? (existing?.mode === "container" ? existing[key] : undefined);
+                return value === undefined ? [] : [[key, value]];
+            }));
+            return { ...request.container, ...limits, mode, ...(base === undefined ? {} : { base }) };
         })() : { mode };
         let proposed;
         try {
@@ -76,6 +86,13 @@ export async function changeExecutionMode(configPath, request, dependencies = {}
             return done("failed", "modes_file_invalid");
         }
         const resolved = resolveExecutionModes(proposed, aliases, config.executionProfiles).get(request.alias);
+        const limits = resolved.container && writerLimits(resolved.container);
+        if (limits) {
+            const controllers = await (dependencies.cgroupControllers ?? (() => podmanCgroupControllers(createProcessRunner())))().catch(() => []);
+            if (((limits.cpus !== undefined || limits.cpuShares !== undefined) && !controllers.includes("cpu"))
+                || (limits.memory !== undefined && !controllers.includes("memory")))
+                return done("failed", "cgroup_controller_unavailable");
+        }
         const refused = await dependencies.beforeWrite?.(resolved);
         if (refused)
             return refused;

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

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"]);
+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 };
+}