pi-session-mcp 0.8.3 → 0.12.0

package/dist/refusal-server.js

@@ -0,0 +1,46 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
+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;
+    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() }, () => {
+                const value = { ok: false, error: { code, message: messages[code] } };
+                return { isError: true, structuredContent: value, content: [{ type: "text", text: JSON.stringify(value) }] };
+            });
+        }
+        return server;
+    }, {
+        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/sdk-pi-adapter.js

@@ -424,11 +424,13 @@ export class SdkPiSessionAdapter {
         }
         const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
         const mcpTools = await this.connectMcpTools(input);
-        const tools = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools);
-        if (!tools) {
+        const grantedTools = executionProfile.grantedExtensionTools ?? [];
+        const composed = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools, grantedTools);
+        if (!composed.ok) {
             await mcpTools.close();
-            throw this.failure(executionProfile, "extension_load", "extension_tool_conflict");
+            throw this.failure(executionProfile, "extension_load", composed.code);
         }
+        const tools = composed.tools;
         let sessionRuntime;
         try {
             sessionRuntime = await withCreationDeadline(() => this.extensionSdk.createRuntime(async ({ sessionManager }) => ({
@@ -472,8 +474,10 @@ 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));
-            if (!recheck || recheck.length !== tools.length || recheck.some((name, index) => name !== tools[index]))
+            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services), grantedTools);
+            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]))
                 conflict = true;
         }
         catch (error) {
@@ -486,7 +490,7 @@ 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);
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills, grantedTools);
     }
     async loadSkills(input) {
         try {
@@ -577,7 +581,7 @@ 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 = []) {
+    toolCheck = "exact", skills = [], requiredTools = []) {
         try {
             this.checkResources(session.resourceLoader, skills, executionProfile, "postcheck");
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
@@ -586,13 +590,16 @@ export class SdkPiSessionAdapter {
             if (session.thinkingLevel !== executionProfile.thinkingLevel) {
                 throw this.failure(executionProfile, "postcheck", "thinking_level_unavailable");
             }
-            if (toolMismatch !== undefined) {
+            if (toolMismatch !== undefined || requiredTools.length > 0) {
                 const active = new Set(session.getActiveToolNames());
+                if (requiredTools.some((name) => !active.has(name))) {
+                    throw this.failure(executionProfile, "postcheck", "extension_tool_missing");
+                }
                 const allowed = new Set(tools);
                 const mismatch = toolCheck === "subset"
                     ? [...active].some((name) => !allowed.has(name))
                     : active.size !== tools.length || tools.some((name) => !active.has(name));
-                if (mismatch) {
+                if (mismatch && toolMismatch !== undefined) {
                     throw this.failure(executionProfile, "postcheck", toolMismatch);
                 }
             }

package/dist/server.d.ts

@@ -1,5 +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): 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,49 +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 { 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);
-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(),
-    workspaces: z.array(z.object({ alias: aliasSchema }).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()),
-        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 } : {}) };
 }
@@ -53,51 +15,63 @@ 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) {
+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.",
+        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.",
         inputSchema: z.object({}).strict(),
         outputSchema: capabilitiesSchema,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, () => result(projectCapabilities(workspaces, executionProfiles, configuration)));
+    }, () => 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");
-        return { ok: true, session: await registry.start(workspace, toResolvedExecutionProfile(configured)) };
+        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), 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]),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, () => safe(() => ({ ok: true, sessions: registry.list() })));
     server.registerTool("pi_session_get", {
-        description: "Get one local Pi session by ID.", inputSchema: z.object({ sessionId: z.string().uuid() }).strict(), outputSchema: z.union([successSchema, errorSchema]),
+        description: "Get one local Pi session by ID.", inputSchema: z.object({ sessionId: idInputSchema }).strict(), outputSchema: z.union([successSchema, errorSchema]),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, ({ sessionId }) => safe(() => ({ ok: true, session: registry.get(sessionId) })));
     server.registerTool("pi_session_prompt", {
-        description: "Accept a prompt after Pi preflight and run the turn in the background.", inputSchema: z.object({ sessionId: z.string().uuid(), prompt: z.string().min(1).max(100_000) }).strict(), outputSchema: z.union([promptSuccessSchema, errorSchema]),
+        description: "Accept a prompt after Pi preflight and run the turn in the background. Returns a running turn at once; poll pi_turn_get with pauses.", inputSchema: z.object({ sessionId: idInputSchema, prompt: z.string().min(1).max(100_000) }).strict(), outputSchema: z.union([promptSuccessSchema, errorSchema]),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, ({ sessionId, prompt }) => safe(async () => ({ ok: true, ...(await registry.prompt(sessionId, prompt)) })));
     server.registerTool("pi_session_abort", {
-        description: "Abort a running Pi turn; idle sessions are unchanged.", inputSchema: z.object({ sessionId: z.string().uuid() }).strict(), outputSchema: z.union([successSchema, errorSchema]),
+        description: "Abort a running Pi turn; idle sessions are unchanged.", inputSchema: z.object({ sessionId: idInputSchema }).strict(), outputSchema: z.union([successSchema, errorSchema]),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, ({ sessionId }) => safe(async () => ({ ok: true, session: await registry.abort(sessionId) })));
     server.registerTool("pi_session_close", {
-        description: "Abort if needed, dispose, and remove a Pi session.", inputSchema: z.object({ sessionId: z.string().uuid() }).strict(), outputSchema: z.union([successSchema, errorSchema]),
+        description: "Abort if needed, dispose, and remove a Pi session. Idempotent; close every started session.", inputSchema: z.object({ sessionId: idInputSchema }).strict(), outputSchema: z.union([successSchema, errorSchema]),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, ({ sessionId }) => safe(async () => ({ ok: true, session: await registry.close(sessionId) })));
     server.registerTool("pi_turn_get", {
-        description: "Get the normalized observable result of a Pi turn.", inputSchema: z.object({ sessionId: z.string().uuid(), turnId: z.string().uuid() }).strict(), outputSchema: z.union([turnSuccessSchema, errorSchema]),
+        description: "Get the normalized observable result of a Pi turn. completed, failed and aborted are terminal and never change: read a terminal turn once. completed is not task success.", inputSchema: z.object({ sessionId: idInputSchema, turnId: idInputSchema }).strict(), outputSchema: z.union([turnSuccessSchema, errorSchema]),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, ({ sessionId, turnId }) => safe(() => ({ ok: true, turn: registry.getTurn(sessionId, turnId) })));
     return server;

package/dist/session-registry.d.ts

@@ -1,3 +1,4 @@
+import type { WriterGuard } from "./writer-guard.js";
 import { type PiSessionAdapter } from "./pi-adapter.js";
 import type { PermissionProfile, ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 export type SessionState = "idle" | "running" | "failed" | "closing" | "closed";
@@ -10,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;
@@ -40,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" | "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);
@@ -52,11 +58,23 @@ export declare const PREFLIGHT_DEADLINE_MS = 5000;
 export declare const ABORT_DEADLINE_MS = 5000;
 export declare const CLOSE_CLEANUP_DEADLINE_MS = 5000;
 export declare const SHUTDOWN_DEADLINE_MS = 12000;
+/**
+ * Content-free notice that a published turn became terminal. `via` is `close` when `close` marked a
+ * still running turn aborted, otherwise `registry`. The registry read model stays the only truth.
+ */
+export interface TurnTerminalNotice {
+    sessionId: string;
+    turnId: string;
+    state: Exclude<TurnState, "running">;
+    via: "registry" | "close";
+}
 export interface SessionRegistryOptions {
     preflightDeadlineMs?: number;
     abortDeadlineMs?: number;
     closeCleanupDeadlineMs?: number;
     shutdownDeadlineMs?: number;
+    writerGuard?: WriterGuard;
+    onTurnTerminal?: (event: TurnTerminalNotice) => void;
 }
 export declare class SessionRegistry {
     private readonly adapter;
@@ -65,10 +83,16 @@ export declare class SessionRegistry {
     private readonly closed;
     private readonly pendingStarts;
     private readonly options;
+    private readonly writerGuard;
+    private readonly onTurnTerminal;
+    private readonly codingAdmissions;
     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[];
     get(id: string): SessionView;
@@ -81,6 +105,12 @@ export declare class SessionRegistry {
     private verifySelection;
     private completeTurn;
     private failTurn;
+    /**
+     * Called once per terminal transition, after the turn is final. Only a published turn is reported:
+     * a preflight that was rejected, timed out or restored never had a public turn id. A throwing
+     * listener is swallowed and can neither change registry state nor reach a caller.
+     */
+    private notifyTerminal;
     /**
      * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
      * execution start, update and end) advances this turn, never another turn or the session.

package/dist/session-registry.js

@@ -1,7 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { PiSessionCreationError } from "./pi-adapter.js";
 const REGISTRY_ERROR_MESSAGES = {
+    writer_session_lost: "Writer session was lost",
+    base_not_applicable: "Base is only applicable to coding sessions on container workspaces",
     unknown_workspace: "Unknown workspace",
+    writer_uncollected: "Writer is not at its collected baseline",
+    writer_busy: "Writer already has an open coding session",
+    workspace_mode_forbids_coding: "The workspace's execution mode does not allow coding sessions on this server",
     unknown_session: "Unknown session",
     session_running: "Session already has a running turn",
     prompt_rejected: "Pi rejected the prompt during preflight",
@@ -43,21 +48,28 @@ export class SessionRegistry {
     closed = new Map();
     pendingStarts = new Set();
     options;
+    writerGuard;
+    onTurnTerminal;
+    codingAdmissions = new Map();
     stopping = false;
     shutdownController = new AbortController();
     constructor(adapter, workspaces, options = {}) {
         this.adapter = adapter;
         this.workspaces = workspaces;
+        this.writerGuard = options.writerGuard;
+        this.onTurnTerminal = options.onTurnTerminal;
         this.options = { preflightDeadlineMs: options.preflightDeadlineMs ?? PREFLIGHT_DEADLINE_MS, abortDeadlineMs: options.abortDeadlineMs ?? ABORT_DEADLINE_MS, closeCleanupDeadlineMs: options.closeCleanupDeadlineMs ?? CLOSE_CLEANUP_DEADLINE_MS, shutdownDeadlineMs: options.shutdownDeadlineMs ?? SHUTDOWN_DEADLINE_MS };
     }
-    async start(workspace, executionProfile) {
+    async start(workspace, executionProfile, options = {}) {
         if (this.stopping)
             throw new RegistryError("server_stopping");
         const cwd = this.workspaces.get(workspace);
         if (!cwd)
             throw new RegistryError("unknown_workspace");
         // Track registration and orphan cleanup too, not just the raw adapter promise.
-        const start = this.createAndRegister(cwd, workspace, executionProfile);
+        const start = this.writerGuard && executionProfile.permissionProfile === "coding"
+            ? this.guardedCreate(cwd, workspace, executionProfile, options)
+            : this.createAndRegister(cwd, workspace, executionProfile, options);
         this.pendingStarts.add(start);
         try {
             return await start;
@@ -66,8 +78,29 @@ export class SessionRegistry {
             this.pendingStarts.delete(start);
         }
     }
-    async createAndRegister(cwd, workspace, executionProfile) {
-        const handle = await Promise.resolve().then(() => this.adapter.create({ cwd, executionProfile, signal: this.shutdownController.signal }));
+    async guardedCreate(cwd, workspace, executionProfile, options) {
+        const previous = this.codingAdmissions.get(workspace) ?? Promise.resolve();
+        let release;
+        const admission = new Promise((resolve) => { release = resolve; });
+        this.codingAdmissions.set(workspace, admission);
+        await previous;
+        try {
+            if (this.stopping)
+                throw new RegistryError("server_stopping");
+            const open = [...this.sessions.values()].filter((entry) => entry.workspace === workspace && entry.profile === "coding").length;
+            await this.writerGuard.check(workspace, open);
+            if (this.stopping)
+                throw new RegistryError("server_stopping");
+            return await this.createAndRegister(cwd, workspace, executionProfile, options);
+        }
+        finally {
+            release();
+            if (this.codingAdmissions.get(workspace) === admission)
+                this.codingAdmissions.delete(workspace);
+        }
+    }
+    async createAndRegister(cwd, workspace, executionProfile, options) {
+        const handle = await Promise.resolve().then(() => this.adapter.create({ cwd, workspace, ...(options.base === undefined ? {} : { base: options.base }), executionProfile, signal: this.shutdownController.signal }));
         try {
             if (this.stopping)
                 throw new RegistryError("server_stopping");
@@ -77,6 +110,7 @@ export class SessionRegistry {
                 id: randomUUID(), workspace, executionProfile: executionProfile.alias, profile: executionProfile.permissionProfile,
                 provider: handle.appliedSelection.provider, model: handle.appliedSelection.model,
                 thinkingLevel: handle.appliedSelection.thinkingLevel, state: "idle", createdAt: time, updatedAt: time,
+                ...(handle.placement ? { writer: handle.placement.writer, base: { ...handle.placement.base } } : {}),
                 handle, operation: Promise.resolve(), disposed: false, turns: new Map(), order: [],
             };
             this.sessions.set(entry.id, entry);
@@ -99,6 +133,8 @@ export class SessionRegistry {
     async prompt(id, text) {
         const entry = this.require(id);
         return this.serial(entry, async () => {
+            if (entry.handle.isLost?.())
+                throw new RegistryError("writer_session_lost");
             if (entry.state === "running" || entry.abortPromise)
                 throw new RegistryError("session_running");
             if (entry.state === "closing" || entry.state === "closed")
@@ -158,7 +194,7 @@ export class SessionRegistry {
             const result = await this.withTimeout(Promise.race([
                 preflight.then((value) => ({ kind: "preflight", value })),
                 operation.then(() => ({ kind: "operation" }), () => ({ kind: "operation" })),
-            ]), this.options.preflightDeadlineMs, { kind: "timeout" });
+            ]), entry.handle.deadlines?.preflightMs ?? this.options.preflightDeadlineMs, { kind: "timeout" });
             if (result.kind === "timeout") {
                 this.quarantineTimedOutPreflight(entry, turn, operation, previous);
                 throw new RegistryError("prompt_timeout");
@@ -193,7 +229,7 @@ export class SessionRegistry {
             }
             return this.view(entry);
         });
-        const result = await this.withTimeout(operation.then((session) => ({ kind: "completed", session }), () => ({ kind: "failed" })), this.options.abortDeadlineMs, { kind: "timeout" });
+        const result = await this.withTimeout(operation.then((session) => ({ kind: "completed", session }), () => ({ kind: "failed" })), entry.handle.deadlines?.abortMs ?? this.options.abortDeadlineMs, { kind: "timeout" });
         if (result.kind === "timeout")
             throw new RegistryError("abort_timeout");
         if (result.kind === "failed")
@@ -220,8 +256,9 @@ export class SessionRegistry {
                 const time = this.advance(turn.updatedAt);
                 turn.updatedAt = time;
                 turn.completedAt = time;
+                this.notifyTerminal(existing, turn, "close");
                 const abortPromise = this.beginAbort(existing, turn);
-                await this.withTimeout(abortPromise.then(() => undefined, () => undefined), this.options.closeCleanupDeadlineMs, undefined);
+                await this.withTimeout(abortPromise.then(() => undefined, () => undefined), existing.handle.deadlines?.cleanupMs ?? this.options.closeCleanupDeadlineMs, undefined);
             }
             existing.turn = undefined;
             existing.turnPromise = undefined;
@@ -257,7 +294,7 @@ export class SessionRegistry {
         const normalized = normalize(outcome.assistantText);
         turn.state = "completed";
         turn.assistantText = normalized.text;
-        turn.truncated = normalized.truncated;
+        turn.truncated = normalized.truncated || outcome.truncated === true;
     }
     else if (outcome.status === "aborted")
         turn.state = "aborted";
@@ -267,11 +304,24 @@ export class SessionRegistry {
         entry.lastError = "Pi turn failed";
     } if (entry.turn === turn)
         entry.turn = undefined; if (entry.turnPromise)
-        entry.turnPromise = undefined; entry.state = turn.state === "failed" ? "failed" : "idle"; entry.updatedAt = turn.updatedAt; }
+        entry.turnPromise = undefined; entry.state = turn.state === "failed" ? "failed" : "idle"; entry.updatedAt = turn.updatedAt; this.notifyTerminal(entry, turn, "registry"); }
     failTurn(entry, turn) { if (turn.terminal)
         return; turn.terminal = true; turn.state = "failed"; turn.updatedAt = this.advance(turn.updatedAt); turn.completedAt = turn.updatedAt; turn.error = { code: "turn_failed", message: "Pi turn failed" }; if (entry.turn === turn)
         entry.turn = undefined; if (entry.turnPromise)
-        entry.turnPromise = undefined; entry.state = "failed"; entry.updatedAt = turn.updatedAt; entry.lastError = "Pi turn failed"; }
+        entry.turnPromise = undefined; entry.state = "failed"; entry.updatedAt = turn.updatedAt; entry.lastError = "Pi turn failed"; this.notifyTerminal(entry, turn, "registry"); }
+    /**
+     * Called once per terminal transition, after the turn is final. Only a published turn is reported:
+     * a preflight that was rejected, timed out or restored never had a public turn id. A throwing
+     * listener is swallowed and can neither change registry state nor reach a caller.
+     */
+    notifyTerminal(entry, turn, via) {
+        if (!this.onTurnTerminal || turn.state === "running" || entry.turns.get(turn.turnId) !== turn)
+            return;
+        try {
+            this.onTurnTerminal({ sessionId: entry.id, turnId: turn.turnId, state: turn.state, via });
+        }
+        catch { /* A listener must never affect the registry. */ }
+    }
     /**
      * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
      * execution start, update and end) advances this turn, never another turn or the session.
@@ -349,7 +399,7 @@ export class SessionRegistry {
     async disposeHandle(handle) {
         try {
             const cleanup = Promise.resolve(handle.dispose()).then(() => undefined, () => undefined);
-            await this.withTimeout(cleanup, this.options.closeCleanupDeadlineMs, undefined);
+            await this.withTimeout(cleanup, handle.deadlines?.cleanupMs ?? this.options.closeCleanupDeadlineMs, undefined);
         }
         catch { /* Cleanup errors must never expose adapter internals. */ }
     }

package/dist/session-tools.d.ts

@@ -1,9 +1,18 @@
 import type { PermissionProfile } from "./execution-profile.js";
 export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly string[]>>;
+export declare const MAX_GRANTED_EXTENSION_TOOLS = 32;
+export declare function isAcceptableExtensionToolName(name: string): boolean;
+export type ComposedSessionTools = {
+    readonly ok: true;
+    readonly tools: string[];
+} | {
+    readonly ok: false;
+    readonly code: "extension_tool_conflict" | "extension_tool_missing";
+};
 /**
- * The tool allowlist of a session, or undefined when an extension tool name conflicts.
- * Extension tools are active only in coding profiles, but a conflict fails closed in both,
- * so an extension can never shadow a built-in or granted tool. A name outside the safe
- * character set, or one the SDK treats as an MCP tool, also fails closed.
+ * The tool allowlist of a session. Read-only activates exactly the granted extension
+ * names; coding activates all registered extension tools. Conflicts are checked first
+ * 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[])[]): string[] | undefined;
+export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[], grantedExtensionTools?: readonly string[]): ComposedSessionTools;

package/dist/session-tools.js

@@ -2,6 +2,7 @@ export const PROFILE_TOOLS = {
     "read-only": ["read", "grep", "find", "ls"],
     coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
 };
+export const MAX_GRANTED_EXTENSION_TOOLS = 32;
 /**
  * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
  * function-name limit `^[a-zA-Z0-9_-]{1,64}$`. The SDK reads `*` in an allowlist as a glob
@@ -9,7 +10,7 @@ export const PROFILE_TOOLS = {
  */
 const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
 /**
- * These mirror `isMcpToolName` of Pi SDK 1.2.0 (core/mcp-servers.js), which is not a root
+ * These mirror `isMcpToolName` of Pi SDK 1.4.0 (core/mcp-servers.js), which is not a root
  * export. When the allowlist names no `mcp__` entry, the SDK's `_isAllowedTool` keeps such
  * tools outside the allowlist for codemode and tool_search, so an extension tool with one
  * of these names could be active without being granted. This server's own MCP bridge
@@ -17,25 +18,28 @@ const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
  */
 const MCP_RESERVED_PREFIX = "mcp__";
 const MCP_RESERVED_NAMES = new Set(["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
-function isAcceptableExtensionToolName(name) {
+export function isAcceptableExtensionToolName(name) {
     return EXTENSION_TOOL_NAME.test(name) && !name.startsWith(MCP_RESERVED_PREFIX) && !MCP_RESERVED_NAMES.has(name);
 }
 /**
- * The tool allowlist of a session, or undefined when an extension tool name conflicts.
- * Extension tools are active only in coding profiles, but a conflict fails closed in both,
- * so an extension can never shadow a built-in or granted tool. A name outside the safe
- * character set, or one the SDK treats as an MCP tool, also fails closed.
+ * The tool allowlist of a session. Read-only activates exactly the granted extension
+ * names; coding activates all registered extension tools. Conflicts are checked first
+ * 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) {
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = []) {
     const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
     const extensionTools = [];
     for (const names of extensionToolNames) {
         for (const name of names) {
             if (!isAcceptableExtensionToolName(name) || reserved.has(name))
-                return undefined;
+                return { ok: false, code: "extension_tool_conflict" };
             reserved.add(name);
             extensionTools.push(name);
         }
     }
-    return [...PROFILE_TOOLS[permissionProfile], ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : [])];
+    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)] };
 }

package/dist/setup-cli.d.ts

@@ -1,10 +1,24 @@
 import { SetupOrchestrator, 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";
 /** Small argv adapter; command execution remains injected in SetupClientAdapter. */
 export interface SetupCliRequest extends SetupRequest {
     readonly json: boolean;
     /** `--customize-skill <name>`: copies a shipped skill into the override directory instead of touching clients. */
     readonly customizeSkill?: string;
+    readonly repo?: ModeRequest;
+    readonly writer?: {
+        name: string;
+        operation: WriterOperation;
+        apply: boolean;
+        discard: boolean;
+        baseRef?: string;
+    };
+    readonly isolationControl?: {
+        alias: string;
+        apply: boolean;
+    };
 }
 export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
 export declare function runSetupCli(argv: readonly string[], orchestrator: SetupOrchestrator): Promise<SetupResult>;