pi-session-mcp 0.11.9 → 0.12.0

package/dist/doctor.js

@@ -6,6 +6,7 @@ import { createProcessRunner } from "./setup-process.js";
 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 { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
@@ -31,7 +32,7 @@ async function readPrefix(path, maxBytes) {
     }
 }
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_not_ready", "writer_dirty", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_base_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_lease_directory", "writer_not_ready", "writer_not_migrated", "writer_off_default_base", "writer_dirty", "writer_git_identity_missing", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -147,7 +148,7 @@ async function hasGitfilePointer(fs, workspace) {
         return false;
     }
 }
-async function defaultEventSpoolRoot(path) {
+async function defaultRootInfo(path) {
     try {
         const info = await lstat(path);
         return { isDirectory: info.isDirectory(), uid: info.uid, mode: info.mode };
@@ -158,6 +159,30 @@ async function defaultEventSpoolRoot(path) {
         throw error;
     }
 }
+/**
+ * Offline check of the host-only writer lease directory. A missing directory is fine because the
+ * first lease creates it. An existing entry must be a real directory of the current user with mode
+ * 0700: the rule `acquireWriterLease` applies before it opens a lease file. Nothing is created,
+ * repaired or read, and no path or lease file name appears in the report.
+ */
+async function writerLeaseCheck(home, probe, uid) {
+    let info;
+    try {
+        info = await probe(join(home, ...LEASE_DIRECTORY));
+    }
+    catch {
+        return failure("writer_lease_directory", "writer lease", "grant access to the writer lease directory");
+    }
+    if (info === undefined)
+        return undefined;
+    // Lease files must keep their inodes: a moved or recreated directory would let a second holder in.
+    if (!info.isDirectory)
+        return failure("writer_lease_directory", "writer lease", "close every writer session and setup run, then replace the entry with a private directory owned by the current user");
+    if ((uid !== undefined && info.uid !== uid) || (info.mode & 0o7777) !== 0o700) {
+        return failure("writer_lease_directory", "writer lease", "repair the lease directory in place (owner and chmod 700); never move or delete it or its lock files");
+    }
+    return ok("writer_lease_directory", "writer lease");
+}
 /**
  * Offline check of the event spool's runtime directories, run only when event delivery is enabled.
  * Nothing is created or repaired, and no path appears in the report. A missing runtime directory
@@ -208,6 +233,44 @@ async function defaultWriterRuntime() {
             }
         } };
 }
+async function writerGitIdentity(clone) {
+    try {
+        const handle = await open(join(clone, ".git", "config"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65_536)
+                return false;
+            const buffer = Buffer.alloc(65_536);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if ((await handle.stat()).size > 65_536)
+                return false;
+            let user = false, name = false, email = false;
+            for (const line of buffer.subarray(0, bytesRead).toString("utf8").split("\n")) {
+                const section = /^\s*\[([^\]]+)\]/.exec(line);
+                if (section) {
+                    user = section[1].trim().toLowerCase() === "user";
+                    continue;
+                }
+                if (!user)
+                    continue;
+                const key = /^\s*(name|email)\s*=\s*(.*?)\s*$/i.exec(line);
+                if (!key || !key[2] || /^(?:""|[#;])/.test(key[2]))
+                    continue;
+                if (key[1].toLowerCase() === "name")
+                    name = true;
+                else
+                    email = true;
+            }
+            return name && email;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
 async function writerDirty(clone, state) {
     try {
         const git = join(clone, ".git");
@@ -280,6 +343,7 @@ async function writerDirty(clone, state) {
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
+    const home = dependencies.home ?? homedir();
     const checks = [];
     let metadata;
     try {
@@ -418,9 +482,13 @@ export async function runDoctor(dependencies = {}) {
         let runtime;
         let rawConfig, rawConfigLoaded = false, rawConfigReadable = false;
         let availableBuiltinSkills = new Set();
+        const offDefaultBase = new Map();
         for (const [alias, entry] of config.workspaceModes) {
             if (entry.mode !== "container" || !entry.container)
                 continue;
+            checks.push(entry.container.base === undefined
+                ? warning("workspace_base_unset", alias, `record the workspace default base with pi-session-mcp-setup --repo ${alias} --base <branch> --apply`)
+                : ok("workspace_base_unset", alias));
             if (!rawConfigLoaded) {
                 rawConfigLoaded = true;
                 try {
@@ -445,7 +513,7 @@ export async function runDoctor(dependencies = {}) {
                     checks.push(ok("container_profile_refused", alias));
             }
             for (let index = 1; index <= entry.container.writers; index++) {
-                const name = writerName(alias, index), home = dependencies.home ?? homedir(), paths = writerPaths(home, name);
+                const name = writerName(alias, index), paths = writerPaths(home, name);
                 const remediation = `run pi-session-mcp-setup --repo ${alias} --apply, or --writer ${name} --recreate --apply`;
                 let state, ready = false;
                 try {
@@ -459,6 +527,11 @@ export async function runDoctor(dependencies = {}) {
                 checks.push(ready ? ok("writer_not_ready", name) : failure("writer_not_ready", name, remediation));
                 if (!state)
                     continue;
+                checks.push(state.launch === "relay" ? ok("writer_not_migrated", name)
+                    : warning("writer_not_migrated", name, `run pi-session-mcp-setup --repo ${alias} --apply to migrate the writer to the relay`));
+                if (entry.container.base !== undefined && ready && state.base.ref !== `refs/heads/${entry.container.base}`) {
+                    offDefaultBase.set(alias, (offDefaultBase.get(alias) ?? 0) + 1);
+                }
                 checks.push(await writerDirty(paths.clone, state)
                     ? warning("writer_dirty", name, "collect writer work before resetting or recreating the writer") : ok("writer_dirty", name));
                 let bundles = false;
@@ -471,9 +544,18 @@ export async function runDoctor(dependencies = {}) {
                 catch (error) {
                     bundles = !isMissing(error);
                 }
+                checks.push(await writerGitIdentity(paths.clone) ? ok("writer_git_identity_missing", name)
+                    : warning("writer_git_identity_missing", name, "set user.name and user.email in the operator checkout, then reset the writer"));
                 checks.push(bundles ? warning("writer_uncollected_bundle", name, "collect or review outstanding writer bundles") : ok("writer_uncollected_bundle", name));
             }
         }
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container || entry.container.base === undefined)
+                continue;
+            const count = offDefaultBase.get(alias) ?? 0;
+            checks.push(count === 0 ? ok("writer_off_default_base", alias)
+                : warning("writer_off_default_base", alias, `${count} ${count === 1 ? "writer is" : "writers are"} off the workspace default base; finish each with pi-session-mcp-setup --writer <name> --finish --apply once its work is collected`));
+        }
     }
     if (config) {
         // This advisory check needs positive evidence, like the gitfile check: unreadable or
@@ -546,7 +628,10 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config?.eventDelivery === "spool")
-        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultEventSpoolRoot, dependencies.uid ?? process.getuid?.()));
+        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.()));
+    const lease = await writerLeaseCheck(home, dependencies.writerLeaseRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.());
+    if (lease)
+        checks.push(lease);
     if (config)
         checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));

package/dist/execution-modes.d.ts

@@ -6,13 +6,17 @@ export interface ContainerSettings {
     readonly profiles: readonly string[];
     readonly image: string;
     readonly network: "pasta" | "none";
-    readonly cache: "none" | "go";
+    readonly cache: "none" | "go" | "uv";
+    readonly tags: "none" | "reachable";
+    readonly base?: string;
 }
 export interface WorkspaceModeEntry {
     readonly mode: WorkspaceMode;
     readonly container?: ContainerSettings;
 }
 export declare const EXECUTION_MODES_FILE = "execution-modes.json";
+/** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
+export declare function isShortBranchName(value: string): boolean;
 export declare function executionModesPath(configPath: string): string;
 export declare const executionModesSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
@@ -37,7 +41,13 @@ export declare const executionModesSchema: z.ZodObject<{
         cache: z.ZodDefault<z.ZodEnum<{
             go: "go";
             none: "none";
+            uv: "uv";
         }>>;
+        tags: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            reachable: "reachable";
+        }>>;
+        base: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "mode">>;
 }, z.core.$strict>;
 type ModeProfile = {
@@ -46,5 +56,5 @@ type ModeProfile = {
 };
 export declare function resolveExecutionModes(raw: unknown, workspaceAliases: ReadonlySet<string>, profiles: ReadonlyMap<string, ModeProfile>): ReadonlyMap<string, WorkspaceModeEntry>;
 export declare function loadExecutionModes(configPath: string, workspaceAliases: ReadonlySet<string>, profiles: ReadonlyMap<string, ModeProfile>): Promise<ReadonlyMap<string, WorkspaceModeEntry>>;
-export declare function codingAllowed(entry: WorkspaceModeEntry): boolean;
+export declare function codingAllowed(entry: WorkspaceModeEntry, relay: boolean): boolean;
 export {};

package/dist/execution-modes.js

@@ -3,7 +3,16 @@ import { dirname, join } from "node:path";
 import { z } from "zod";
 import { ConfigError } from "./config.js";
 import { ImmutableMap } from "./execution-profile.js";
+import { isSafeRefName } from "./writer-boundary.js";
 export const EXECUTION_MODES_FILE = "execution-modes.json";
+/** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
+export function isShortBranchName(value) {
+    return value.length <= 200
+        && isSafeRefName(value)
+        && value !== "HEAD"
+        && !value.startsWith("refs/")
+        && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
+}
 export function executionModesPath(configPath) {
     return join(dirname(configPath), EXECUTION_MODES_FILE);
 }
@@ -17,7 +26,9 @@ const entrySchema = z.discriminatedUnion("mode", [
         profiles: z.array(z.string()).min(1),
         image: z.union([z.literal("node"), z.string().regex(/^[0-9a-f]{64}$/)]).default("node"),
         network: z.enum(["pasta", "none"]).default("pasta"),
-        cache: z.enum(["none", "go"]).default("none"),
+        cache: z.enum(["none", "go", "uv"]).default("none"),
+        tags: z.enum(["none", "reachable"]).default("none"),
+        base: z.string().refine(isShortBranchName).optional(),
     }).strict(),
 ]);
 export const executionModesSchema = z.object({
@@ -39,9 +50,10 @@ export function resolveExecutionModes(raw, workspaceAliases, profiles) {
                     throw new ConfigError("invalid_execution_modes");
                 }
             }
-            const { mode, ...settings } = entry;
+            const { mode, base, ...settings } = entry;
             entries.set(alias, Object.freeze({ mode, container: Object.freeze({
                     ...settings, profiles: Object.freeze([...settings.profiles]),
+                    ...(base === undefined ? {} : { base }),
                 }) }));
         }
         else {
@@ -66,6 +78,6 @@ export async function loadExecutionModes(configPath, workspaceAliases, profiles)
     }
     return resolveExecutionModes(raw, workspaceAliases, profiles);
 }
-export function codingAllowed(entry) {
-    return entry.mode === "unset" || entry.mode === "host";
+export function codingAllowed(entry, relay) {
+    return entry.mode === "unset" || entry.mode === "host" || (entry.mode === "container" && relay);
 }

package/dist/main.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { stdoutGuard } from "./stdout-guard-install.js";
 import { isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { RoutingPiSessionAdapter, WriterRelayAdapter } from "./writer-relay.js";
 import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { loadConfig } from "./config.js";
 import { EventSpoolError, TurnEventSpool } from "./event-spool.js";
@@ -45,13 +47,18 @@ async function main() {
                 spool = TurnEventSpool.open(directory, { diagnostic: writeDiagnostic });
         }
         const events = spool;
-        registry = new SessionRegistry(new SdkPiSessionAdapter({ diagnosticSink: writeDiagnostic }), config.workspaces, {
+        const hostAdapter = new SdkPiSessionAdapter({ diagnosticSink: writeDiagnostic });
+        const relay = guardPath === undefined;
+        const adapter = relay ? new RoutingPiSessionAdapter(hostAdapter, new WriterRelayAdapter({
+            home: homedir(), workspaceModes: config.workspaceModes, executionProfiles: config.executionProfiles,
+        }), config.workspaceModes) : hostAdapter;
+        registry = new SessionRegistry(adapter, config.workspaces, {
             ...(guardPath === undefined ? {} : { writerGuard: createWriterGuard(guardPath, config.workspaces) }),
             ...(events === undefined ? {} : {
                 onTurnTerminal: (event) => events.write({ kind: "turn_terminal", session: event.sessionId, turn: event.turnId, state: event.state, via: event.via }),
             }),
         });
-        handle = serveStdio(() => createServer(registry, config.workspaces, config.executionProfiles, config.defaultExecutionProfile, config.configuration, config.workspaceModes, delivery), {
+        handle = serveStdio(() => createServer(registry, config.workspaces, config.executionProfiles, config.defaultExecutionProfile, config.configuration, config.workspaceModes, delivery, relay), {
             transport: new StdioServerTransport(process.stdin, stdoutGuard.transportStdout),
             onerror: () => writeDiagnostic({ level: "error", event: "mcp_transport_error", stage: "transport", code: "mcp_transport_error" }),
         });

package/dist/override-lock.d.ts

@@ -32,3 +32,5 @@ export interface OverrideLock {
  * `override_lock_unavailable`.
  */
 export declare function acquireOverrideLock(overrideDirectory: string, options?: OverrideLockOptions): Promise<OverrideLock>;
+export declare function flockBinary(options: OverrideLockOptions): string | undefined;
+export declare function lockWithFlock(flockPath: string, lockFd: number, timeoutMs: number, signal: AbortSignal | undefined, nonBlocking?: boolean): Promise<void>;

package/dist/override-lock.js

@@ -72,7 +72,7 @@ export async function acquireOverrideLock(overrideDirectory, options = {}) {
         },
     };
 }
-function flockBinary(options) {
+export function flockBinary(options) {
     const trusted = options.isTrustedBinary ?? ((path) => isTrustedSystemBinary(path));
     return (options.flockCandidates ?? FLOCK_CANDIDATES).find((candidate) => trusted(candidate));
 }
@@ -86,7 +86,7 @@ async function openLockFile(lockPath, platform, timeoutMs, signal) {
         throw new OverrideLockError(error.message === "ownership_lock_busy" ? "override_lock_busy" : "override_lock_unavailable");
     }
 }
-function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
+export function lockWithFlock(flockPath, lockFd, timeoutMs, signal, nonBlocking = false) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -97,7 +97,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             // flock parses fractional seconds with the locale's decimal separator, so only whole
             // seconds go on the command line. The exact bound is the timer below, which stops flock.
             const wholeSeconds = String(Math.max(1, Math.ceil(timeoutMs / 1_000)));
-            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), "-w", wholeSeconds, "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
+            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), ...(nonBlocking ? ["-n"] : ["-w", wholeSeconds]), "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
         }
         catch {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -111,7 +111,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             catch { /* already gone */ }
         } };
         const cleanup = () => { clearTimeout(bound); signal?.removeEventListener("abort", stop); };
-        const bound = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+        const bound = nonBlocking ? undefined : setTimeout(() => { expired = true; stop(); }, timeoutMs);
         signal?.addEventListener("abort", stop, { once: true });
         locker.once("error", () => { cleanup(); reject(new OverrideLockError("override_lock_unavailable")); });
         locker.once("close", (code) => {

package/dist/pi-adapter.d.ts

@@ -3,6 +3,7 @@ export type { PermissionProfile };
 export type PiTurnOutcome = {
     status: "completed";
     assistantText: string;
+    truncated?: boolean;
 } | {
     status: "failed";
 } | {
@@ -18,7 +19,34 @@ export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);
 }
+export declare class WriterUnavailableError extends Error {
+    readonly reason: "none_ready" | "none_at_base" | "none_admitted";
+    readonly counts?: {
+        busy: number;
+        notAtBaseline: number;
+        settingsChanged: number;
+    } | undefined;
+    readonly code = "writer_unavailable";
+    constructor(reason: "none_ready" | "none_at_base" | "none_admitted", counts?: {
+        busy: number;
+        notAtBaseline: number;
+        settingsChanged: number;
+    } | undefined);
+}
 export interface PiSessionHandle {
+    readonly placement?: {
+        writer: string;
+        base: {
+            ref: string;
+            commit: string;
+        };
+    } | undefined;
+    readonly deadlines?: {
+        preflightMs?: number;
+        abortMs?: number;
+        cleanupMs?: number;
+    } | undefined;
+    isLost?(): boolean;
     readonly sdkSessionId: string;
     /** Only whitelisted, post-verified selection metadata may cross the adapter boundary. */
     readonly appliedSelection: PiAppliedSelection;
@@ -38,6 +66,8 @@ export interface PiSessionHandle {
 export interface PiSessionAdapter {
     create(input: {
         cwd: string;
+        workspace: string;
+        base?: string;
         executionProfile: ResolvedExecutionProfile;
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;

package/dist/pi-adapter.js

@@ -26,3 +26,14 @@ export class PiSessionCreationError extends Error {
         this.code = code;
     }
 }
+export class WriterUnavailableError extends Error {
+    reason;
+    counts;
+    code = "writer_unavailable";
+    constructor(reason, counts) {
+        super("No writer is available");
+        this.reason = reason;
+        this.counts = counts;
+        this.name = "WriterUnavailableError";
+    }
+}

package/dist/refusal-server.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-export type RefusalCode = "container_runtime_unavailable" | "writer_not_ready";
+export type RefusalCode = "container_runtime_unavailable" | "writer_not_ready" | "writer_busy" | "writer_fenced";
 export declare function serveRefusal(code: RefusalCode, io?: {
     stdin: Readable;
     stdout: Writable;

package/dist/refusal-server.js

@@ -5,10 +5,20 @@ import { PACKAGE_VERSION } from "./package-metadata.js";
 const messages = {
     container_runtime_unavailable: "Rootless Podman is not usable on this machine; this writer refuses all work.",
     writer_not_ready: "This writer is not ready; run pi-session-mcp-setup for its repository.",
+    writer_busy: "This writer is already leased; try another writer.",
+    writer_fenced: "Container absence could not be confirmed; this writer refuses all work.",
 };
 export async function serveRefusal(code, io) {
     const stdout = io?.stdout ?? (await import("./stdout-guard-install.js")).stdoutGuard.transportStdout;
-    serveStdio(() => {
+    const stdin = io?.stdin ?? process.stdin;
+    let finish;
+    const ended = new Promise((resolve) => { finish = resolve; });
+    stdin.once("end", finish);
+    stdin.once("close", finish);
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    for (const signal of signals)
+        process.once(signal, finish);
+    const handle = serveStdio(() => {
         const server = new McpServer({ name: "pi-session-mcp", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
         for (const name of ["pi_capabilities_get", "pi_session_start", "pi_session_list", "pi_session_get", "pi_session_prompt", "pi_session_abort", "pi_session_close", "pi_turn_get"]) {
             server.registerTool(name, { inputSchema: z.object({}).passthrough() }, () => {
@@ -18,7 +28,19 @@ export async function serveRefusal(code, io) {
         }
         return server;
     }, {
-        transport: new StdioServerTransport(io?.stdin ?? process.stdin, stdout),
+        transport: new StdioServerTransport(stdin, stdout),
         onerror: () => { process.stderr.write(JSON.stringify({ level: "error", event: "mcp_transport_error", stage: "transport", code: "mcp_transport_error" }) + "\n"); },
     });
+    try {
+        if (stdin.readableEnded || stdin.destroyed)
+            finish();
+        await ended;
+        await handle.close();
+    }
+    finally {
+        stdin.off("end", finish);
+        stdin.off("close", finish);
+        for (const signal of signals)
+            process.off(signal, finish);
+    }
 }

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
-import { type ConfigurationMetadata } from "./config.js";
+import type { ConfigurationMetadata } from "./config.js";
 import { type WorkspaceModeEntry } from "./execution-modes.js";
 import { type ConfiguredExecutionProfile } from "./execution-profile.js";
 import { type SessionRegistry } from "./session-registry.js";
-export declare function createServer(registry: SessionRegistry, workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, defaultExecutionProfile: string, configuration: ConfigurationMetadata, workspaceModes?: ReadonlyMap<string, WorkspaceModeEntry>, eventDelivery?: "spool" | "off"): McpServer;
+export declare function createServer(registry: SessionRegistry, workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, defaultExecutionProfile: string, configuration: ConfigurationMetadata, workspaceModes?: ReadonlyMap<string, WorkspaceModeEntry>, eventDelivery?: "spool" | "off", relay?: boolean): McpServer;

package/dist/server.js

@@ -2,55 +2,11 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import packageMetadata from "../package.json" with { type: "json" };
 import { projectCapabilities } from "./capabilities.js";
-import { CONFIGURATION_FINGERPRINT_PATTERN, RELOAD_POLICY } from "./config.js";
-import { codingAllowed } from "./execution-modes.js";
-import { PiSessionCreationError } from "./pi-adapter.js";
-import { ALIAS_PATTERN, toResolvedExecutionProfile } from "./execution-profile.js";
+import { codingAllowed, isShortBranchName } from "./execution-modes.js";
+import { PiSessionCreationError, WriterUnavailableError } from "./pi-adapter.js";
+import { toResolvedExecutionProfile } from "./execution-profile.js";
 import { RegistryError } from "./session-registry.js";
-const thinkingLevelSchema = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
-const viewSchema = z.object({
-    id: z.string(), workspace: z.string(), executionProfile: z.string(), profile: z.enum(["read-only", "coding"]),
-    provider: z.string(), model: z.string(), thinkingLevel: thinkingLevelSchema,
-    state: z.enum(["idle", "running", "failed", "closing", "closed"]), createdAt: z.string(), updatedAt: z.string(),
-    lastError: z.string().optional(),
-});
-const aliasSchema = z.string().regex(ALIAS_PATTERN);
-// Input IDs: tools/list keeps `format: "uuid"` but omits zod's long repeated `pattern`; the
-// server still validates with the unchanged `z.string().uuid()`, so accepted values and issues are identical.
-const idInputSchema = z.string().meta({ format: "uuid" }).pipe(z.string().uuid());
-const successSchema = z.object({ ok: z.literal(true), session: viewSchema });
-const turnBase = { turnId: z.string().uuid(), sessionId: z.string().uuid(), startedAt: z.string(), updatedAt: z.string() };
-const turnSchema = z.discriminatedUnion("state", [
-    z.object({ ...turnBase, state: z.literal("running") }),
-    z.object({ ...turnBase, state: z.literal("completed"), completedAt: z.string(), assistantText: z.string(), truncated: z.boolean() }),
-    z.object({ ...turnBase, state: z.literal("failed"), completedAt: z.string(), error: z.object({ code: z.literal("turn_failed"), message: z.literal("Pi turn failed") }) }),
-    z.object({ ...turnBase, state: z.literal("aborted"), completedAt: z.string() }),
-]);
-const promptSuccessSchema = z.object({ ok: z.literal(true), session: viewSchema, turn: turnSchema });
-const turnSuccessSchema = z.object({ ok: z.literal(true), turn: turnSchema });
-const listSchema = z.object({ ok: z.literal(true), sessions: z.array(viewSchema) });
-const errorSchema = z.object({ ok: z.literal(false), error: z.object({ code: z.string(), message: z.string() }) });
-const capabilitiesSchema = z.object({
-    ok: z.literal(true),
-    server: z.object({ name: z.literal(packageMetadata.name), version: z.literal(packageMetadata.version) }).strict(),
-    configuration: z.object({
-        fingerprint: z.string().regex(CONFIGURATION_FINGERPRINT_PATTERN),
-        reloadPolicy: z.literal(RELOAD_POLICY),
-    }).strict(),
-    events: z.object({ delivery: z.enum(["spool", "off"]) }).strict(),
-    workspaces: z.array(z.object({ alias: aliasSchema, mode: z.enum(["unset", "host", "container", "read-only"]) }).strict()),
-    executionProfiles: z.array(z.object({
-        alias: aliasSchema,
-        default: z.boolean(),
-        permissionProfile: z.enum(["read-only", "coding"]),
-        provider: z.string(),
-        model: z.string(),
-        thinkingLevel: thinkingLevelSchema,
-        extensions: z.array(z.string()),
-        grantedExtensionTools: z.array(z.string()),
-        skills: z.array(aliasSchema),
-    }).strict()),
-}).strict();
+import { aliasSchema, idInputSchema, successSchema, promptSuccessSchema, turnSuccessSchema, listSchema, errorSchema, capabilitiesSchema } from "./tool-schemas.js";
 function result(value, isError = false) {
     return { content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value, ...(isError ? { isError: true } : {}) };
 }
@@ -59,11 +15,14 @@ async function safe(action) {
         return result(await action());
     }
     catch (error) {
+        if (error instanceof WriterUnavailableError) {
+            return result({ ok: false, error: { code: error.code, message: error.message, reason: error.reason, ...(error.counts === undefined ? {} : { counts: error.counts }) } }, true);
+        }
         const known = error instanceof RegistryError || error instanceof PiSessionCreationError;
         return result({ ok: false, error: { code: known ? error.code : "internal_error", message: known ? error.message : "Operation failed" } }, true);
     }
 }
-export function createServer(registry, workspaces, executionProfiles, defaultExecutionProfile, configuration, workspaceModes = new Map(), eventDelivery = "off") {
+export function createServer(registry, workspaces, executionProfiles, defaultExecutionProfile, configuration, workspaceModes = new Map(), eventDelivery = "off", relay = false) {
     const server = new McpServer({ name: packageMetadata.name, version: packageMetadata.version }, { capabilities: { tools: {} } });
     server.registerTool("pi_capabilities_get", {
         description: "List configured workspace and execution-profile aliases. This reports configured intent, not provider or runtime availability. Call once at the start of a run.",
@@ -73,17 +32,23 @@ export function createServer(registry, workspaces, executionProfiles, defaultExe
     }, () => result(projectCapabilities(workspaces, executionProfiles, configuration, workspaceModes, eventDelivery)));
     server.registerTool("pi_session_start", {
         description: "Start a managed embedded Pi session for a configured workspace alias.",
-        inputSchema: z.object({ workspace: aliasSchema, executionProfile: aliasSchema.optional() }).strict(), outputSchema: z.union([successSchema, errorSchema]),
+        inputSchema: z.object({ workspace: aliasSchema, executionProfile: aliasSchema.optional(), base: z.string().refine(isShortBranchName).optional() }).strict(), outputSchema: z.union([successSchema, errorSchema]),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, ({ workspace, executionProfile }) => safe(async () => {
+    }, ({ workspace, executionProfile, base }) => safe(async () => {
         const alias = executionProfile ?? defaultExecutionProfile;
         const configured = executionProfiles.get(alias);
         if (!configured)
             throw new RegistryError("unknown_execution_profile");
-        if (configured.permissionProfile === "coding" && !codingAllowed(workspaceModes.get(workspace) ?? { mode: "unset" })) {
+        if (!workspaces.has(workspace))
+            throw new RegistryError("unknown_workspace");
+        const mode = workspaceModes.get(workspace) ?? { mode: "unset" };
+        if (base !== undefined && (configured.permissionProfile !== "coding" || mode.mode !== "container")) {
+            throw new RegistryError("base_not_applicable");
+        }
+        if (configured.permissionProfile === "coding" && !codingAllowed(mode, relay)) {
             throw new RegistryError("workspace_mode_forbids_coding");
         }
-        return { ok: true, session: await registry.start(workspace, toResolvedExecutionProfile(configured)) };
+        return { ok: true, session: await registry.start(workspace, toResolvedExecutionProfile(configured), base === undefined ? {} : { base }) };
     }));
     server.registerTool("pi_session_list", {
         description: "List local Pi sessions and their state.", inputSchema: z.object({}).strict(), outputSchema: z.union([listSchema, errorSchema]),

package/dist/session-registry.d.ts

@@ -11,6 +11,11 @@ export interface SessionView {
     provider: string;
     model: string;
     thinkingLevel: ThinkingLevel;
+    writer?: string;
+    base?: {
+        ref: string;
+        commit: string;
+    };
     state: SessionState;
     createdAt: string;
     updatedAt: string;
@@ -41,7 +46,7 @@ export interface PromptResult {
     session: SessionView;
     turn: TurnView;
 }
-export type RegistryErrorCode = "unknown_workspace" | "unknown_session" | "session_running" | "prompt_rejected" | "prompt_timeout" | "abort_failed" | "abort_timeout" | "unknown_turn" | "unknown_execution_profile" | "workspace_mode_forbids_coding" | "writer_uncollected" | "writer_busy" | "server_stopping";
+export type RegistryErrorCode = "writer_session_lost" | "base_not_applicable" | "unknown_workspace" | "unknown_session" | "session_running" | "prompt_rejected" | "prompt_timeout" | "abort_failed" | "abort_timeout" | "unknown_turn" | "unknown_execution_profile" | "workspace_mode_forbids_coding" | "writer_uncollected" | "writer_busy" | "server_stopping";
 export declare class RegistryError extends Error {
     readonly code: RegistryErrorCode;
     constructor(code: RegistryErrorCode);
@@ -84,7 +89,9 @@ export declare class SessionRegistry {
     private stopping;
     private readonly shutdownController;
     constructor(adapter: PiSessionAdapter, workspaces: ReadonlyMap<string, string>, options?: SessionRegistryOptions);
-    start(workspace: string, executionProfile: ResolvedExecutionProfile): Promise<SessionView>;
+    start(workspace: string, executionProfile: ResolvedExecutionProfile, options?: {
+        base?: string;
+    }): Promise<SessionView>;
     private guardedCreate;
     private createAndRegister;
     list(): SessionView[];