pi-session-mcp 0.13.0 → 0.13.1

package/.pi-session-mcp-cli/config.js

@@ -72,12 +72,31 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    constructor(code, locations = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
     }
 }
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -151,7 +170,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
             const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues));
         }
         throw error;
     }

package/.pi-session-mcp-cli/doctor.js

@@ -8,7 +8,7 @@ import { podmanInfo, isSafeRefName } from "./writer-boundary.js";
 import { containedBuiltinSkills, containedProfileRefused } from "./writer-lifecycle.js";
 import { readWriterState, writerAcceptanceCurrent, writerName, writerPaths } from "./writer-state.js";
 import { LEASE_DIRECTORY } from "./writer-lease.js";
-import { loadConfig } from "./config.js";
+import { ConfigError, loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
@@ -423,8 +423,13 @@ export async function runDoctor(dependencies = {}) {
             checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
         else if (isUnreadable(error))
             checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
-        else
-            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+        else {
+            // Locations name the offending field; an error without one, or at the root, keeps the plain subject.
+            const locations = error instanceof ConfigError ? error.locations : [];
+            for (const location of locations.length ? locations : [""]) {
+                checks.push(failure("config_invalid", location ? `configuration:${location}` : "configuration", "fix configuration using the documented schema"));
+            }
+        }
     }
     if (config) {
         for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 ## Unreleased
 
+## 0.13.1 — 2026-10-29
+
+Patch release under ADR 0003 with an unchanged MCP contract. It ships the
+fixes after 0.13.0: Doctor names where the configuration schema rejects a
+file ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)),
+read-only confinement of Pi's agent directory
+([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)), a writer
+added without `--base` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)),
+stale waiter-lock reclamation in the wake hook
+([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)) and
+per-writer reconcile failures
+([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)). Setup
+reports change for a broken kept writer: it now carries its own code on its
+target instead of `writer_reconcile_failed`. `npm audit` still reports
+`undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release, now with
+eight advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading follows [Installation](docs/installation.md#upgrade); writers must be
+accepted again after the upgrade, as after every release.
+
+### Changed
+
+- Doctor's `config_invalid` names where the schema rejects the configuration:
+  one check per issue location (at most five) with the subject
+  `configuration:<location>`, for example
+  `configuration:executionProfiles.review.default`. Locations hold only schema
+  field names, aliases and array indexes; an unknown key that is not a schema
+  field name, and any other key that is not a valid alias, is shown as
+  `<key>`, and values and messages are never reported. An error without a
+  location keeps the subject `configuration`
+  ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)).
+
+### Added
+
+- Issue forms for bug reports, change proposals and maintenance tasks, and a
+  pull request template, written so that a person or a coding agent can carry
+  an issue out and a reviewer can check it
+  ([#178](https://github.com/plagor44-ux/pi-session-mcp/issues/178)).
+
+### Fixed
+
+- Security, in the lockfile only, development path: `@hono/node-server`
+  2.1.1 → 2.1.5 (via MCP Inspector; GHSA-rmxm-3fg6-px4f). Still open:
+  `undici` 8.10.2 in the production path, pinned exactly by Pi SDK 1.4.0, now
+  with eight advisories (GHSA-4qv8-2p9j-2685, GHSA-f72v-6w45-q472,
+  GHSA-xjj6-f33q-929c, GHSA-4w7w-5xrc-9h26, GHSA-2m5v-pch6-74hx,
+  GHSA-qrxm-fqhp-jwvm, GHSA-9fm3-97px-rjf6, GHSA-55wc-3pg8-jfw6), so
+  `npm audit` still reports it
+  ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+- Writer reconciliation reports a kept writer that fails, for example with
+  a missing wrapper after a crash during provisioning, on that writer's
+  target with its own code (`writer_state_invalid`) and still reconciles the
+  other writers. Only failures of shared setup state (configuration,
+  ownership) end the whole step with `writer_reconcile_failed`
+  ([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)).
+- Wake hook: reclaiming a stale waiter lock is serialized by an exclusive
+  `<lock>.reclaim` guard, and the lock is judged again while holding it. Two
+  waiters that both saw the same stale lock can no longer both take the turn
+  and send a duplicate wake reminder
+  ([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)).
+- Read-only confinement protects Pi's agent directory (`~/.pi/agent`, or
+  `PI_CODING_AGENT_DIR`) and, for a symlinked configuration file, its target's
+  directory: a skill directory that equals or contains either contributes only
+  the skill file as a read root. Before, a skill file placed directly in the
+  agent directory made `auth.json` readable. The real file of a symlinked skill
+  file is now a read root too, so the model can read a skill it was given
+  ([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)).
+- Setup provisions a writer added without `--base` (for example by raising
+  `--writers`) on the workspace's recorded default base, as finish and recreate
+  already did. Before, it landed on `origin/HEAD` and default starts never
+  leased it. A recorded base that is the repository default still provisions
+  from `origin/HEAD` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)).
+
 ## 0.13.0 — 2026-10-28
 
 Minor release under ADR 0003 for

package/CONTRIBUTING.md

@@ -42,7 +42,14 @@ ones:
 Pull requests are limited to collaborators. If you are not a collaborator and
 want to contribute a fix, open an issue that describes it.
 
-- Keep a pull request to one focused change, and say which issue it addresses.
+Issues use the forms in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/):
+bug report, change proposal or maintenance task. Each asks for acceptance
+criteria and a way to verify them, so that a person or a coding agent can carry
+the issue out and a reviewer can check it. Pull requests use
+[`.github/pull_request_template.md`](.github/pull_request_template.md).
+
+- Keep a pull request to one focused change, and name every issue it addresses
+  with its own closing keyword (`Closes #12. Closes #13.`).
 - Run the checks above and `npm audit` before opening it.
 - Describe what you verified and how. State only what was run: provider-free
   tests do not establish live client or model behavior.

package/README.md

@@ -30,10 +30,12 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.13.0**.
+The package version is **0.13.1**.
 
 [Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 
+Every read-only profile reads only inside its workspace and the directories of its selected skills, and a read-only profile on Linux can opt into a bubblewrap shell without network, home or host writes (`shell: "sandboxed"`, [ADR 0013](docs/adr/0013-hardened-read-only-profiles.md)).
+
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
 - **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
@@ -113,7 +115,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 ```
 
 - A workspace alias maps to a directory. Clients can select aliases only.
-- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
+- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`. A read-only profile can add `shell: "sandboxed"` on Linux.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
 - An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
 - An optional top-level `"events": { "delivery": "spool" }` turns on content-free turn events, so that a Claude Code hook can wake the controller when a turn ends instead of polling. It is off by default and changes nothing for Codex. See [Wake the controller](docs/installation.md#wake-the-controller-claude-code).

package/dist/config.d.ts

@@ -4,8 +4,18 @@ import { type WorkspaceModeEntry } from "./execution-modes.js";
 export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level" | "invalid_execution_modes" | "invalid_event_delivery";
 export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
-    constructor(code: ConfigErrorCode);
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    readonly locations: readonly string[];
+    constructor(code: ConfigErrorCode, locations?: readonly string[]);
 }
+export declare const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export declare function issueLocations(issues: readonly z.core.$ZodIssue[]): string[];
 export declare const configSchema: z.ZodObject<{
     events: z.ZodOptional<z.ZodObject<{
         delivery: z.ZodEnum<{

package/dist/config.js

@@ -72,12 +72,31 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    constructor(code, locations = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
     }
 }
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -151,7 +170,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
             const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues));
         }
         throw error;
     }

package/dist/confined-tools.d.ts

@@ -7,6 +7,7 @@ export declare const CONFINED_TOOL_NAMES: readonly string[];
  * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
  * A skill directory that equals or contains a protected path (the operator's home, the configuration
  * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
  */
 export declare function allowedReadRoots(workspace: string, skills: readonly Skill[], protectedPaths?: readonly string[]): Promise<string[]>;
 /**

package/dist/confined-tools.js

@@ -32,13 +32,17 @@ function isWithin(path, root) {
  * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
  * A skill directory that equals or contains a protected path (the operator's home, the configuration
  * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
  */
 export async function allowedReadRoots(workspace, skills, protectedPaths = []) {
     const roots = new Set([await realpath(workspace)]);
     const protectedReal = await Promise.all(protectedPaths.map((path) => canonical(path)));
     for (const skill of skills) {
-        const directory = await realpath(dirname(skill.filePath));
-        roots.add(protectedReal.some((path) => isWithin(path, directory)) ? await realpath(skill.filePath) : directory);
+        const directory = await realpath(dirname(skill.filePath)), file = await canonical(skill.filePath);
+        const root = protectedReal.some((path) => isWithin(path, directory)) ? file : directory;
+        roots.add(root);
+        if (!isWithin(file, root))
+            roots.add(file);
     }
     return [...roots];
 }

package/dist/doctor.js

@@ -8,7 +8,7 @@ import { podmanInfo, isSafeRefName } from "./writer-boundary.js";
 import { containedBuiltinSkills, containedProfileRefused } from "./writer-lifecycle.js";
 import { readWriterState, writerAcceptanceCurrent, writerName, writerPaths } from "./writer-state.js";
 import { LEASE_DIRECTORY } from "./writer-lease.js";
-import { loadConfig } from "./config.js";
+import { ConfigError, loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
@@ -423,8 +423,13 @@ export async function runDoctor(dependencies = {}) {
             checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
         else if (isUnreadable(error))
             checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
-        else
-            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+        else {
+            // Locations name the offending field; an error without one, or at the root, keeps the plain subject.
+            const locations = error instanceof ConfigError ? error.locations : [];
+            for (const location of locations.length ? locations : [""]) {
+                checks.push(failure("config_invalid", location ? `configuration:${location}` : "configuration", "fix configuration using the documented schema"));
+            }
+        }
     }
     if (config) {
         for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {

package/dist/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { stdoutGuard } from "./stdout-guard-install.js";
+import { realpath } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
 import { RoutingPiSessionAdapter, WriterRelayAdapter } from "./writer-relay.js";
@@ -47,10 +48,13 @@ async function main() {
                 spool = TurnEventSpool.open(directory, { diagnostic: writeDiagnostic });
         }
         const events = spool;
+        // The configuration directory must never become readable through a skill directory: the directory
+        // named by the variable and, for a symlinked configuration file, the directory of its target.
+        // loadConfig has read the file, so the variable is set and the path exists.
+        const configFile = resolve(process.env.PI_SESSION_MCP_CONFIG);
         const hostAdapter = new SdkPiSessionAdapter({
             diagnosticSink: writeDiagnostic,
-            // The configuration directory must never become readable through a skill directory.
-            ...(process.env.PI_SESSION_MCP_CONFIG === undefined || process.env.PI_SESSION_MCP_CONFIG === "" ? {} : { protectedReadPaths: [dirname(resolve(process.env.PI_SESSION_MCP_CONFIG))] }),
+            protectedReadPaths: [dirname(configFile), dirname(await realpath(configFile))],
         });
         const relay = guardPath === undefined;
         const adapter = relay ? new RoutingPiSessionAdapter(hostAdapter, new WriterRelayAdapter({

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

@@ -210,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-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 };
+}