@jmfederico/pi-web 1.202608.0 → 1.202608.2

package/dist/server/sessions/piSessionService.js

@@ -1,7 +1,7 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, defineTool, readStoredCredential, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { readFile, writeFile } from "node:fs/promises";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, defineTool, hasTrustRequiringProjectResources, ProjectTrustStore, readStoredCredential, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { projectBrowserMessage } from "../browserMessageProjection.js";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
 import { BUILTIN_COMMANDS } from "./builtinCommands.js";
@@ -16,8 +16,6 @@ import { parsePromptAttachments } from "../../shared/promptAttachments.js";
 import { ASK_USER_ANSWERS_CUSTOM_TYPE, SESSION_TREE_CUSTOM_INSTRUCTIONS_MAX_LENGTH, SESSION_UNREAD_LIMIT } from "../../shared/apiTypes.js";
 import { canonicalizeStoredCwd, cwdPathsEqual } from "../workingDirectory.js";
 import { readSessionHeaderSummary } from "./sessionFileHeader.js";
-import { countOutOfListingChildren, locateOutOfListingParents } from "./parentSessionLocator.js";
-import { siblingWorkspaceCwds } from "../workspaces/projectWorkspaceCwds.js";
 import { createAskUserToolDefinition } from "./askUserTool.js";
 import { PendingAskStore, renderAskUserAnswersText } from "./pendingAskStore.js";
 import { PendingExtensionDialogStore } from "./pendingExtensionDialogStore.js";
@@ -30,6 +28,7 @@ import { planSessionCleanup, summarizeSessionCleanupExecution } from "./sessionC
 import { SessionNotificationStore, } from "./sessionNotificationStore.js";
 import { plainTextTheme } from "./plainTextTheme.js";
 import { SessionUnreadStore } from "./sessionUnreadStore.js";
+import { applyEnabledModelToggle, catalogWithEnabledFirst, modelScopeId, persistedEnabledModelPatterns, resolveEnabledModelIds, resolveSessionModelOptions, scopedModelsFromEnabledIds } from "./sessionModelScope.js";
 const noopLogger = { info() { } };
 const DEFAULT_UNREAD_PUBLICATION_RETRY_MS = 1_000;
 /**
@@ -56,6 +55,14 @@ function spawnTargetError(decision) {
         return new Error("Spawning session is not in a registered project");
     return new Error(`cwd must be a workspace of this project. Allowed: ${decision.allowedCwds.join(", ")}`);
 }
+/**
+ * Tracked subsessions are worktree-scoped, so a requested target other than the
+ * parent's own cwd fails closed instead of being silently retargeted. The
+ * message names the rule and both supported ways to get work done elsewhere.
+ */
+function subsessionCwdError(spawningCwd, requestedCwd) {
+    return new Error(`A tracked subsession runs in this session's working directory (${spawningCwd}); ${requestedCwd} was requested. Instruct the child to work elsewhere from this workspace, or use spawn_session for an independent session in another workspace.`);
+}
 function modelSpecOf(model) {
     return `${model.provider}/${model.id}`;
 }
@@ -275,9 +282,182 @@ export function createPiWebCustomToolDefinitions(cwd, delegationEnabled, spawn,
         ...(askUser === undefined ? [] : [createAskUserToolDefinition(askUser)]),
     ];
 }
-function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subsessions, askUser) {
+/**
+ * Run the `project_trust` event over a pre-trust extension set, mirroring
+ * `emitProjectTrustEvent` in the SDK's `dist/core/extensions/runner.js`. That
+ * helper is not part of the package's public exports (the main index exports
+ * only the `ProjectTrust*` types and `ProjectTrustStore`, and the package's
+ * `exports` map blocks subpath imports, so `resolveProjectTrusted`/
+ * `emitProjectTrustEvent` are not callable from here), so PI WEB reimplements
+ * its documented decision loop over the SDK-provided extension objects: per
+ * extension, the registered `project_trust` handlers run in order; the first
+ * handler returning `yes`/`no` decides and `undecided` falls through to the
+ * next handler/extension; a throwing handler is collected as an error and
+ * later handlers still get their chance.
+ */
+export async function emitWebProjectTrustEvent(extensionsResult, event, ctx) {
+    const errors = [];
+    for (const extension of extensionsResult.extensions) {
+        // A single extension may register multiple handlers for the same event.
+        // The handlers map is keyed exactly as the extension registered it, so a
+        // `project_trust` key guarantees `ProjectTrustHandler` entries — the same
+        // assumption the SDK's emitProjectTrustEvent makes.
+        const handlers = extension.handlers.get("project_trust");
+        if (handlers === undefined || handlers.length === 0)
+            continue;
+        for (const handler of handlers) {
+            try {
+                const handlerResult = await handler(event, ctx);
+                // The SDK reads `trusted` straight off the handler result, so a
+                // non-object would throw there; PI WEB reports it as a handler error
+                // and lets the next handler/extension try.
+                if (typeof handlerResult !== "object" || handlerResult === null) {
+                    errors.push({ extensionPath: extension.path, error: "project_trust handler returned a non-object result" });
+                    continue;
+                }
+                const trusted = "trusted" in handlerResult ? handlerResult.trusted : undefined;
+                if (trusted === "undecided") {
+                    continue;
+                }
+                // Rebuild the decision so only the documented `trusted`/`remember`
+                // fields carry over — the SDK's resolver reads exactly those two.
+                const remember = "remember" in handlerResult ? handlerResult.remember : undefined;
+                return {
+                    result: {
+                        trusted: trusted === "yes" ? "yes" : "no",
+                        ...(remember === true ? { remember: true } : {}),
+                    },
+                    errors,
+                };
+            }
+            catch (error) {
+                errors.push({
+                    extensionPath: extension.path,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    return { errors };
+}
+/**
+ * PI WEB's headless project-trust context. `hasUI` is false because there is
+ * no browser trust prompt (chartered behavior: `ask` never loads untrusted
+ * resources), so the UI methods are inert — the same no-UI shape the SDK
+ * passes when pi runs without a trust UI. The host mode is `rpc`, mirroring
+ * how PI WEB binds its session extension contexts.
+ */
+function webProjectTrustContext(cwd) {
+    return {
+        cwd,
+        mode: "rpc",
+        hasUI: false,
+        ui: {
+            select: () => Promise.resolve(undefined),
+            confirm: () => Promise.resolve(false),
+            input: () => Promise.resolve(undefined),
+            notify: () => undefined,
+        },
+    };
+}
+/**
+ * Resolve whether a workspace's project-local `.pi/` resources may load, the
+ * way `pi` resolves it — a faithful mirror of the SDK's `resolveProjectTrusted`
+ * (`dist/core/project-trust.js`, also not a public export). PI WEB has no
+ * browser trust prompt, so the precedence is, in order:
+ *
+ * 1. Nothing trust-requiring under `cwd` → trusted.
+ * 2. Pre-trust extensions (user/global — project-local ones are not loaded
+ *    yet) may decide via the `project_trust` event; `remember: true` persists
+ *    the decision to the agent dir's `trust.json`. Handler errors are reported
+ *    through {@link WebProjectTrustResolution.onExtensionError} and never
+ *    abort resolution.
+ * 3. Otherwise the saved `trust.json` decision wins.
+ * 4. Otherwise `defaultProjectTrust` decides (`always` trusts; `never`/`ask`
+ *    do not — `ask` cannot prompt in the browser, matching `pi` run without a
+ *    trust UI).
+ */
+export async function resolveWebProjectTrusted(resolution) {
+    const { cwd, trustStore, settingsManager } = resolution;
+    if (!hasTrustRequiringProjectResources(cwd))
+        return true;
+    if (resolution.extensionsResult) {
+        const { result, errors } = await emitWebProjectTrustEvent(resolution.extensionsResult, { type: "project_trust", cwd }, webProjectTrustContext(cwd));
+        for (const error of errors) {
+            resolution.onExtensionError?.(`Extension "${error.extensionPath}" project_trust error: ${error.error}`);
+        }
+        if (result) {
+            const trusted = result.trusted === "yes";
+            if (result.remember === true) {
+                trustStore.set(cwd, trusted);
+            }
+            return trusted;
+        }
+    }
+    const saved = trustStore.get(cwd);
+    if (saved !== null)
+        return saved;
+    return settingsManager.getDefaultProjectTrust() === "always";
+}
+/**
+ * Resource-loader options that append PI WEB's own system-prompt sections.
+ *
+ * `appendSystemPromptOverride` composes with what the loader already resolved,
+ * so the operator's `SYSTEM.md` / `APPEND_SYSTEM.md` files keep their content
+ * and PI WEB's sections land after them. Returns `undefined` when there is
+ * nothing to append, leaving the loader exactly as pi configures it.
+ */
+export function piWebResourceLoaderOptions(appendSystemPromptSections) {
+    if (appendSystemPromptSections.length === 0)
+        return undefined;
+    return { appendSystemPromptOverride: (base) => [...base, ...appendSystemPromptSections] };
+}
+function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subsessions, askUser, appendSystemPromptSections = []) {
+    const resourceLoaderOptions = piWebResourceLoaderOptions(appendSystemPromptSections);
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel, initialThinkingLevel, delegationToolsEnabled }) => {
-        const services = await createAgentSessionServices({ cwd, agentDir, modelRuntime });
+        // PI WEB always honors pi's project-trust model. When the workspace ships
+        // trust-requiring resources, trust is resolved exactly once, mirroring the
+        // SDK's flow: the resource loader first loads the pre-trust extension set
+        // (user/global; project-local ones stay out) and calls back with it, so
+        // those extensions may decide via the `project_trust` event; the resolved
+        // value then lands in the SettingsManager before any project-local
+        // resource (extensions, packages, settings, prompts) loads. With no
+        // browser trust prompt, an untrusted project's resources are skipped
+        // (matching `pi` run without a UI). Projects without trust-requiring
+        // resources skip resolution entirely and are trusted, as before.
+        const projectTrustRequiring = hasTrustRequiringProjectResources(cwd);
+        const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: !projectTrustRequiring });
+        // Pre-session-creation trust failures (`project_trust` handler errors)
+        // land in the runtime diagnostics next to the services diagnostics,
+        // exactly as the CLI appends its project-trust diagnostics.
+        const projectTrustDiagnostics = [];
+        const services = await createAgentSessionServices({
+            cwd,
+            agentDir,
+            modelRuntime,
+            settingsManager,
+            ...(resourceLoaderOptions === undefined ? {} : { resourceLoaderOptions }),
+            ...(projectTrustRequiring
+                ? {
+                    resourceLoaderReloadOptions: {
+                        resolveProjectTrust: async ({ extensionsResult }) => resolveWebProjectTrusted({
+                            cwd,
+                            trustStore: new ProjectTrustStore(agentDir),
+                            settingsManager,
+                            extensionsResult,
+                            onExtensionError: (message) => projectTrustDiagnostics.push({ type: "warning", message }),
+                        }),
+                    },
+                }
+                : {}),
+        });
+        const modelOptions = await resolveSessionModelOptions({
+            services,
+            hasExistingSession: sessionManager.buildSessionContext().messages.length > 0,
+            ...(initialModel === undefined ? {} : { initialModel }),
+            ...(initialThinkingLevel === undefined ? {} : { initialThinkingLevel }),
+        });
+        services.diagnostics.push(...modelOptions.diagnostics);
         const resolvedDelegationToolsEnabled = delegationToolsEnabled
             ?? await sessionAllowsDelegationTools(sessionManager, sessionManagers);
         const customTools = createPiWebCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions, askUser);
@@ -286,10 +466,11 @@ function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subse
             sessionManager,
             customTools,
             ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
-            ...(initialModel === undefined ? {} : { model: initialModel }),
-            ...(initialThinkingLevel === undefined ? {} : { thinkingLevel: initialThinkingLevel }),
+            ...(modelOptions.model === undefined ? {} : { model: modelOptions.model }),
+            ...(modelOptions.thinkingLevel === undefined ? {} : { thinkingLevel: modelOptions.thinkingLevel }),
+            ...(modelOptions.scopedModels.length === 0 ? {} : { scopedModels: modelOptions.scopedModels }),
         });
-        return { ...result, services, diagnostics: services.diagnostics };
+        return { ...result, services, diagnostics: [...projectTrustDiagnostics, ...services.diagnostics] };
     };
 }
 function createPiWebEditToolDefinition(cwd) {
@@ -331,6 +512,16 @@ export class PiSessionService {
         this.treeNavigations = new WeakSet();
         /** Counts async operations that may append an entry before they settle. */
         this.sessionEntryMutationCounts = new WeakMap();
+        /** Settings-wide queue preventing enabled-model read/modify/write races across sessions. */
+        this.modelScopeMutationQueue = Promise.resolve();
+        /** Global and workspace-owned enabled-model states; live session scopes project one entry lazily. */
+        this.modelScopeStates = new Map();
+        /** Coalesces initialization reads independently for the global and each workspace scope. */
+        this.modelScopeInitializations = new Map();
+        /** Monotonic revision published for global scope changes and consumed by clients. */
+        this.modelScopeRevision = 0;
+        /** Last scope/catalog revision projected into each runtime, synchronized lazily on use. */
+        this.modelScopeCache = new WeakMap();
         /** Runtime/session-identity reservations for operations that must not overlap tree navigation. */
         this.treeExclusiveRuntimeOperationCounts = new WeakMap();
         this.treeExclusiveSessionOperationCounts = new Map();
@@ -347,13 +538,6 @@ export class PiSessionService {
         this.subsessionLinks = new Map();
         /** Parent id/file identities whose persisted links have already been loaded. */
         this.subsessionHydratedParents = new Set();
-        /**
-         * Session file path -> its parsed header and the file identity at read
-         * time. Headers are written once, so identity-verified reads are cached.
-         */
-        this.sessionHeaderCache = new Map();
-        /** Session file path -> its in-flight header read, so concurrent scans share one read per file. */
-        this.pendingSessionHeaderReads = new Map();
         /**
          * Tracked subsession id -> whether a completion notification is armed.
          * Armed when the child starts working; firing on completion disarms it so a
@@ -366,46 +550,23 @@ export class PiSessionService {
         this.pendingUnreadMutations = [];
         this.unreadPublicationFlushRequested = false;
         this.unreadPublicationStopped = false;
-        /**
-         * Read a session file header, memoized per path, with one in-flight read
-         * per path: concurrent scans of a shared session directory share the read
-         * instead of each opening the file. Pi writes the header once at session
-         * creation, so a successful read stays valid as long as the path still
-         * holds the same file: every hit re-checks the file's identity (dev/ino),
-         * and a replacement landed at a cached path is re-read instead of serving
-         * the previous file's header — the summary scanner detects such
-         * replacements, so the listing and the header reads must agree. The one
-         * thing identity cannot detect is an in-place rewrite that keeps the
-         * inode; detach, the only such writer, deletes the entry itself. Failures
-         * are not cached so a session file that appears later is picked up.
-         */
-        this.readCachedSessionHeader = (sessionFile) => {
-            const pending = this.pendingSessionHeaderReads.get(sessionFile);
-            if (pending !== undefined)
-                return pending;
-            const read = this.loadSessionHeader(sessionFile).finally(() => {
-                this.pendingSessionHeaderReads.delete(sessionFile);
-            });
-            this.pendingSessionHeaderReads.set(sessionFile, read);
-            return read;
-        };
         this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
         this.agentDir = deps.agentDir;
         this.sessionManager = deps.sessionManager;
         this.modelRuntime = deps.modelRuntime;
         this.spawnTargets = deps.spawnTargets;
-        this.projectWorkspaces = deps.projectWorkspaces;
         this.logger = deps.logger ?? noopLogger;
         this.now = deps.now ?? (() => new Date());
         this.notificationStore = deps.notificationStore ?? new SessionNotificationStore();
         this.unreadStore = deps.unreadStore ?? new SessionUnreadStore();
+        this.onUnreadChanged = deps.onUnreadChanged;
         this.pendingAskStore = deps.pendingAskStore ?? new PendingAskStore();
         this.pendingExtensionDialogStore = deps.pendingExtensionDialogStore ?? new PendingExtensionDialogStore();
         this.extensionDialogsTimeoutMs = deps.extensionDialogsTimeoutMs ?? DEFAULT_EXTENSION_DIALOGS_TIMEOUT_MS;
         this.catalogRefreshStatus = deps.catalogRefreshStatus;
         this.unreadPublicationRetryInitialMs = Math.max(0, deps.unreadPublicationRetryDelayMs ?? DEFAULT_UNREAD_PUBLICATION_RETRY_MS);
         this.unreadPublicationRetryDelayMs = this.unreadPublicationRetryInitialMs;
-        // Subsessions are a beta capability gated behind their own flag, and they
+        // Subsessions are gated behind their own flag, and they
         // also require the spawn capability (they share its project-scope resolver).
         const subsessionsActive = this.spawnTargets !== undefined && deps.subsessionsEnabled === true;
         this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRuntime, this.sessionManager, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
@@ -413,7 +574,7 @@ export class PiSessionService {
             list: (parentSessionId, parentSessionFile) => this.listSubsessions(parentSessionId, parentSessionFile),
             check: (parentSessionId, sessionId, parentSessionFile) => this.checkSubsession(parentSessionId, sessionId, parentSessionFile),
             read: (parentSessionId, sessionId, query, parentSessionFile) => this.readSubsession(parentSessionId, sessionId, query, parentSessionFile),
-        }, deps.askUserEnabled === true ? { open: (input) => this.openAsk(input) } : undefined);
+        }, deps.askUserEnabled === true ? { open: (input) => this.openAsk(input) } : undefined, deps.appendSystemPromptSections ?? []);
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
         this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
@@ -541,8 +702,6 @@ export class PiSessionService {
         this.subsessionLinks.clear();
         this.subsessionHydratedParents.clear();
         this.subsessionNotifyArmed.clear();
-        this.sessionHeaderCache.clear();
-        this.pendingSessionHeaderReads.clear();
         this.notificationStore.clearAll("service-dispose");
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
@@ -573,83 +732,7 @@ export class PiSessionService {
             .sort(compareArchivedRecords)
             .map((record) => clientSessionFromArchivedRecord(record, sessionsById.get(record.sessionId)))
             .filter(isDefined);
-        return await this.withRelatedSessionsElsewhere([...unarchivedSessions, ...archivedSessions], cwd);
-    }
-    /**
-     * Annotate a listing with the session relationships that cross workspace
-     * boundaries: where an out-of-listing parent lives, and how many children a
-     * listed session has in sibling workspaces.
-     *
-     * Both directions are best-effort. An unreadable parent header or a sibling
-     * workspace that cannot be listed leaves the session unannotated rather than
-     * failing the listing, and the browser falls back to its generic states.
-     */
-    async withRelatedSessionsElsewhere(sessions, cwd) {
-        const [parentLocations, childCounts] = await Promise.all([
-            locateOutOfListingParents(sessions, cwd, this.readCachedSessionHeader),
-            this.countChildrenInSiblingWorkspaces(sessions, cwd),
-        ]);
-        return sessions.map((session) => {
-            const parent = session.parentSessionPath === undefined ? undefined : parentLocations.get(session.parentSessionPath);
-            const childrenElsewhere = childCounts.get(session.path);
-            if (parent === undefined && childrenElsewhere === undefined)
-                return session;
-            const annotated = { ...session };
-            if (parent !== undefined) {
-                annotated.parentSessionId = parent.parentSessionId;
-                annotated.parentSessionCwd = parent.parentSessionCwd;
-            }
-            if (childrenElsewhere !== undefined)
-                annotated.childSessionsElsewhere = childrenElsewhere;
-            return annotated;
-        });
-    }
-    /**
-     * Count children of the listed sessions that live in other workspaces of the
-     * same project.
-     *
-     * Only sibling workspaces are scanned: agents may only spawn into workspaces
-     * of the spawning session's own project, so that bounds where a child can be.
-     * Each sibling scan reads only the header line of every session file (the
-     * only place `parentSessionPath` is recorded), never the transcripts. Listing
-     * is skipped entirely when no project-workspace locator is configured or the
-     * cwd belongs to no registered project.
-     */
-    async countChildrenInSiblingWorkspaces(sessions, cwd) {
-        if (this.projectWorkspaces === undefined || sessions.length === 0)
-            return new Map();
-        try {
-            const siblingCwds = await siblingWorkspaceCwds(this.projectWorkspaces, cwd);
-            if (siblingCwds.length === 0)
-                return new Map();
-            const listings = await Promise.all(siblingCwds.map((siblingCwd) => this.sessionManager.listParentSessionPaths(siblingCwd, this.readCachedSessionHeader)));
-            return countOutOfListingChildren(sessions, listings.flat());
-        }
-        catch (error) {
-            this.logger.info({ cwd, error: error instanceof Error ? error.message : String(error) }, "failed to count child sessions in sibling workspaces");
-            return new Map();
-        }
-    }
-    async loadSessionHeader(sessionFile) {
-        let stats;
-        try {
-            stats = await stat(sessionFile);
-        }
-        catch {
-            // Gone or unreadable: report no header and forget any cached entry.
-            this.sessionHeaderCache.delete(sessionFile);
-            return undefined;
-        }
-        const cached = this.sessionHeaderCache.get(sessionFile);
-        if (cached?.dev === stats.dev && cached.ino === stats.ino)
-            return cached.header;
-        const header = await readSessionHeaderSummary(sessionFile);
-        if (header === undefined) {
-            this.sessionHeaderCache.delete(sessionFile);
-            return undefined;
-        }
-        this.sessionHeaderCache.set(sessionFile, { header, dev: stats.dev, ino: stats.ino });
-        return header;
+        return [...unarchivedSessions, ...archivedSessions];
     }
     async start(cwd, options = {}) {
         return this.startSession(cwd, options);
@@ -711,15 +794,22 @@ export class PiSessionService {
         };
     }
     /**
-     * Start a *tracked* child session on behalf of a LLM. Identical to
-     * {@link spawnSession} in how the target cwd is resolved, but the child
-     * records its parent (so it shows in the session tree) and is registered so
-     * the parent is notified when it stops working and can inspect it later.
+     * Start a *tracked* child session on behalf of a LLM. Unlike
+     * {@link spawnSession}, a tracked child always runs in the parent's own
+     * workspace: parent/child trees are worktree-scoped, so a child elsewhere
+     * would be invisible to the parent's listing. The child records its parent
+     * (so it shows in the session tree) and is registered so the parent is
+     * notified when it stops working and can inspect it later.
      */
     async spawnSubsession(input) {
         if (this.spawnTargets === undefined)
             throw new Error("Spawning sessions is disabled");
-        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+        if (input.cwd !== undefined && input.cwd !== "" && !cwdPathsEqual(input.cwd, input.spawningCwd)) {
+            throw subsessionCwdError(input.spawningCwd, input.cwd);
+        }
+        // Resolved against the parent's own cwd only: this still refuses spawning
+        // from an unregistered directory, which keeps the child visible in the UI.
+        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, undefined);
         if (!decision.allowed)
             throw spawnTargetError(decision);
         // A model spec overrides the inherited model and is resolved against the
@@ -754,15 +844,117 @@ export class PiSessionService {
         };
     }
     /**
-     * The models a session may pick from: its scoped set when model-scoped,
-     * otherwise the runtime's available snapshot. Refreshes the runtime catalog
-     * first so callers see newly configured providers and models.
+     * Resolve the settings domain for a session. Pi's settings manager deep-merges
+     * objects, but an `enabledModels` array in `.pi/settings.json` replaces the
+     * global array, so that workspace gets its own effective scope and is not
+     * affected by global picker edits.
+     */
+    modelScopeContext(session) {
+        const projectSettings = session.settingsManager.getProjectSettings?.() ?? {};
+        if (!Object.hasOwn(projectSettings, "enabledModels")) {
+            return { key: "global", source: "global", editable: true };
+        }
+        const workspace = canonicalizeStoredCwd(session.sessionManager.getCwd());
+        return { key: `workspace:${workspace}`, source: "workspace", editable: false };
+    }
+    /**
+     * Read the effective scope for one settings domain. Global sessions share one
+     * snapshot; project-overridden sessions share a snapshot keyed by workspace.
+     * Neither path enumerates or mutates other active sessions.
+     */
+    async modelScopeSnapshot(session, context = this.modelScopeContext(session)) {
+        const existing = this.modelScopeStates.get(context.key);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.modelScopeInitializations.get(context.key);
+        if (pending !== undefined)
+            return pending;
+        const initialization = (async () => {
+            const enabledIds = await resolveEnabledModelIds(sessionScopeSource(session));
+            const snapshot = {
+                enabledIds: enabledIds === null ? null : [...enabledIds],
+                revision: 0,
+            };
+            this.modelScopeStates.set(context.key, snapshot);
+            return snapshot;
+        })();
+        this.modelScopeInitializations.set(context.key, initialization);
+        try {
+            return await initialization;
+        }
+        finally {
+            if (this.modelScopeInitializations.get(context.key) === initialization)
+                this.modelScopeInitializations.delete(context.key);
+        }
+    }
+    /**
+     * Project one settings-domain scope into one SDK session only when that
+     * session is used. `PiAgentSession` needs an in-memory array for cycling, but
+     * that array is a cache; the keyed snapshot above is the source of truth.
+     */
+    async synchronizeSessionModelScope(session, available) {
+        const context = this.modelScopeContext(session);
+        const snapshot = await this.modelScopeSnapshot(session, context);
+        const catalogKey = available.map(modelScopeId).join("\0");
+        const cached = this.modelScopeCache.get(session);
+        if (cached?.scopeKey === context.key && cached.revision === snapshot.revision && cached.catalogKey === catalogKey)
+            return;
+        session.setScopedModels(scopedModelsFromEnabledIds(available, snapshot.enabledIds, session.scopedModels));
+        this.modelScopeCache.set(session, { scopeKey: context.key, revision: snapshot.revision, catalogKey });
+    }
+    /**
+     * The models a session may pick from: its synchronized scoped set when
+     * model-scoped, otherwise the runtime's available snapshot. Refreshes the
+     * shared runtime catalog first so callers see newly configured providers and
+     * models. The refresh stays local (`allowNetwork: false`); network refreshes
+     * belong to the bounded background catalog refresher, not this request path.
      */
     async sessionModelCandidates(session) {
-        await session.modelRuntime.refresh();
+        await session.modelRuntime.refresh({ allowNetwork: false });
+        const available = session.modelRuntime.getAvailableSnapshot();
+        await this.synchronizeSessionModelScope(session, available);
         return session.scopedModels.length > 0
             ? session.scopedModels.map((scoped) => scoped.model)
-            : session.modelRuntime.getAvailableSnapshot();
+            : available;
+    }
+    /**
+     * The session machine's full available catalog with per-model enabled state,
+     * ordered enabled-first for scope semantics while retaining each model's
+     * natural catalog index for stable picker placement. The enabled state comes
+     * from the keyed scope snapshot rather than a session-local SettingsManager.
+     */
+    async enabledModelCatalog(session) {
+        await session.modelRuntime.refresh({ allowNetwork: false });
+        const available = session.modelRuntime.getAvailableSnapshot();
+        await this.synchronizeSessionModelScope(session, available);
+        const context = this.modelScopeContext(session);
+        const enabledIds = (await this.modelScopeSnapshot(session, context)).enabledIds;
+        return catalogWithEnabledFirst(available, enabledIds);
+    }
+    runModelScopeMutation(operation) {
+        const queued = this.modelScopeMutationQueue.then(operation);
+        this.modelScopeMutationQueue = queued.then(() => undefined, () => undefined);
+        return queued;
+    }
+    /** Persist one global enabled-model selection and publish its new revision. */
+    applyEnabledModelScope(session, available, enabledIds) {
+        const availableIds = available.map(modelScopeId);
+        const persisted = persistedEnabledModelPatterns(enabledIds, availableIds);
+        const nextState = {
+            // Pi normalizes a scope covering the complete current catalog to an
+            // omitted setting, which is the global canonical all-enabled state.
+            enabledIds: persisted === undefined ? null : enabledIds === null ? [] : [...enabledIds],
+            revision: ++this.modelScopeRevision,
+        };
+        session.settingsManager.setEnabledModels(persisted);
+        this.modelScopeStates.set("global", nextState);
+        session.setScopedModels(scopedModelsFromEnabledIds(available, nextState.enabledIds, session.scopedModels));
+        this.modelScopeCache.set(session, {
+            scopeKey: "global",
+            revision: nextState.revision,
+            catalogKey: available.map(modelScopeId).join("\0"),
+        });
+        this.events.publishGlobal({ type: "models.changed", revision: nextState.revision });
     }
     /**
      * Resolve a strict `provider/model-id` spec from a spawn tool against the
@@ -1357,6 +1549,68 @@ export class PiSessionService {
         const models = await this.sessionModelCandidates(session);
         return models.map(modelToClientModel);
     }
+    async modelCatalog(ref) {
+        const session = await this.getOrOpen(ref);
+        const scope = this.modelScopeContext(session);
+        return (await this.enabledModelCatalog(session)).map((entry) => catalogEntryToClientModel(entry, scope.editable));
+    }
+    /**
+     * Add/remove one model to/from the global pi `enabledModels` scope. A
+     * workspace `.pi/settings.json` override remains authoritative for that
+     * workspace and is intentionally read-only in this picker.
+     */
+    async setModelEnabled(ref, provider, modelId, enabled) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        return this.runModelScopeMutation(async () => {
+            const scope = this.modelScopeContext(session);
+            if (scope.source !== "global")
+                throw new Error("Model availability is controlled by this workspace's .pi/settings.json");
+            this.assertTreeNavigationInactive(session, "change enabled models");
+            await session.modelRuntime.refresh({ allowNetwork: false });
+            const currentIds = (await this.modelScopeSnapshot(session, scope)).enabledIds;
+            const available = session.modelRuntime.getAvailableSnapshot();
+            const availableIds = available.map(modelScopeId);
+            const targetId = `${provider}/${modelId}`;
+            if (!availableIds.includes(targetId))
+                throw new Error(`Model not found: ${targetId}`);
+            if (!enabled && session.model !== undefined && modelScopeId(session.model) === targetId) {
+                throw new Error("Current model cannot be disabled");
+            }
+            const nextIds = applyEnabledModelToggle(currentIds, availableIds, targetId, enabled);
+            this.assertTreeNavigationInactive(session, "change enabled models");
+            if (nextIds !== currentIds)
+                this.applyEnabledModelScope(session, available, nextIds);
+            // Respond from a fresh post-edit read so the response is exactly what
+            // GET models/catalog returns after the edit, including pi's normalizations.
+            return (await this.enabledModelCatalog(session)).map((entry) => catalogEntryToClientModel(entry));
+        });
+    }
+    /** Atomically expose every model or narrow the global enabled scope to the current model. */
+    async setModelScope(ref, mode) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        return this.runModelScopeMutation(async () => {
+            const scope = this.modelScopeContext(session);
+            if (scope.source !== "global")
+                throw new Error("Model availability is controlled by this workspace's .pi/settings.json");
+            this.assertTreeNavigationInactive(session, "change enabled models");
+            await session.modelRuntime.refresh({ allowNetwork: false });
+            const available = session.modelRuntime.getAvailableSnapshot();
+            const availableIds = available.map(modelScopeId);
+            let nextIds = null;
+            if (mode === "current") {
+                const current = session.model;
+                if (current === undefined || !availableIds.includes(modelScopeId(current))) {
+                    throw new Error("Current model is unavailable");
+                }
+                nextIds = [modelScopeId(current)];
+            }
+            this.assertTreeNavigationInactive(session, "change enabled models");
+            this.applyEnabledModelScope(session, available, nextIds);
+            return (await this.enabledModelCatalog(session)).map((entry) => catalogEntryToClientModel(entry));
+        });
+    }
     async setModel(ref, provider, modelId) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
@@ -1375,7 +1629,11 @@ export class PiSessionService {
     async cycleModel(ref, direction) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
-        const result = await this.runSessionEntryMutation(session, "change models", () => session.cycleModel(direction));
+        const result = await this.runModelScopeMutation(async () => {
+            await session.modelRuntime.refresh({ allowNetwork: false });
+            await this.synchronizeSessionModelScope(session, session.modelRuntime.getAvailableSnapshot());
+            return this.runSessionEntryMutation(session, "change models", () => session.cycleModel(direction));
+        });
         if (result === undefined)
             throw new Error(session.scopedModels.length > 0 ? "Only one model in scope" : "Only one model available");
         this.publishActivity(session, `model: ${result.model.id}`, "idle", result.model.provider);
@@ -1585,6 +1843,83 @@ export class PiSessionService {
             }
         }
     }
+    /**
+     * Fork the session from one entry of its tree into a new session file,
+     * leaving the original session untouched. The forked runtime replaces the
+     * current one, so the outcome is reported for the session the client is
+     * about to join rather than the forked-from record.
+     */
+    async forkFromTree(ref, request) {
+        if (request.entryId.trim() === "")
+            throw new Error("Session tree entry is required");
+        if (this.isTreeExclusiveSessionIdentityActive(ref.id)) {
+            throw new Error("Stop current session activity before forking the session tree");
+        }
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        if (this.hasActiveWork(session))
+            throw new Error("Stop current session activity before forking the session tree");
+        if (session.sessionManager.getLeafId() !== request.expectedLeafId) {
+            throw new Error("The session changed since /tree was opened. Reopen /tree and try again.");
+        }
+        this.publishActivity(session, "forking session from entry", "active");
+        this.publishStatus(session);
+        try {
+            const result = await this.commandService.forkEntry(session.sessionId, request.entryId, {
+                expectedLeafId: request.expectedLeafId,
+            });
+            if (result.type === "unsupported")
+                throw new Error(result.message);
+            if (result.type !== "done")
+                throw new Error("Session fork is unavailable");
+            if (result.session === undefined) {
+                if (this.isCurrentActiveSession(session)) {
+                    this.publishActivity(session, "fork cancelled", "idle");
+                    this.publishStatus(session);
+                }
+                return { cancelled: true };
+            }
+            const forkedSession = this.active.get(result.session.id)?.runtime.session;
+            if (forkedSession !== undefined && this.isCurrentActiveSession(forkedSession)) {
+                this.publishActivity(forkedSession, "session forked", "idle");
+                this.publishStatus(forkedSession);
+            }
+            if (result.session.id !== session.sessionId)
+                this.clearSupersededSessionActivity(session);
+            return {
+                cancelled: false,
+                session: result.session,
+                ...(result.promptDraft === undefined ? {} : { promptDraft: result.promptDraft }),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (this.isCurrentActiveSession(session)) {
+                this.publishActivity(session, "fork failed", "error", message);
+                this.events.publish(session.sessionId, { type: "session.error", message });
+                this.publishStatus(session);
+            }
+            throw error;
+        }
+    }
+    /**
+     * A changed-id fork can rebind its runtime after a heartbeat published the
+     * prior identity as active. Clear every observable owner before forgetting
+     * that identity's local activity record.
+     */
+    clearSupersededSessionActivity(session) {
+        const sessionId = session.sessionId;
+        if (this.activities.get(sessionId)?.phase === "active") {
+            const at = new Date().toISOString();
+            const stored = { phase: "idle", label: "idle", at };
+            this.activities.set(sessionId, stored);
+            const activity = { sessionId, ...stored };
+            this.events.publish(sessionId, { type: "activity.update", activity });
+            this.events.publishGlobal({ type: "activity.update", activity });
+        }
+        this.workspaceActivity?.removeSession(sessionId, session.sessionManager.getCwd());
+        this.activities.delete(sessionId);
+    }
     async reloadSessionRuntime(session) {
         if (this.hasActiveWork(session))
             throw new Error("Stop current session activity before reloading");
@@ -1832,13 +2167,10 @@ export class PiSessionService {
         if (sessionFile === undefined || sessionFile === "")
             throw new Error("Session is not persisted");
         await clearParentSession(sessionFile);
-        // The header cache memoizes the first successful read, and detach is the
-        // only flow that rewrites a header; drop the stale entry so sibling child
-        // counts and parent locations observe the cleared parent immediately.
-        this.sessionHeaderCache.delete(sessionFile);
-        // The same in-place rewrite is invisible to the gateway's summary memo
-        // (same inode, possibly grown file), which would otherwise keep listing
-        // the old parent link and a stale message count until restart.
+        // The header rewrite keeps the inode, and whenever it leaves the file's
+        // size unchanged it is invisible to the gateway's summary memo, which
+        // cannot detect such rewrites from identity + size alone and would keep
+        // listing the old parent link until restart.
         this.sessionManager.invalidateSessionFile(sessionFile);
         clearParentSessionHeader(session.sessionManager);
         this.unregisterSubsession(session.sessionId);
@@ -2106,9 +2438,11 @@ export class PiSessionService {
             const { archivePath } = archived;
             return this.openExistingSession(archived.sessionId, archived.cwd, () => this.sessionManager.open(archivePath), { notifications: "disabled" });
         }
-        // Resolve the session file directly by id: opening one inactive session
-        // must not pay for a full transcript listing of its whole workspace.
-        const match = await this.sessionManager.resolveSessionFile(ref.cwd, ref.id, this.readCachedSessionHeader);
+        // Resolve the session file directly by id: opening one known session must
+        // not depend on — or wait behind — a full transcript listing of its whole
+        // workspace. `getActive` routes prompt/shell/runCommand, so coupling it to
+        // the listing would let an in-flight listing serialize unrelated sends.
+        const match = await this.sessionManager.resolveSessionFile(ref.cwd, ref.id);
         if (!match)
             throw new Error("Session not found");
         return this.openExistingSession(match.id, match.cwd, () => this.sessionManager.open(match.path), options);
@@ -2424,6 +2758,11 @@ export class PiSessionService {
         void this.publishUnreadMutations(mutations).catch(() => undefined);
     }
     publishUnreadMutations(mutations) {
+        // The store applied the mutations already, so the status projection is told
+        // now rather than after the durable flush: it reads in-memory unread state
+        // and must not lag behind the rows the browser is about to see.
+        if (mutations.length > 0)
+            this.onUnreadChanged?.();
         this.enqueueUnreadMutations(mutations);
         this.unreadPublicationFlushRequested = true;
         if (this.unreadPublication === undefined && this.unreadPublicationRetryTimer !== undefined) {
@@ -3033,6 +3372,20 @@ function modelToClientModel(model) {
         ...(reasoning === undefined ? {} : { reasoning }),
     };
 }
+/** The scope source pi's enabled-id precedence reads from: live scope, settings patterns, runtime catalog. */
+function sessionScopeSource(session) {
+    return { settingsManager: session.settingsManager, modelRuntime: session.modelRuntime, scopedModels: session.scopedModels };
+}
+function catalogEntryToClientModel(entry, editable = true) {
+    return {
+        ...modelToClientModel(entry.model),
+        provider: entry.model.provider,
+        id: entry.model.id,
+        enabled: entry.enabled,
+        catalogIndex: entry.catalogIndex,
+        ...(editable ? {} : { editable: false }),
+    };
+}
 function notificationIdentityForSession(session) {
     return {
         sessionId: session.sessionId,