@jmfederico/pi-web 1.202610.0 → 1.202610.2

package/dist/server/sessions/piSessionService.js

@@ -1,19 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEventBus, createEditToolDefinition, defineTool, hasTrustRequiringProjectResources, ProjectTrustStore, readStoredCredential, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { projectBrowserMessage } from "../browserMessageProjection.js";
 import { isSessionMediaId } from "../../shared/sessionMedia.js";
+import { getBuiltinExtensionFactories } from "./builtinExtensionFactories.js";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
 import { clientSessionFirstMessagePreview } from "./clientSessionPreview.js";
 import { BUILTIN_COMMANDS } from "./builtinCommands.js";
 import { SessionCommandService } from "./sessionCommandService.js";
 import { SessionActivityMarker } from "./sessionActivityMarker.js";
 import { projectSessionTree } from "./sessionTreeProjection.js";
+import { messageHistoryTargetId } from "./messageHistoryTarget.js";
 import { SessionArchiveStore } from "./sessionArchiveStore.js";
-import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree } from "./sessionArchiveTree.js";
+import { findArchiveCandidateByExactId, planSessionArchiveTree } from "./sessionArchiveTree.js";
 import { PiSessionEventConnections } from "./piSessionEventConnections.js";
-import { deterministicSessionName, fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
+import { fallbackSessionName, generateShortSessionName, requireInitialSessionName } from "./sessionNameGenerator.js";
+import { createExtensionSessionDispatch } from "./extensionSessionDispatch.js";
 import { computeEditPreview } from "./editPreview.js";
 import { attachmentsToInlineImages, saveAttachmentsToWorkspace } from "./attachmentService.js";
 import { loadEffectiveProjectAttachmentsConfig } from "../workspaces/projectPiWebConfig.js";
@@ -21,19 +26,24 @@ 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 { parseSessionDefaults, parseSessionDefaultsUpdate } from "../../shared/sessionDefaults.js";
 import { canonicalizeStoredCwd, cwdPathsEqual } from "../workingDirectory.js";
+import { parsePersistedChildSubsessionLink, parsePersistedParentSubsessionLink } from "./subsessionProvenance.js";
 import { readSessionHeaderSummary } from "./sessionFileHeader.js";
 import { createAskUserToolDefinition } from "./askUserTool.js";
-import { PendingAskStore, renderAskUserAnswersText } from "./pendingAskStore.js";
+import { createAskUserOutcome, renderAskUserAnswersText, resolveAskUserRequest } from "./askUserDomain.js";
 import { PendingExtensionDialogStore } from "./pendingExtensionDialogStore.js";
 import { ExtensionDialogWaiters, effectiveExtensionDialogTimeoutMs, extensionDialogCancelValue } from "./extensionDialogWaiters.js";
 import { DEFAULT_EXTENSION_DIALOGS_TIMEOUT_MS } from "../../config.js";
 import { createSpawnSessionToolDefinition } from "./spawnSessionTool.js";
+import { readSessionUiMetadata, requireSessionUiMetadata, SESSION_UI_METADATA_CUSTOM_TYPE } from "./sessionMetadata.js";
 import { createSubsessionToolDefinitions } from "./spawnSubsessionTool.js";
 import { buildTranscriptView } from "./subsessionTranscript.js";
+import { createSubsessionCompletionDelivery } from "./subsessionCompletionDelivery.js";
+import { completionReceiptIds, persistedSubsessionCompletions, renderSubsessionCompletions, SUBSESSION_COMPLETION_ENTRY_TYPE, SUBSESSION_NOTIFICATION_CUSTOM_TYPE, SUBSESSION_RECEIPT_ENTRY_TYPE, SubsessionCompletionInbox } from "./subsessionCompletionInbox.js";
 import { annotateAssistantThinkingLevel, historyMessagesFromEntries } from "./transcriptMessages.js";
 import { planSessionCleanup, summarizeSessionCleanupExecution } from "./sessionCleanup.js";
 import { SessionNotificationStore, } from "./sessionNotificationStore.js";
 import { plainTextTheme } from "./plainTextTheme.js";
+import { projectTranscriptMarkdown } from "./transcriptMarkdown.js";
 import { SessionUnreadStore } from "./sessionUnreadStore.js";
 import { applyEnabledModelToggle, catalogWithEnabledFirst, modelScopeId, persistedEnabledModelPatterns, resolveEnabledModelIds, resolveSessionModelOptions, scopedModelsFromEnabledIds } from "./sessionModelScope.js";
 const noopLogger = { info() { } };
@@ -288,14 +298,14 @@ function createRuntimeWithOneShotSessionOptions(createRuntime, initialModel, ini
         });
     };
 }
-export function createPiWebCustomToolDefinitions(cwd, delegationEnabled, spawn, subsessions, askUser) {
+export function createPiWebCustomToolDefinitions(cwd, delegationEnabled, spawn, subsessions, askUserEnabled = false) {
     return [
         createPiWebEditToolDefinition(cwd),
         ...(delegationEnabled && spawn !== undefined ? [createSpawnSessionToolDefinition(cwd, { spawn })] : []),
         ...(delegationEnabled && subsessions !== undefined ? createSubsessionToolDefinitions(cwd, subsessions) : []),
         // Asking the user is not delegation: the questions land in the session the
         // user is already watching, so tracked children may ask too.
-        ...(askUser === undefined ? [] : [createAskUserToolDefinition(askUser)]),
+        ...(askUserEnabled ? [createAskUserToolDefinition()] : []),
     ];
 }
 /**
@@ -428,7 +438,7 @@ export function piWebResourceLoaderOptions(appendSystemPromptSections) {
         return undefined;
     return { appendSystemPromptOverride: (base) => [...base, ...appendSystemPromptSections] };
 }
-function createDefaultRuntimeFactory(sessionEvents, modelRuntime, sessionManagers, spawn, subsessions, askUser, appendSystemPromptSections = []) {
+function createDefaultRuntimeFactory(sessionEvents, modelRuntime, sessionManagers, spawn, subsessions, askUserEnabled = false, appendSystemPromptSections = []) {
     const resourceLoaderOptions = piWebResourceLoaderOptions(appendSystemPromptSections);
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel, initialThinkingLevel, delegationToolsEnabled }) => {
         // PI WEB always honors pi's project-trust model. When the workspace ships
@@ -442,6 +452,14 @@ function createDefaultRuntimeFactory(sessionEvents, modelRuntime, sessionManager
         // (matching `pi` run without a UI). Projects without trust-requiring
         // resources skip resolution entirely and are trusted, as before.
         const eventBus = createEventBus();
+        const builtinFactories = await getBuiltinExtensionFactories();
+        // Resolved before session_start. The bridge shares the same delegation
+        // policy as core tools, including tracked-child and global disablement.
+        let dispatchEnabled = false;
+        const sessionDispatch = createExtensionSessionDispatch(cwd, {
+            ...(spawn === undefined ? {} : { spawn }),
+            isEnabled: () => dispatchEnabled,
+        });
         const projectTrustRequiring = hasTrustRequiringProjectResources(cwd);
         const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: !projectTrustRequiring });
         // Pre-session-creation trust failures (`project_trust` handler errors)
@@ -453,7 +471,10 @@ function createDefaultRuntimeFactory(sessionEvents, modelRuntime, sessionManager
             agentDir,
             modelRuntime,
             settingsManager,
-            resourceLoaderOptions: { ...resourceLoaderOptions, eventBus },
+            resourceLoaderOptions: {
+                ...resourceLoaderOptions, eventBus,
+                extensionFactories: [...builtinFactories, sessionDispatch, ...(subsessions === undefined ? [] : [createSubsessionCompletionDelivery(subsessions)])],
+            },
             ...(projectTrustRequiring
                 ? {
                     resourceLoaderReloadOptions: {
@@ -477,7 +498,8 @@ function createDefaultRuntimeFactory(sessionEvents, modelRuntime, sessionManager
         services.diagnostics.push(...modelOptions.diagnostics);
         const resolvedDelegationToolsEnabled = delegationToolsEnabled
             ?? await sessionAllowsDelegationTools(sessionManager, sessionManagers);
-        const customTools = createPiWebCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions, askUser);
+        dispatchEnabled = resolvedDelegationToolsEnabled;
+        const customTools = createPiWebCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions, askUserEnabled);
         const result = await createAgentSessionFromServices({
             services,
             sessionManager,
@@ -534,8 +556,12 @@ export class PiSessionService {
          * can anchor the selected branch on disk.
          */
         this.unpersistedTreeBranchLeaves = new WeakMap();
+        /** Latest prepared text belongs to the session, never to a browser's unsent draft. */
+        this.suggestedInputs = new Map();
         /** Counts async operations that may append an entry before they settle. */
         this.sessionEntryMutationCounts = new WeakMap();
+        /** Exempt only a command's own prompt receipt while it invokes guarded session control. */
+        this.extensionCommandExecution = new AsyncLocalStorage();
         this.pendingPromptEchoes = new WeakMap();
         this.publishedAssistantPartials = new WeakMap();
         /** Settings-wide queue preventing enabled-model read/modify/write races across sessions. */
@@ -551,7 +577,11 @@ export class PiSessionService {
         /** Runtime/session-identity reservations for operations that must not overlap tree navigation. */
         this.treeExclusiveRuntimeOperationCounts = new WeakMap();
         this.treeExclusiveSessionOperationCounts = new Map();
-        this.deferredSubsessionNotifications = new WeakMap();
+        /** Parent id/file identity -> one inbox shared by all completion delivery paths. */
+        this.subsessionInboxes = new Map();
+        this.subsessionStoppedParents = new WeakSet();
+        this.subsessionDeliveringParents = new WeakSet();
+        this.subsessionDeliveryScheduled = new WeakSet();
         this.deferredGeneratedSessionNames = new WeakMap();
         this.compactionPromptQueues = new Map();
         this.compactionDrainTimers = new Map();
@@ -592,7 +622,6 @@ export class PiSessionService {
         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;
@@ -606,9 +635,11 @@ export class PiSessionService {
         this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.sessionEvents, this.modelRuntime, this.sessionManager, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
             spawn: (input) => this.spawnSubsession(input),
             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.appendSystemPromptSections ?? []);
+            join: (parentSessionId, parentSessionFile, toolCallId) => this.joinSubsessions(parentSessionId, parentSessionFile, toolCallId),
+            prepare: (parentSessionId, parentSessionFile) => this.prepareSubsessionDelivery(parentSessionId, parentSessionFile),
+            check: (parentSessionId, sessionId, parentSessionFile, toolCallId) => this.checkSubsession(parentSessionId, sessionId, parentSessionFile, toolCallId),
+            read: (parentSessionId, sessionId, query, parentSessionFile, toolCallId) => this.readSubsession(parentSessionId, sessionId, query, parentSessionFile, toolCallId),
+        }, deps.askUserEnabled === true, deps.appendSystemPromptSections ?? []);
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
         this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
@@ -725,12 +756,12 @@ export class PiSessionService {
         const activeSessions = Array.from(new Set(this.active.values()));
         for (const active of activeSessions) {
             this.forgetUnreadActivity(active.runtime.session);
-            this.pendingAskStore.forgetSession(active.runtime.session.sessionId);
             this.endSessionExtensionDialogs(active.runtime.session.sessionId);
         }
         this.active.clear();
         this.pendingSessionOpens.clear();
         this.startupSessions.clear();
+        this.suggestedInputs.clear();
         this.activities.clear();
         this.compactionPromptQueues.clear();
         this.authLossWarnings.clear();
@@ -739,6 +770,7 @@ export class PiSessionService {
         this.subsessionLinks.clear();
         this.subsessionHydratedParents.clear();
         this.subsessionNotifyArmed.clear();
+        this.subsessionInboxes.clear();
         this.notificationStore.clearAll("service-dispose");
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
@@ -751,6 +783,7 @@ export class PiSessionService {
                 await active.runtime.dispose();
             }
         })).finally(async () => {
+            this.extensionCommandExecution.disable();
             this.events.mediaIndex.clear();
             await this.activityMarker.dispose();
         });
@@ -764,7 +797,29 @@ export class PiSessionService {
         for (const record of archivedForCwd) {
             this.publishNotificationMutations(this.notificationStore.clearSession(record.sessionId, "archive-reconcile"));
         }
-        const unarchivedSessions = sessions.filter((session) => !archivedById.has(session.id)).map(clientSessionFromListEntry);
+        const unarchivedById = new Map(sessions.filter((session) => !archivedById.has(session.id))
+            .map((session) => [session.id, clientSessionFromListEntry(session)]));
+        // Pi can fork before the first conversational entry without creating a file.
+        // Enumerate already-hosted runtimes only; listing must not open cold sessions.
+        for (const active of new Set(this.active.values())) {
+            const session = active.runtime.session;
+            if (!cwdPathsEqual(session.sessionManager.getCwd(), cwd) || archivedById.has(session.sessionId))
+                continue;
+            const listed = unarchivedById.get(session.sessionId);
+            const tracked = this.subsessionLinkForActiveChild(session) !== undefined;
+            if (listed !== undefined) {
+                // Match the file too: a clone with the same id must not inherit a
+                // live runtime's classification. Disk rows otherwise use the scanner.
+                if (tracked && session.sessionFile !== undefined && sessionPathsEqual(listed.path, session.sessionFile))
+                    listed.agentSubsession = true;
+                continue;
+            }
+            const info = clientSessionFromActiveSession(session);
+            if (tracked)
+                info.agentSubsession = true;
+            unarchivedById.set(session.sessionId, info);
+        }
+        const unarchivedSessions = [...unarchivedById.values()].sort((a, b) => Date.parse(b.modified) - Date.parse(a.modified));
         const reconcilableSessionIds = this.reconcilableSessionIds(cwd, unarchivedSessions.map((session) => session.id), archivedById);
         this.workspaceActivity?.reconcileSessionActivity(cwd, reconcilableSessionIds);
         await this.publishUnreadMutations(this.unreadStore.reconcileCwd(canonicalizeStoredCwd(cwd), reconcilableSessionIds));
@@ -812,29 +867,37 @@ export class PiSessionService {
         }
     }
     async startSession(cwd, options) {
-        const active = await this.create(this.sessionManager.create(cwd, options.parentSession === undefined ? undefined : { parentSession: options.parentSession }), cwd, {
+        const metadata = options.metadata === undefined ? undefined : requireSessionUiMetadata(options.metadata);
+        const name = options.name === undefined ? undefined : requireInitialSessionName(options.name);
+        const manager = this.sessionManager.create(cwd, options.parentSession === undefined ? undefined : { parentSession: options.parentSession });
+        if (metadata !== undefined) {
+            if (manager.appendCustomEntry === undefined)
+                throw new Error("Session manager does not support UI metadata initialization");
+            manager.appendCustomEntry(SESSION_UI_METADATA_CUSTOM_TYPE, { version: 1, metadata });
+        }
+        if (name !== undefined) {
+            if (manager.appendSessionInfo === undefined)
+                throw new Error("Session manager does not support initial naming");
+            manager.appendSessionInfo(name);
+        }
+        const active = await this.create(manager, cwd, {
             startupIntent: "create",
             ...(options.startupToken === undefined ? {} : { startupToken: options.startupToken }),
             ...(options.initialModel === undefined ? {} : { initialModel: options.initialModel }),
             ...(options.initialThinkingLevel === undefined ? {} : { initialThinkingLevel: options.initialThinkingLevel }),
             ...(options.creationProvenance === undefined ? {} : { creationProvenance: options.creationProvenance }),
         });
-        return this.announceCreatedSession(active, cwd, options.parentSession);
+        return options.deferAnnouncement === true
+            ? clientSessionFromActiveSession(active.runtime.session)
+            : this.announceCreatedSession(active, cwd, options.parentSession);
     }
-    announceCreatedSession(active, cwd, parentSession) {
+    announceCreatedSession(active, cwd, parentSession, agentSubsession) {
         const { session } = active.runtime;
         const created = {
-            id: session.sessionId,
-            path: session.sessionFile ?? "",
+            ...clientSessionFromActiveSession(session),
             cwd,
-            persisted: sessionFileExists(session.sessionFile),
-            created: new Date().toISOString(),
-            modified: new Date().toISOString(),
-            messageCount: session.messages.length,
-            firstMessage: "",
-            // Include the parent so listeners can nest the new session in the tree
-            // immediately, instead of showing it flat until the next reload.
             ...(parentSession === undefined ? {} : { parentSessionPath: parentSession }),
+            ...(agentSubsession === true ? { agentSubsession: true } : {}),
         };
         // Broadcast so other clients (and the spawning agent's UI) can add the new
         // session to their list without a manual reload.
@@ -858,6 +921,8 @@ export class PiSessionService {
             ? input.model
             : await this.resolveSpawnModel({ id: input.spawningSessionId, cwd: input.spawningCwd }, input.modelSpec);
         const created = await this.start(decision.cwd, {
+            ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+            ...(input.name === undefined ? {} : { name: input.name }),
             ...(model === undefined ? {} : { initialModel: model }),
             ...(input.thinkingLevel === undefined ? {} : { initialThinkingLevel: input.thinkingLevel }),
         });
@@ -899,6 +964,7 @@ export class PiSessionService {
             ...(model === undefined ? {} : { initialModel: model }),
             ...(input.thinkingLevel === undefined ? {} : { initialThinkingLevel: input.thinkingLevel }),
             creationProvenance: "tracked-subsession",
+            deferAnnouncement: true,
         });
         const modelUsed = this.active.get(created.id)?.runtime.session.model;
         const parentSessionFile = nonEmptyString(input.parentSessionFile);
@@ -912,6 +978,13 @@ export class PiSessionService {
         await this.registerVerifiedSubsession(link);
         this.persistSubsessionLink(link);
         this.persistSubsessionChildMarker(input.parentSessionId, created.id);
+        const active = this.active.get(created.id);
+        if (active === undefined)
+            throw new Error("Tracked subsession disappeared during creation");
+        // Freshly created children are known by this exact runtime/file link even
+        // before Pi flushes its buffered custom entries. Reopened sessions only
+        // enter this registry after reciprocal persisted provenance validation.
+        this.announceCreatedSession(active, decision.cwd, input.parentSessionFile, this.subsessionLinkForActiveChild(active.runtime.session) !== undefined);
         await this.prompt(created, input.prompt);
         this.logger.info({ parentSessionId: input.parentSessionId, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length }, "spawn_subsession started a tracked child session");
         return {
@@ -1052,83 +1125,30 @@ export class PiSessionService {
             throw unknownSpawnModelError(modelSpec);
         return model;
     }
-    /**
-     * Register the question set an agent wants the user to answer as the session's
-     * open ask. Deliberately does not wait for the user: `ask_user` terminates the
-     * run and the submitted answers come back later as a follow-up message.
-     *
-     * Rejected question sets throw {@link PendingAskValidationError}, which the
-     * agent loop reports to the model as an error tool result.
-     */
-    // eslint-disable-next-line @typescript-eslint/require-await -- async so a rejected question set becomes a rejection rather than a synchronous throw from a promise-returning method.
-    async openAsk(input) {
-        const result = this.pendingAskStore.open(input);
-        // A supersede closes the earlier ask, so the browsers watching it must hear
-        // that before they hear about its replacement.
-        if (result.superseded !== undefined)
-            this.publishAskClosed(input.sessionId, result.superseded);
-        this.events.publish(input.sessionId, { type: "ask.opened", ask: result.ask });
-        this.publishStatusForSessionId(input.sessionId);
-        return result;
-    }
-    /**
-     * Record the user's answers to the session's open ask and hand them to the
-     * model. The answers travel as a system-authored custom message rather than a
-     * user message, so they are not attributed to the human in the transcript;
-     * they still wake an idle session (`triggerTurn`) and queue behind in-flight
-     * work (`deliverAs: "followUp"`), which is how the run that `ask_user`
-     * terminated continues.
-     */
+    /** Reply to a durable question entry, even after later conversation or replies. */
     async submitAsk(ref, askId, submission) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
-        // Checked before the store closes the ask so a refused delivery cannot
-        // discard answers the user already submitted.
         this.assertTreeNavigationInactive(session, "answer questions");
-        return this.closeAsk(session, this.pendingAskStore.submit(session.sessionId, askId, submission));
+        const ask = resolveAskUserRequest(await this.readableSessionBranch(ref, session), askId);
+        const outcome = createAskUserOutcome(ask, submission, this.now().toISOString());
+        return this.deliverAskOutcome(session, outcome);
     }
-    /**
-     * Close the open ask without answers. The model is still told, naming every
-     * question as unanswered: it was promised a follow-up message and would
-     * otherwise wait for one that never comes.
-     */
+    /** Skip is also a transcript reply; it does not invalidate future answers. */
     async cancelAsk(ref, askId) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
-        this.assertTreeNavigationInactive(session, "dismiss questions");
-        return this.closeAsk(session, this.pendingAskStore.cancel(session.sessionId, askId));
-    }
-    /**
-     * Publish and deliver a closed ask. A stale close is reported rather than
-     * thrown: losing the race against a supersede, another browser, or a session
-     * that went away is ordinary, and the returned status tells the browser what
-     * the session's open ask is now.
-     */
-    async closeAsk(session, result) {
-        if (result.status === "stale")
-            return { result: "stale", sessionStatus: this.statusFromSession(session) };
-        const { outcome } = result;
-        this.publishAskClosed(session.sessionId, outcome);
+        this.assertTreeNavigationInactive(session, "skip questions");
+        const ask = resolveAskUserRequest(await this.readableSessionBranch(ref, session), askId);
+        return this.deliverAskOutcome(session, createAskUserOutcome(ask, undefined, this.now().toISOString()));
+    }
+    async deliverAskOutcome(session, outcome) {
+        // Pi persists/displays the structured message and wakes an idle agent, or
+        // queues it behind in-flight work. Ordinary entry-mutation protection still
+        // applies, but there is no answer-specific stale/duplicate gate.
         await this.runSessionEntryMutation(session, "deliver answers to your questions", () => session.sendCustomMessage({ customType: ASK_USER_ANSWERS_CUSTOM_TYPE, content: renderAskUserAnswersText(outcome), display: true, details: outcome }, { triggerTurn: true, deliverAs: "followUp" }));
         this.publishStatus(session);
-        return { result: "closed", outcome, sessionStatus: this.statusFromSession(session) };
-    }
-    publishAskClosed(sessionId, outcome) {
-        this.events.publish(sessionId, { type: "ask.closed", askId: outcome.askId, reason: outcome.reason });
-    }
-    /**
-     * Void the session's open ask because the user sent a chat message instead of
-     * answering it. Every browser closes the card as cancelled, and the model is
-     * told — without being woken — so the notice rides into the turn the message
-     * itself triggers rather than becoming a turn of its own.
-     */
-    async voidOpenAskForUserMessage(session) {
-        const outcome = this.pendingAskStore.cancelOpen(session.sessionId);
-        if (outcome === undefined)
-            return;
-        this.publishAskClosed(session.sessionId, outcome);
-        await this.runSessionEntryMutation(session, "void the open questions", () => session.sendCustomMessage({ customType: ASK_USER_ANSWERS_CUSTOM_TYPE, content: renderAskUserAnswersText(outcome), display: true, details: outcome }, { triggerTurn: false, deliverAs: "followUp" }));
-        this.publishStatus(session);
+        return this.statusFromSession(session);
     }
     /**
      * Record the user's answer to an open extension dialog and resolve the
@@ -1277,27 +1297,120 @@ export class PiSessionService {
         const authorizedChildIds = [...childIds].filter((childId) => this.subsessionLinkBelongsToParent(parentSessionId, parentFile, childId));
         return Promise.all(authorizedChildIds.map(async (childId) => ({ sessionId: childId, ...(await this.subsessionSummaryFields(childId)) })));
     }
+    /** Collect ready answers before deciding whether the parent needs to wait. */
+    async joinSubsessions(parentSessionId, parentSessionFile, toolCallId) {
+        const subsessions = await this.listSubsessions(parentSessionId, parentSessionFile);
+        this.reconcileSubsessionCompletions(parentSessionId, parentSessionFile);
+        const completions = this.subsessionInbox(parentSessionId, parentSessionFile).pending();
+        this.receiveSubsessionCompletions(parentSessionId, parentSessionFile, completions, toolCallId);
+        return { subsessions, completions };
+    }
     /** Status and final result of a subsession, scoped to the caller's children. */
-    async checkSubsession(parentSessionId, sessionId, parentSessionFile) {
+    async checkSubsession(parentSessionId, sessionId, parentSessionFile, toolCallId) {
         const session = await this.openSubsession(parentSessionId, sessionId, parentSessionFile);
+        // Finalize the same completion even if its event/heartbeat notification has
+        // not run yet. Inspection must not leave a future notice armed for this run.
+        this.reconcileSubsessionCompletion(session);
+        const status = this.subsessionStatus(session);
         const messages = historyMessages(session);
+        const completion = this.subsessionCompletionForOutput(parentSessionId, parentSessionFile, session, messages);
+        if (status !== "working" && completion !== undefined)
+            this.receiveSubsessionCompletions(parentSessionId, parentSessionFile, [completion], toolCallId);
         return {
             sessionId,
             cwd: session.sessionManager.getCwd(),
-            status: this.subsessionStatus(session),
+            status,
             finalText: finalAssistantText(messages),
             messageCount: messages.length,
+            ...(status === "working" || completion?.errorDetail === undefined ? {} : { errorDetail: completion.errorDetail }),
         };
     }
-    /** Filtered, paginated transcript of a subsession, scoped to the caller's children. */
-    async readSubsession(parentSessionId, sessionId, query, parentSessionFile) {
+    /** Filtered transcript reads acknowledge only the final answer actually returned. */
+    async readSubsession(parentSessionId, sessionId, query, parentSessionFile, toolCallId) {
         const session = await this.openSubsession(parentSessionId, sessionId, parentSessionFile);
-        const view = buildTranscriptView(historyMessages(session), query);
+        this.reconcileSubsessionCompletion(session);
+        const messages = historyMessages(session);
+        const view = buildTranscriptView(messages, query);
+        const status = this.subsessionStatus(session);
+        const completion = this.subsessionCompletionForOutput(parentSessionId, parentSessionFile, session, messages);
+        const errorDetail = status === "working" ? undefined : completion?.errorDetail;
+        if (status !== "working" && completion !== undefined
+            && (transcriptReturnsFinalOutput(messages, view, completion.finalText) || (completion.finalText === "" && errorDetail !== undefined))) {
+            this.receiveSubsessionCompletions(parentSessionId, parentSessionFile, [completion], toolCallId);
+        }
+        return { sessionId, cwd: session.sessionManager.getCwd(), status, ...view, ...(errorDetail === undefined ? {} : { errorDetail }) };
+    }
+    subsessionInbox(parentSessionId, parentSessionFile) {
+        const file = nonEmptyString(parentSessionFile) ?? nonEmptyString(this.active.get(parentSessionId)?.runtime.session.sessionFile);
+        const key = subsessionHydratedParentKey(parentSessionId, file);
+        let inbox = this.subsessionInboxes.get(key);
+        if (inbox === undefined) {
+            inbox = new SubsessionCompletionInbox();
+            this.subsessionInboxes.set(key, inbox);
+        }
+        return inbox;
+    }
+    restoreSubsessionReceipts(session, releaseClaims = true) {
+        this.subsessionInbox(session.sessionId, session.sessionFile).restoreReceipts(session.sessionManager.getBranch(), releaseClaims);
+    }
+    subsessionCompletionForOutput(parentId, parentFile, child, messages) {
+        const branch = persistedSubsessionCompletions(child.sessionManager.getBranch()).filter(({ sessionId }) => sessionId === child.sessionId);
+        // A child can be rewound independently of its parent. Never acknowledge an
+        // abandoned branch's newer result while returning the current branch's text.
+        const completion = branch.at(-1) ?? (child.sessionManager.appendCustomEntry === undefined
+            ? this.subsessionInbox(parentId, parentFile).latest(child.sessionId) : undefined);
+        return completion?.finalText === finalAssistantText(messages) ? completion : undefined;
+    }
+    receiveSubsessionCompletions(parentId, parentFile, completions, toolCallId) {
+        if (completions.length === 0)
+            return;
+        const parent = this.active.get(parentId)?.runtime.session;
+        if (parent === undefined || (parentFile !== undefined && !sessionFileMatches(parent, parentFile))) {
+            throw new Error(`Parent session ${parentId} is not available to receive subsession results`);
+        }
+        const inbox = this.subsessionInbox(parentId, parentFile);
+        const completionIds = completions.map(({ completionId }) => completionId).filter((id) => !inbox.hasReceived(id));
+        if (completionIds.length === 0)
+            return;
+        // Persist before removing unread results. A storage failure leaves the
+        // answer unread and fails the tool instead of losing the notification.
+        this.assertTreeNavigationInactive(parent, "receive subsession results");
+        parent.sessionManager.appendCustomEntry?.(SUBSESSION_RECEIPT_ENTRY_TYPE, { completionIds, ...(toolCallId === undefined ? {} : { toolCallId }) });
+        inbox.receive(completionIds);
+    }
+    reconcileSubsessionCompletions(parentId, parentFile) {
+        for (const childId of this.subsessionChildren.get(parentId) ?? []) {
+            if (!this.subsessionLinkBelongsToParent(parentId, nonEmptyString(parentFile), childId))
+                continue;
+            const link = this.subsessionLinks.get(childId);
+            const child = link === undefined ? undefined : this.activeChildForSubsessionLink(link)?.runtime.session;
+            if (child !== undefined)
+                this.reconcileSubsessionCompletion(child);
+        }
+    }
+    reconcileSubsessionCompletion(session) {
+        this.updateSubsessionTracking(session);
+        if (!this.hasActiveWork(session) && this.subsessionNotifyArmed.get(session.sessionId) === true) {
+            throw new Error(`Could not record completion of subsession ${session.sessionId}; its result remains unread. Retry after fixing session storage.`);
+        }
+    }
+    /** Claims commit on entry_appended (boundary drafts) or message_end (idle wakes). */
+    async prepareSubsessionDelivery(parentId, parentFile) {
+        await this.hydrateSubsessionsForParent(parentId, nonEmptyString(parentFile));
+        const parent = this.active.get(parentId)?.runtime.session;
+        if (parent === undefined || (parentFile !== undefined && !sessionFileMatches(parent, parentFile)))
+            return undefined;
+        // Tool receipts are intents until the successful (possibly nested) result
+        // is persisted. Reconcile those intents without releasing in-flight drafts.
+        this.restoreSubsessionReceipts(parent, false);
+        this.reconcileSubsessionCompletions(parentId, parentFile);
+        const completions = this.subsessionInbox(parentId, parentFile).claim();
+        if (completions.length === 0)
+            return undefined;
         return {
-            sessionId,
-            cwd: session.sessionManager.getCwd(),
-            status: this.subsessionStatus(session),
-            ...view,
+            type: "custom_message", customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, display: true,
+            content: renderSubsessionCompletions(completions, this.workingSubsessionIds(parentId)),
+            details: { sessionId: completions[0]?.sessionId, completionIds: completions.map(({ completionId }) => completionId) },
         };
     }
     /** Open a session after verifying it is one of the caller's tracked children. */
@@ -1351,6 +1464,14 @@ export class PiSessionService {
         this.subsessionLinks.set(childSessionId, link);
         if (!this.subsessionNotifyArmed.has(childSessionId))
             this.subsessionNotifyArmed.set(childSessionId, false);
+        const childManager = this.activeChildForSubsessionLink(link)?.runtime.session.sessionManager
+            ?? (link.childSessionFile === undefined ? undefined : this.sessionManager.open(link.childSessionFile));
+        if (childManager !== undefined) {
+            for (const completion of persistedSubsessionCompletions(childManager.getEntries?.() ?? childManager.getBranch())) {
+                if (completion.sessionId === childSessionId)
+                    this.subsessionInbox(parentSessionId, link.parentSessionFile).record(completion);
+            }
+        }
         const cwd = this.cwdForVerifiedSubsession(link);
         await this.publishUnreadMutations(this.unreadStore.excludeSession(childSessionId, cwd));
     }
@@ -1375,6 +1496,8 @@ export class PiSessionService {
         this.subsessionParents.delete(childSessionId);
         this.subsessionLinks.delete(childSessionId);
         this.subsessionNotifyArmed.delete(childSessionId);
+        for (const inbox of this.subsessionInboxes.values())
+            inbox.forgetChild(childSessionId);
         if (parentSessionId === undefined)
             return;
         const children = this.subsessionChildren.get(parentSessionId);
@@ -1531,7 +1654,7 @@ export class PiSessionService {
      * working. Prompt failures before agent_start explicitly arm the same latch.
      * Standalone commands and compactions must not arm a completion notice.
      */
-    updateSubsessionTracking(session, agentStarted = false) {
+    updateSubsessionTracking(session, agentStarted = false, agentSettled = false) {
         const link = this.subsessionLinkForActiveChild(session);
         if (link === undefined)
             return;
@@ -1540,22 +1663,31 @@ export class PiSessionService {
             this.subsessionNotifyArmed.set(childId, true);
             return;
         }
-        if (this.hasActiveWork(session))
+        // Native settlement is authoritative even while the host prompt Promise's
+        // mutation receipt is unwinding. Capture now, before another run can start.
+        if (!agentSettled && this.hasActiveWork(session))
             return;
         if (this.subsessionNotifyArmed.get(childId) !== true)
             return;
-        this.subsessionNotifyArmed.set(childId, false);
         const activity = this.activities.get(childId);
-        const status = activity?.phase === "error" ? "error" : "idle";
-        const errorSection = status === "error" && activity?.detail !== undefined ? `Error: ${activity.detail}\n\n` : "";
-        const finalText = finalAssistantText(historyMessages(session));
-        const outputSection = formatSubsessionNotificationOutput(childId, finalText);
-        const workingIds = this.workingSubsessionIds(link.parentSessionId);
-        const next = workingIds.length === 0
-            ? "No other tracked subsessions are working."
-            : `Still working: ${workingIds.join(", ")}. Continue working, or call yield_to_subsessions alone and last at the next join point. Further completion notices arrive automatically; do not poll.`;
-        const text = `Subsession ${childId} stopped working (${status}).\n${next}\n\n${errorSection}${outputSection}`;
-        void this.notifyParentOfSubsession(link.parentSessionId, childId, text);
+        const messages = historyMessages(session);
+        const completion = {
+            completionId: randomUUID(), sessionId: childId, cwd: session.sessionManager.getCwd(),
+            status: activity?.phase === "error" ? "error" : "idle",
+            finalText: finalAssistantText(messages), messageCount: messages.length,
+            ...(activity?.phase !== "error" || activity.detail === undefined ? {} : { errorDetail: activity.detail }),
+        };
+        try {
+            session.sessionManager.appendCustomEntry?.(SUBSESSION_COMPLETION_ENTRY_TYPE, completion);
+        }
+        catch (error) {
+            // Keep the latch armed so a later reconciliation can retry persistence.
+            this.logSubsessionNotificationFailure(link.parentSessionId, childId, error);
+            return;
+        }
+        this.subsessionNotifyArmed.set(childId, false);
+        this.subsessionInbox(link.parentSessionId, link.parentSessionFile).record(completion);
+        void this.wakeParentForSubsession(link.parentSessionId, childId);
     }
     async getOrOpenParentForSubsession(parentSessionId, childSessionId) {
         const link = this.subsessionLinks.get(childSessionId);
@@ -1573,35 +1705,69 @@ export class PiSessionService {
         const sessionManager = this.sessionManager.open(parentSessionFile);
         return (await this.create(sessionManager, sessionManager.getCwd())).runtime.session;
     }
-    /**
-     * Deliver a subsession-completion notice to the parent as a system-authored
-     * custom message rather than a user message, so it is not attributed to the
-     * human in the transcript. It still wakes an idle parent (`triggerTurn`) and
-     * queues behind in-flight work (`deliverAs: "followUp"`), preserving the
-     * established "queue if busy, send and act if idle" behavior.
-     */
-    async notifyParentOfSubsession(parentId, childId, text) {
+    async wakeParentForSubsession(parentId, childId) {
         try {
             const session = await this.getOrOpenParentForSubsession(parentId, childId);
-            if (this.treeNavigations.has(session)) {
-                const pending = this.deferredSubsessionNotifications.get(session) ?? [];
-                pending.push({ parentId, childId, text });
-                this.deferredSubsessionNotifications.set(session, pending);
-                return;
-            }
-            await this.deliverSubsessionNotification(session, { parentId, childId, text });
+            this.scheduleSubsessionDelivery(session);
         }
         catch (error) {
             this.logSubsessionNotificationFailure(parentId, childId, error);
         }
     }
-    async deliverSubsessionNotification(session, notification) {
-        await this.runSessionEntryMutation(session, "deliver a subsession notification", () => session.sendCustomMessage({ customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, content: notification.text, display: true, details: { sessionId: notification.childId } }, { triggerTurn: true, deliverAs: "followUp" }));
-        this.publishStatus(session);
+    /** Busy parents keep results in the inbox; never enqueue a second copy in Pi. */
+    async deliverPendingSubsessionCompletions(session) {
+        if (this.hasActiveWork(session) || !this.isCurrentActiveSession(session) || this.subsessionStoppedParents.has(session))
+            return;
+        const inbox = this.subsessionInbox(session.sessionId, session.sessionFile);
+        const completions = inbox.claim();
+        if (completions.length === 0)
+            return;
+        const completionIds = completions.map(({ completionId }) => completionId);
+        this.subsessionDeliveringParents.add(session);
+        let delivered = false;
+        try {
+            await this.runSessionEntryMutation(session, "deliver subsession results", () => session.sendCustomMessage({
+                customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, display: true,
+                content: renderSubsessionCompletions(completions, this.workingSubsessionIds(session.sessionId)),
+                details: { sessionId: completions[0]?.sessionId, completionIds },
+            }, { triggerTurn: true }));
+            inbox.receive(completionIds);
+            delivered = true;
+        }
+        catch (error) {
+            this.subsessionStoppedParents.add(session);
+            throw error;
+        }
+        finally {
+            inbox.release(completionIds);
+            this.subsessionDeliveringParents.delete(session);
+            if (delivered)
+                this.scheduleSubsessionDelivery(session);
+            this.publishStatus(session);
+        }
+    }
+    scheduleSubsessionDelivery(session) {
+        if (this.subsessionDeliveryScheduled.has(session) || this.subsessionInbox(session.sessionId, session.sessionFile).pending().length === 0)
+            return;
+        this.subsessionDeliveryScheduled.add(session);
+        // Settlement can precede the host prompt-mutation receipt's finally block.
+        // Recheck on the next tick, closing the yield/child-completion race without
+        // restarting a stopped run or putting rendered answers in a follow-up queue.
+        setTimeout(() => {
+            this.subsessionDeliveryScheduled.delete(session);
+            void this.deliverPendingSubsessionCompletions(session).catch((error) => {
+                this.logSubsessionNotificationFailure(session.sessionId, "inbox", error);
+            });
+        }, 0);
     }
     logSubsessionNotificationFailure(parentId, childId, error) {
         this.logger.info({ parentSessionId: parentId, sessionId: childId, error: error instanceof Error ? error.message : String(error) }, "failed to notify parent of subsession completion");
     }
+    browserTranscriptMessage(session, message) {
+        return projectTranscriptMarkdown(message, session.extensionRunner.getMarkdownTransformers(), (error, transformerIndex) => {
+            this.logger.info({ err: error, sessionId: session.sessionId, transformerIndex }, "Transcript Markdown transformer failed");
+        });
+    }
     async transcriptSnapshot(ref, page) {
         const session = await this.getOrOpen(ref);
         const seqBeforeRead = this.events.currentSeq(session.sessionId);
@@ -1616,8 +1782,9 @@ export class PiSessionService {
         const userCount = messages.filter((message) => isRecord(message) && message["role"] === "user").length;
         const echoes = (this.pendingPromptEchoes.get(session) ?? []).filter((echo) => echo.userIndex >= userCount);
         messages.push(...echoes.map((echo) => echo.message));
+        const messagePage = pageMessagesAtSafeBoundary(messages, page);
         return {
-            page: pageMessagesAtSafeBoundary(messages, page),
+            page: { ...messagePage, messages: messagePage.messages.map((message) => this.browserTranscriptMessage(session, message)) },
             status: this.statusFromSession(session, transcriptMessageCount(branch) + echoes.length),
             seq: this.events.currentSeq(session.sessionId),
             partial: this.publishedAssistantPartials.get(session) ?? null,
@@ -1625,7 +1792,8 @@ export class PiSessionService {
     }
     async messages(ref, page) {
         const session = await this.getOrOpen(ref);
-        return pageMessagesAtSafeBoundary(historyMessagesFromEntries(await this.readableSessionBranch(ref, session)), page);
+        const result = pageMessagesAtSafeBoundary(historyMessagesFromEntries(await this.readableSessionBranch(ref, session)), page);
+        return { ...result, messages: result.messages.map((message) => this.browserTranscriptMessage(session, message)) };
     }
     async media(ref, mediaId) {
         if (!isSessionMediaId(mediaId))
@@ -1899,11 +2067,6 @@ export class PiSessionService {
             this.publishStatus(session);
             return;
         }
-        // A chat message answers the session's open ask in the user's own words, so
-        // the form is void: keeping it open would invite answers to questions the
-        // conversation has already moved past. Ignored duplicates skip this on
-        // purpose: they must not void an ask posted after the queued original.
-        await this.voidOpenAskForUserMessage(session);
         if (session.isCompacting) {
             this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images, echoUserMessage);
             return;
@@ -1924,7 +2087,7 @@ export class PiSessionService {
             // SDK input hooks may await before appending the user message. Keep the
             // already-published echo visible in snapshots until that append occurs.
             this.pendingPromptEchoes.set(session, [...echoes, echo]);
-            this.events.publish(session.sessionId, { type: "message.append", message: echo.message }, { id: session.sessionId, cwd: session.sessionManager.getCwd() });
+            this.events.publish(session.sessionId, { type: "message.append", message: this.browserTranscriptMessage(session, echo.message) }, { id: session.sessionId, cwd: session.sessionManager.getCwd() });
         }
         const promptOptions = buildPromptOptions(behavior, images);
         const commandName = text.startsWith("/") ? text.slice(1).split(" ")[0] : undefined;
@@ -1936,7 +2099,12 @@ export class PiSessionService {
             if (getString(event, "type") === "agent_start")
                 agentStarted = true;
         });
-        const promptPromise = this.runSessionEntryMutation(session, "send a prompt", () => session.prompt(text, promptOptions)).finally(() => {
+        const submission = { session, active: true };
+        const isExtensionCommand = session.extensionRunner.getRegisteredCommands().some((command) => command.invocationName === commandName);
+        const promptPromise = this.runSessionEntryMutation(session, "send a prompt", () => isExtensionCommand
+            ? this.extensionCommandExecution.run({ submission }, () => session.prompt(text, promptOptions))
+            : session.prompt(text, promptOptions)).finally(() => {
+            submission.active = false;
             unsubscribe?.();
             if (echo !== undefined) {
                 const remaining = (this.pendingPromptEchoes.get(session) ?? []).filter((pending) => pending !== echo);
@@ -1947,6 +2115,7 @@ export class PiSessionService {
             }
         });
         void promptPromise.catch((error) => {
+            this.subsessionStoppedParents.add(session);
             const message = error instanceof Error ? error.message : String(error);
             this.publishActivity(session, "error", "error", message);
             this.events.publish(session.sessionId, { type: "session.error", message });
@@ -2089,15 +2258,20 @@ export class PiSessionService {
         return this.commandService.respond(active.runtime.session.sessionId, requestId, value);
     }
     async navigateTree(ref, request) {
-        if (request.targetId.trim() === "")
+        return this.navigateSessionTree(ref, request.targetId, request.expectedLeafId, sessionTreeNavigationOptions(request), undefined, request.retainCheckpoint);
+    }
+    async navigateSessionTree(ref, targetId, expectedLeafId, options, expectedSession, retainCheckpoint = false) {
+        if (targetId.trim() === "")
             throw new Error("Session tree target is required");
         if (this.isTreeExclusiveSessionIdentityActive(ref.id)) {
             throw new Error("Stop current session activity before navigating the session tree");
         }
         await this.assertWritable(ref);
-        const options = sessionTreeNavigationOptions(request);
         const session = await this.getOrOpen(ref);
-        if (typeof session.navigateTree !== "function")
+        if (expectedSession !== undefined && session !== expectedSession)
+            throw new Error("This extension command belongs to an unavailable session runtime");
+        const navigateTree = session.navigateTree?.bind(session);
+        if (navigateTree === undefined)
             throw new Error("Session tree navigation is not supported by this Pi runtime");
         if (this.hasActiveWork(session))
             throw new Error("Stop current session activity before navigating the session tree");
@@ -2106,13 +2280,22 @@ export class PiSessionService {
         this.treeNavigations.add(session);
         try {
             const oldLeafId = session.sessionManager.getLeafId();
-            if (oldLeafId !== request.expectedLeafId) {
+            if (oldLeafId !== expectedLeafId) {
                 throw new Error("The session changed since /tree was opened. Reopen /tree and try again.");
             }
-            const activeEditableTargetParentId = activeEditableTreeTargetParentId(session.sessionManager, request.targetId, oldLeafId);
-            this.publishActivity(session, options.summarize ? "summarizing branch" : "navigating session tree", "active");
+            if (retainCheckpoint)
+                targetId = messageHistoryTargetId(session.sessionManager.getBranch(), targetId);
+            const checkpointTail = retainCheckpoint ? session.sessionManager.getBranch().find((entry) => isRecord(entry) && entry["id"] === targetId) : undefined;
+            const retainCustomMessage = isRecord(checkpointTail) && checkpointTail["type"] === "custom_message";
+            if (retainCustomMessage && options.summarize === true) {
+                throw new Error("Retaining a custom-message checkpoint requires navigation without a branch summary");
+            }
+            const activeEditableTargetParentId = retainCustomMessage ? undefined : activeEditableTreeTargetParentId(session.sessionManager, targetId, oldLeafId);
+            this.publishActivity(session, options.summarize === true ? "summarizing branch" : "navigating session tree", "active");
             this.publishStatus(session);
-            let result = await session.navigateTree(request.targetId, options);
+            let result = retainCustomMessage
+                ? await navigateTreeRetainingCustomMessage(session.sessionManager, targetId, checkpointTail["parentId"], () => navigateTree(targetId, options))
+                : await navigateTree(targetId, options);
             if (activeEditableTargetParentId !== undefined
                 && !result.cancelled
                 && result.editorText === undefined
@@ -2124,14 +2307,14 @@ export class PiSessionService {
                 // extraction, agent-context rebuilding, and tree extension events.
                 setSessionTreeLeaf(session.sessionManager, activeEditableTargetParentId);
                 try {
-                    result = await session.navigateTree(request.targetId, options);
+                    result = await navigateTree(targetId, options);
                 }
                 catch (error) {
-                    session.sessionManager.branch(request.targetId);
+                    session.sessionManager.branch(targetId);
                     throw error;
                 }
                 if (result.cancelled)
-                    session.sessionManager.branch(request.targetId);
+                    session.sessionManager.branch(targetId);
             }
             if (result.cancelled) {
                 if (this.isCurrentActiveSession(session)) {
@@ -2139,13 +2322,6 @@ export class PiSessionService {
                 }
                 return { cancelled: true, ...(result.aborted === undefined ? {} : { aborted: result.aborted }) };
             }
-            if (session.sessionManager.getLeafId() !== oldLeafId) {
-                // Questions belong to the position we left. Close them for every browser
-                // without appending a cancellation message or waking the rewound session.
-                const outcome = this.pendingAskStore.cancelOpen(session.sessionId);
-                if (outcome !== undefined)
-                    this.publishAskClosed(session.sessionId, outcome);
-            }
             if (result.summaryEntry !== undefined) {
                 // A summary entry durably identifies the selected branch as the file's
                 // newest leaf, superseding any earlier bare selection.
@@ -2159,6 +2335,8 @@ export class PiSessionService {
                     this.unpersistedTreeBranchLeaves.set(session, selectedLeafId);
                 }
             }
+            this.setSuggestedInput(session.sessionId, result.editorText);
+            this.events.publish(session.sessionId, { type: "session.tree.changed" });
             if (this.isCurrentActiveSession(session))
                 this.publishActivity(session, "session tree navigated", "idle");
             return { cancelled: false, ...(result.editorText === undefined ? {} : { editorText: result.editorText }) };
@@ -2179,7 +2357,6 @@ export class PiSessionService {
             }
             else {
                 this.deferredGeneratedSessionNames.delete(session);
-                this.deferredSubsessionNotifications.delete(session);
             }
         }
     }
@@ -2190,6 +2367,9 @@ export class PiSessionService {
      * about to join rather than the forked-from record.
      */
     async forkFromTree(ref, request) {
+        return this.forkSessionTree(ref, request);
+    }
+    async forkSessionTree(ref, request, options, expectedSession) {
         if (request.entryId.trim() === "")
             throw new Error("Session tree entry is required");
         if (this.isTreeExclusiveSessionIdentityActive(ref.id)) {
@@ -2197,6 +2377,8 @@ export class PiSessionService {
         }
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
+        if (expectedSession !== undefined && session !== expectedSession)
+            throw new Error("This extension command belongs to an unavailable session runtime");
         if (this.hasActiveWork(session))
             throw new Error("Stop current session activity before forking the session tree");
         if (session.sessionManager.getLeafId() !== request.expectedLeafId) {
@@ -2205,8 +2387,15 @@ export class PiSessionService {
         this.publishActivity(session, "forking session from entry", "active");
         this.publishStatus(session);
         try {
-            const result = await this.commandService.forkEntry(session.sessionId, request.entryId, {
+            // forkEntry rechecks this same leaf after asynchronous naming and inside
+            // the replacement gate, so the resolved branch cutoff cannot go stale.
+            const entryId = request.retainCheckpoint === true
+                ? messageHistoryTargetId(session.sessionManager.getBranch(), request.entryId)
+                : request.entryId;
+            const result = await this.commandService.forkEntry(session.sessionId, entryId, {
+                ...options,
                 expectedLeafId: request.expectedLeafId,
+                expectedSession: session,
             });
             if (result.type === "unsupported")
                 throw new Error(result.message);
@@ -2219,6 +2408,8 @@ export class PiSessionService {
                 }
                 return { cancelled: true };
             }
+            this.setSuggestedInput(result.session.id, result.promptDraft);
+            this.events.publish(session.sessionId, { type: "session.tree.changed" });
             const forkedSession = this.active.get(result.session.id)?.runtime.session;
             if (forkedSession !== undefined && this.isCurrentActiveSession(forkedSession)) {
                 this.publishActivity(forkedSession, "session forked", "idle");
@@ -2267,9 +2458,16 @@ export class PiSessionService {
             this.publishActivity(session, "reloading resources", "active");
             const priorGeneration = this.notificationGenerationBySession.get(session);
             let candidateGeneration;
+            const reloadBoundary = { beforeSessionStart: false };
             try {
-                await session.reload(priorGeneration === undefined ? undefined : {
+                await session.reload({
                     beforeSessionStart: () => {
+                        // The SDK invalidated the old runner. Settle its dialogs before
+                        // replacement session_start handlers can open new ones.
+                        this.endSessionExtensionDialogs(session.sessionId);
+                        reloadBoundary.beforeSessionStart = true;
+                        if (priorGeneration === undefined)
+                            return;
                         candidateGeneration = this.notificationStore.beginReplacement(priorGeneration, notificationIdentityForSession(session));
                         this.notificationGenerationBySession.set(session, candidateGeneration);
                         this.replaceSessionNotificationContext(session, candidateGeneration);
@@ -2282,6 +2480,10 @@ export class PiSessionService {
                 this.publishStatus(session);
             }
             catch (error) {
+                // Settings/resource loading can fail after SDK invalidation but
+                // before the hook. Never sweep replacement session_start dialogs.
+                if (!reloadBoundary.beforeSessionStart)
+                    this.endSessionExtensionDialogs(session.sessionId);
                 if (candidateGeneration !== undefined) {
                     this.publishNotificationMutations(this.notificationStore.abortReplacement(candidateGeneration, "candidate"));
                     this.notificationGenerationBySession.set(session, candidateGeneration);
@@ -2390,7 +2592,7 @@ export class PiSessionService {
     async archiveTree(ref) {
         const session = await this.getOrOpen(ref);
         const catalog = await this.workspaceArchiveCandidates(session.sessionManager.getCwd());
-        const root = findArchiveCandidateByIdOrPrefix(catalog, session.sessionId) ?? archiveCandidateFromActiveSession(session, false);
+        const root = findArchiveCandidateByExactId(catalog, session.sessionId) ?? archiveCandidateFromActiveSession(session, false);
         const plan = planSessionArchiveTree(root, catalog);
         const busy = plan.targets.map((target) => target.activeSession).find((target) => target !== undefined && this.hasActiveWork(target));
         if (busy !== undefined)
@@ -2536,6 +2738,7 @@ export class PiSessionService {
             return;
         const sessionId = active.runtime.session.sessionId;
         this.clearCompactionPromptQueue(sessionId);
+        this.subsessionStoppedParents.add(active.runtime.session);
         clearSessionQueue(active.runtime.session);
         // Settle run-scoped dialogs now, at abort-request time: pi's agent loop
         // waits for a parked `tool_call` dialog handler before it can emit
@@ -2706,6 +2909,7 @@ export class PiSessionService {
         if (pendingOpens.length > 0)
             await Promise.allSettled(pendingOpens);
         const active = this.active.get(sessionId);
+        this.suggestedInputs.delete(sessionId);
         if (notificationPolicy.kind === "clear") {
             const generation = active === undefined ? undefined : this.notificationGenerationBySession.get(active.runtime.session);
             const mutations = generation === undefined
@@ -2716,11 +2920,8 @@ export class PiSessionService {
         if (!active)
             return;
         this.forgetUnreadActivity(active.runtime.session);
-        // An open ask is meaningful only while the runtime that posted it exists: no
-        // one is left to receive the answers, so it is dropped without an outcome.
-        this.pendingAskStore.forgetSession(sessionId);
-        // Open dialogs share that stance, but their extension waiters are parked
-        // Promises inside the dying runtime: settle them rather than dropping them.
+        // Extension dialog waiters are parked Promises inside the dying runtime:
+        // settle them rather than dropping them.
         this.endSessionExtensionDialogs(sessionId);
         this.active.delete(sessionId);
         this.events.mediaIndex.forgetSession({ id: sessionId, cwd: active.runtime.session.sessionManager.getCwd() });
@@ -2898,26 +3099,12 @@ export class PiSessionService {
         return { id: sessionId, cwd: active.runtime.cwd };
     }
     activeForRef(ref) {
-        const sessionId = ref.id;
-        const exact = this.active.get(sessionId);
-        if (exact !== undefined && refMatchesActiveSession(ref, exact))
-            return exact;
-        for (const [candidateId, active] of this.active.entries()) {
-            if (candidateId.startsWith(sessionId) && refMatchesActiveSession(ref, active))
-                return active;
-        }
-        return undefined;
+        const active = this.active.get(ref.id);
+        return active !== undefined && refMatchesActiveSession(ref, active) ? active : undefined;
     }
     startupSessionForRef(ref) {
-        const sessionId = ref.id;
-        const exact = this.startupSessions.get(sessionId);
-        if (exact !== undefined && refMatchesStartupSession(ref, exact))
-            return exact;
-        for (const [candidateId, session] of this.startupSessions.entries()) {
-            if (candidateId.startsWith(sessionId) && refMatchesStartupSession(ref, session))
-                return session;
-        }
-        return undefined;
+        const session = this.startupSessions.get(ref.id);
+        return session !== undefined && refMatchesStartupSession(ref, session) ? session : undefined;
     }
     /**
      * The session to serve a read-only status or a dialog close for, while it
@@ -3026,7 +3213,13 @@ export class PiSessionService {
                     // holds for this session; settle those waits before the new
                     // runtime's extensions can open fresh dialogs under the same id.
                     this.endSessionExtensionDialogs(boundSession.sessionId);
+                    const changedIdentity = boundSession.sessionId !== session.sessionId;
                     boundSession = session;
+                    // Publish existence as soon as status/dialog APIs can address it,
+                    // before session_start or arbitrary withSession code can park on a question.
+                    this.startupSessions.set(session.sessionId, session);
+                    if (changedIdentity)
+                        this.announceCreatedSession(active, session.sessionManager.getCwd());
                     await this.bindSessionExtensions(session, candidateGeneration);
                     if (candidateGeneration !== undefined) {
                         this.publishNotificationMutations(this.notificationStore.commitReplacement(candidateGeneration));
@@ -3101,6 +3294,7 @@ export class PiSessionService {
             await session.bindExtensions({
                 uiContext,
                 mode: "rpc",
+                commandContextActions: this.extensionCommandActions(session),
                 onError: (error) => {
                     const message = `${error.extensionPath}: ${error.error}`;
                     this.publishActivity(session, "extension error", "error", message);
@@ -3115,6 +3309,83 @@ export class PiSessionService {
             this.startupSessions.delete(session.sessionId);
         }
     }
+    extensionCommandActions(session) {
+        const ref = { id: session.sessionId, cwd: session.sessionManager.getCwd() };
+        return {
+            waitForIdle: () => {
+                this.assertCurrentExtensionSession(session);
+                return session.waitForIdle();
+            },
+            navigateTree: (targetId, options) => {
+                const expectedLeafId = session.sessionManager.getLeafId();
+                return this.runExtensionSessionControl(session, async () => {
+                    const result = await this.navigateSessionTree(ref, targetId, expectedLeafId, options ?? { summarize: false }, session);
+                    return { cancelled: result.cancelled };
+                });
+            },
+            fork: (entryId, options) => {
+                const expectedLeafId = session.sessionManager.getLeafId();
+                const withSession = options?.withSession;
+                let completeReplacement;
+                const forkOptions = {
+                    ...options,
+                    position: options?.position ?? "before",
+                    // Capture Pi's fresh context, but run user code after the host's
+                    // replacement reservation is released so fresh controls can work.
+                    ...(withSession === undefined ? {} : { withSession: (ctx) => {
+                            completeReplacement = () => withSession(ctx);
+                            return Promise.resolve();
+                        } }),
+                };
+                return this.runExtensionSessionControl(session, async () => {
+                    const runtime = this.active.get(ref.id)?.runtime;
+                    const result = await this.forkSessionTree(ref, { entryId, expectedLeafId }, forkOptions, session);
+                    if (!result.cancelled) {
+                        try {
+                            await completeReplacement?.();
+                        }
+                        catch (error) {
+                            // The fork is committed. Report callback failure on the current
+                            // runtime (which may have forked again), including its recoverable inbox.
+                            const current = runtime?.session;
+                            if (current !== undefined && this.isCurrentActiveSession(current)) {
+                                const message = errorMessage(error);
+                                current.extensionRunner.getUIContext().notify(message, "error");
+                                this.publishActivity(current, "extension callback failed", "error", message);
+                                this.events.publish(current.sessionId, { type: "session.error", message });
+                            }
+                            throw error;
+                        }
+                    }
+                    return { cancelled: result.cancelled };
+                });
+            },
+            reload: () => this.runExtensionSessionControl(session, () => this.reloadSessionRuntime(session)),
+            // These need host-owned creation/selection policies, not SDK runtime-only
+            // replacement. Fail visibly until PI WEB supplies that integration.
+            newSession: () => Promise.reject(new Error("ctx.newSession() is not supported in PI WEB. Start a new session from the web UI.")),
+            switchSession: () => Promise.reject(new Error("ctx.switchSession() is not supported in PI WEB. Select a session from the web UI.")),
+        };
+    }
+    setSuggestedInput(sessionId, text) {
+        if (text === undefined || text === "")
+            this.suggestedInputs.delete(sessionId);
+        else
+            this.suggestedInputs.set(sessionId, text);
+    }
+    assertCurrentExtensionSession(session) {
+        if (!this.isCurrentActiveSession(session) || this.startupSessions.has(session.sessionId)) {
+            throw new Error("This extension command belongs to an unavailable session runtime");
+        }
+    }
+    runExtensionSessionControl(session, operation) {
+        return this.extensionCommandExecution.run({ ...this.extensionCommandExecution.getStore(), sessionControl: true }, async () => {
+            this.assertCurrentExtensionSession(session);
+            await this.assertWritable({ id: session.sessionId, cwd: session.sessionManager.getCwd() });
+            this.assertCurrentExtensionSession(session);
+            return operation();
+        });
+    }
     replaceSessionNotificationContext(session, generation) {
         session.extensionRunner.setUIContext(this.sessionUiContext(session, generation), "rpc");
     }
@@ -3291,9 +3562,30 @@ export class PiSessionService {
                     this.clearCompactionPromptQueue(sessionId);
             }
         }
+        this.restoreSubsessionReceipts(session);
         const unsubscribe = session.subscribe((event) => {
             const eventType = getString(event, "type");
             const message = getProperty(event, "message");
+            const inbox = this.subsessionInbox(session.sessionId, session.sessionFile);
+            if (eventType === "agent_start") {
+                this.restoreSubsessionReceipts(session, false);
+                this.subsessionStoppedParents.delete(session);
+            }
+            if (eventType === "message_end" && getString(message, "role") === "assistant"
+                && (getString(message, "stopReason") === "aborted" || getString(message, "stopReason") === "error")) {
+                this.subsessionStoppedParents.add(session);
+            }
+            const entry = getProperty(event, "entry");
+            if (eventType === "entry_appended" && getString(entry, "type") === "custom_message"
+                && getString(entry, "customType") === SUBSESSION_NOTIFICATION_CUSTOM_TYPE) {
+                inbox.receive(completionReceiptIds(getProperty(entry, "details")));
+            }
+            // message_end listeners run before SDK persistence. These later
+            // boundaries can safely reconcile committed messages and failed intents.
+            if (eventType === "turn_end" || eventType === "agent_settled")
+                this.restoreSubsessionReceipts(session);
+            if (eventType === "agent_settled")
+                this.scheduleSubsessionDelivery(session);
             if ((eventType === "message_start" || eventType === "message_update") && getString(message, "role") === "assistant") {
                 // SDK state advances before async extension hooks finish. Capture only
                 // published messages, detaching even blocks left intact by projection.
@@ -3302,25 +3594,24 @@ export class PiSessionService {
             else if (eventType === "message_start" || eventType === "message_end" || eventType === "agent_end") {
                 this.publishedAssistantPartials.delete(session);
             }
-            this.events.publish(session.sessionId, toClientEvent(event, session.thinkingLevel), { id: session.sessionId, cwd: session.sessionManager.getCwd() });
-            this.publishActivityForEvent(session, event);
-            // Queued messages can reach the model after an ask opened, even though
-            // there was no ask to dismiss when the user originally submitted them.
-            if (eventType === "message_start" && isRecord(event) && getString(event["message"], "role") === "user") {
-                void this.voidOpenAskForUserMessage(session).catch((error) => {
-                    const message = error instanceof Error ? error.message : String(error);
-                    this.publishActivity(session, "error", "error", message);
-                    this.events.publish(session.sessionId, { type: "session.error", message });
-                });
+            const clientEvent = toClientEvent(event, session.thinkingLevel);
+            if ((clientEvent.type === "message.end" || clientEvent.type === "message.append") && clientEvent.message !== undefined) {
+                clientEvent.message = this.browserTranscriptMessage(session, clientEvent.message);
             }
+            this.events.publish(session.sessionId, clientEvent, { id: session.sessionId, cwd: session.sessionManager.getCwd() });
+            this.publishActivityForEvent(session, event);
+            if (eventType === "message_start" && getString(message, "role") === "user")
+                this.suggestedInputs.delete(session.sessionId);
             if (eventType === "agent_end")
                 this.abortRunScopedExtensionDialogs(session.sessionId);
             if (eventType === "compaction_end")
                 this.scheduleCompactionQueueDrain(session.sessionId);
+            if (eventType === "compaction_end" || eventType === "bash_execution_end")
+                this.scheduleSubsessionDelivery(session);
             if (eventType === "agent_start" || eventType === "agent_end")
                 this.scheduleCompactionQueueDrain(session.sessionId);
             this.publishStatus(session);
-            this.updateSubsessionTracking(session, eventType === "agent_start");
+            this.updateSubsessionTracking(session, eventType === "agent_start", eventType === "agent_settled");
         });
         active.unsubscribe = () => {
             this.sessionEvents.close(session);
@@ -3391,11 +3682,6 @@ export class PiSessionService {
     maybeGenerateSessionName(session, firstMessage) {
         if (session.sessionName !== undefined || session.messages.length !== 0 || session.isStreaming || session.isCompacting)
             return;
-        const deterministicName = deterministicSessionName(firstMessage);
-        if (deterministicName !== undefined) {
-            this.applyGeneratedSessionName(session, deterministicName);
-            return;
-        }
         const model = session.model;
         if (model === undefined)
             return;
@@ -3426,13 +3712,8 @@ export class PiSessionService {
                 this.logger.info({ sessionId: session.sessionId, error: error instanceof Error ? error.message : String(error) }, "failed to apply deferred session name");
             }
         }
-        const notifications = this.deferredSubsessionNotifications.get(session) ?? [];
-        this.deferredSubsessionNotifications.delete(session);
-        for (const notification of notifications) {
-            void this.deliverSubsessionNotification(session, notification).catch((error) => {
-                this.logSubsessionNotificationFailure(notification.parentId, notification.childId, error);
-            });
-        }
+        this.restoreSubsessionReceipts(session);
+        this.scheduleSubsessionDelivery(session);
     }
     applyAuthChange(change = {}) {
         // ModelRuntime.login()/logout() refresh the shared runtime before AuthService
@@ -3518,8 +3799,11 @@ export class PiSessionService {
         return "active";
     }
     hasActiveWork(session) {
+        const execution = this.extensionCommandExecution.getStore();
+        const ownCommandReceipt = execution?.sessionControl === true
+            && execution.submission?.active === true && execution.submission.session === session ? 1 : 0;
         return this.treeNavigations.has(session)
-            || this.isSessionEntryMutationActive(session)
+            || this.isSessionEntryMutationActive(session, ownCommandReceipt)
             || this.isTreeExclusiveOperationActive(session)
             || sessionHasActiveWork(session, this.compactionQueuedMessages(session.sessionId).length);
     }
@@ -3601,9 +3885,11 @@ export class PiSessionService {
         else
             this.sessionEntryMutationCounts.set(session, remaining);
         this.observeUnreadActivityState(session);
+        if (remaining <= 0 && !this.subsessionDeliveringParents.has(session))
+            this.scheduleSubsessionDelivery(session);
     }
-    isSessionEntryMutationActive(session) {
-        return (this.sessionEntryMutationCounts.get(session) ?? 0) > 0;
+    isSessionEntryMutationActive(session, ignoredReceipts = 0) {
+        return (this.sessionEntryMutationCounts.get(session) ?? 0) > ignoredReceipts;
     }
     publishActivityForEvent(session, event) {
         const eventType = getString(event, "type");
@@ -3750,11 +4036,12 @@ export class PiSessionService {
         const model = session.model === undefined ? undefined : modelToClientModel(session.model);
         const contextUsage = session.getContextUsage();
         const warnings = this.warningsForSession(session);
-        const pendingAsk = this.pendingAskStore.pendingAsk(session.sessionId);
         const pendingDialogs = this.pendingExtensionDialogStore.pendingDialogs(session.sessionId);
+        const suggestedInput = this.suggestedInputs.get(session.sessionId);
         return {
             sessionId: session.sessionId,
             persisted: sessionFileExists(session.sessionFile),
+            recentlyActiveElsewhere: this.activityMarker.isActiveElsewhere(session.sessionFile),
             ...(model === undefined ? {} : { model }),
             thinkingLevel: session.thinkingLevel,
             isStreaming: session.isStreaming,
@@ -3767,8 +4054,8 @@ export class PiSessionService {
             cost: stats.cost,
             ...(contextUsage === undefined ? {} : { contextUsage }),
             ...(warnings.length === 0 ? {} : { warnings }),
-            ...(pendingAsk === undefined ? {} : { pendingAsk }),
             ...(pendingDialogs.length === 0 ? {} : { pendingDialogs }),
+            ...(suggestedInput === undefined ? {} : { suggestedInput }),
         };
     }
     /**
@@ -3780,13 +4067,6 @@ export class PiSessionService {
     warningsForSession(session) {
         const runtime = this.active.get(session.sessionId)?.runtime;
         const warnings = runtime === undefined ? [] : collectRuntimeWarnings(runtime);
-        if (this.activityMarker.isActiveElsewhere(session.sessionFile)) {
-            warnings.push({
-                severity: "info",
-                message: "Recently active in another PI-WEB instance. Avoid working on this session in both instances at once.",
-                source: "PI-WEB",
-            });
-        }
         const anthropic = anthropicSubscriptionWarning(session, join(this.agentDir, "auth.json"));
         if (anthropic !== undefined)
             warnings.push(anthropic);
@@ -3827,13 +4107,13 @@ function bulkRefToSessionRef(ref) {
     return { id: ref.id, cwd: ref.cwd };
 }
 function findArchivedRecordForBulkRef(records, ref) {
-    return records.find((record) => record.cwd === ref.cwd && (record.sessionId === ref.id || record.sessionId.startsWith(ref.id)));
+    return records.find((record) => record.cwd === ref.cwd && record.sessionId === ref.id);
 }
 function findListedSessionForBulkRef(context, ref) {
-    return findSessionByIdOrPrefix(context.sessionsByCwd.get(ref.cwd) ?? [], ref.id);
+    return findSessionByExactId(context.sessionsByCwd.get(ref.cwd) ?? [], ref.id);
 }
-function findSessionByIdOrPrefix(sessions, sessionId) {
-    return sessions.find((session) => session.id === sessionId) ?? sessions.find((session) => session.id.startsWith(sessionId));
+function findSessionByExactId(sessions, sessionId) {
+    return sessions.find((session) => session.id === sessionId);
 }
 function uniqueStrings(values) {
     return [...new Set(values)];
@@ -3874,12 +4154,35 @@ function notificationIdentityForSession(session) {
         cwd: canonicalizeStoredCwd(session.sessionManager.getCwd()),
     };
 }
+function metadataFromActiveSession(session) {
+    return readSessionUiMetadata(session.sessionManager.getEntries?.() ?? session.sessionManager.getBranch());
+}
+function clientSessionFromActiveSession(session) {
+    const header = session.sessionManager.getHeader?.();
+    const created = header?.timestamp ?? new Date().toISOString();
+    const metadata = metadataFromActiveSession(session);
+    return {
+        id: session.sessionId,
+        path: session.sessionFile ?? "",
+        cwd: session.sessionManager.getCwd(),
+        persisted: sessionFileExists(session.sessionFile),
+        created,
+        modified: created,
+        messageCount: session.messages.length,
+        firstMessage: "",
+        ...(metadata === undefined ? {} : { metadata }),
+        ...(session.sessionName === undefined ? {} : { name: session.sessionName }),
+        ...(header?.parentSession === undefined ? {} : { parentSessionPath: header.parentSession }),
+    };
+}
 function clientSessionFromListEntry(session) {
     return {
         id: session.id,
         path: session.path,
         cwd: session.cwd,
         persisted: true,
+        ...(session.agentSubsession === true ? { agentSubsession: true } : {}),
+        ...(session.metadata === undefined ? {} : { metadata: requireSessionUiMetadata(session.metadata) }),
         ...(session.name === undefined ? {} : { name: session.name }),
         created: session.created.toISOString(),
         modified: session.modified.toISOString(),
@@ -3897,6 +4200,7 @@ function archiveInputFromListEntry(session) {
         modified: session.modified.toISOString(),
         messageCount: session.messageCount,
         firstMessage: session.firstMessage,
+        ...(session.metadata === undefined ? {} : { metadata: session.metadata }),
         ...(session.name === undefined ? {} : { name: session.name }),
         ...(session.parentSessionPath === undefined ? {} : { parentSessionPath: session.parentSessionPath }),
     };
@@ -3906,6 +4210,7 @@ function archiveInputFromActiveSession(session) {
     if (sessionFile === undefined || sessionFile === "")
         throw new Error("Session is not persisted");
     const parentSessionPath = session.sessionManager.getHeader?.()?.parentSession;
+    const metadata = metadataFromActiveSession(session);
     return {
         sessionId: session.sessionId,
         cwd: session.sessionManager.getCwd(),
@@ -3914,6 +4219,7 @@ function archiveInputFromActiveSession(session) {
         modified: new Date().toISOString(),
         messageCount: session.messages.length,
         firstMessage: "",
+        ...(metadata === undefined ? {} : { metadata }),
         ...(session.sessionName === undefined ? {} : { name: session.sessionName }),
         ...(parentSessionPath === undefined ? {} : { parentSessionPath }),
     };
@@ -3978,11 +4284,13 @@ function clientSessionFromArchivedRecord(record, fallback) {
     if (path === undefined || created === undefined || modified === undefined || messageCount === undefined || firstMessage === undefined)
         return undefined;
     const name = record.name ?? fallback?.name;
+    const metadata = record.metadata ?? fallback?.metadata;
     const parentSessionPath = record.parentSessionPath ?? fallback?.parentSessionPath;
     return {
         id: record.sessionId,
         path,
         cwd: record.cwd,
+        ...(metadata === undefined ? {} : { metadata: requireSessionUiMetadata(metadata) }),
         ...(name === undefined ? {} : { name }),
         created,
         modified,
@@ -4096,37 +4404,6 @@ function persistedChildSubsessionLinkData(parentSessionId, childSessionId) {
         spawnedSessionId: childSessionId,
     };
 }
-function parsePersistedParentSubsessionLink(entry) {
-    if (!isRecord(entry) || entry["type"] !== "custom" || entry["customType"] !== SUBSESSION_LINK_CUSTOM_TYPE)
-        return undefined;
-    const data = entry["data"];
-    if (!isRecord(data))
-        return undefined;
-    const spawnedBySessionId = getString(data, "spawnedBySessionId");
-    const spawnedSessionId = getString(data, "spawnedSessionId");
-    if (spawnedBySessionId === undefined || spawnedBySessionId === "" || spawnedSessionId === undefined || spawnedSessionId === "")
-        return undefined;
-    const spawnedSessionFile = getString(data, "spawnedSessionFile");
-    const cwd = getString(data, "cwd");
-    return {
-        spawnedBySessionId,
-        spawnedSessionId,
-        ...(spawnedSessionFile === undefined || spawnedSessionFile === "" ? {} : { spawnedSessionFile }),
-        ...(cwd === undefined || cwd === "" ? {} : { cwd }),
-    };
-}
-function parsePersistedChildSubsessionLink(entry) {
-    if (!isRecord(entry) || entry["type"] !== "custom" || entry["customType"] !== SUBSESSION_CHILD_LINK_CUSTOM_TYPE)
-        return undefined;
-    const data = entry["data"];
-    if (!isRecord(data))
-        return undefined;
-    const spawnedBySessionId = getString(data, "spawnedBySessionId");
-    const spawnedSessionId = getString(data, "spawnedSessionId");
-    if (spawnedBySessionId === undefined || spawnedBySessionId === "" || spawnedSessionId === undefined || spawnedSessionId === "")
-        return undefined;
-    return { spawnedBySessionId, spawnedSessionId };
-}
 function nonEmptyString(value) {
     return value === undefined || value === "" ? undefined : value;
 }
@@ -4244,6 +4521,55 @@ function activeEditableTreeTargetParentId(manager, targetId, activeLeafId) {
         return undefined;
     return parentId === null || typeof parentId === "string" ? parentId : undefined;
 }
+/**
+ * Pi edits custom messages from their parent. For a retained checkpoint, remap
+ * that single leaf movement instead, before Pi rebuilds context/restores tools
+ * and emits session_tree. Restore the manager methods before extension handlers
+ * run: their appended history must not be overwritten by a post-event repair.
+ * The caller holds the tree-navigation gate and excludes branch summarization.
+ */
+async function navigateTreeRetainingCustomMessage(manager, targetId, parentId, navigate) {
+    if (parentId !== null && typeof parentId !== "string")
+        throw new Error("This checkpoint has no valid history parent");
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Restore exact identities; calls below explicitly bind the manager.
+    const { branch, resetLeaf } = manager;
+    let pending = true;
+    const restore = () => {
+        if (!pending)
+            return;
+        pending = false;
+        manager.branch = branch;
+        manager.resetLeaf = resetLeaf;
+    };
+    try {
+        manager.branch = (entryId) => {
+            if (entryId === parentId) {
+                restore();
+                branch.call(manager, targetId);
+            }
+            else
+                branch.call(manager, entryId);
+        };
+        manager.resetLeaf = () => {
+            if (parentId === null) {
+                restore();
+                branch.call(manager, targetId);
+            }
+            else
+                resetLeaf.call(manager);
+        };
+        const result = await navigate();
+        if (result.cancelled)
+            return result;
+        // The retained notice is context, not text to restore into the editor.
+        const { editorText, ...retainedResult } = result;
+        void editorText;
+        return retainedResult;
+    }
+    finally {
+        restore();
+    }
+}
 function setSessionTreeLeaf(manager, leafId) {
     if (leafId === null)
         manager.resetLeaf();
@@ -4257,15 +4583,22 @@ function transcriptBranchIncludesEntry(entries, entryId) {
 const SUBSESSION_LINK_CUSTOM_TYPE = "pi-web.subsession.link";
 /** custom entry type used to mark a child as created by spawn_subsession. */
 const SUBSESSION_CHILD_LINK_CUSTOM_TYPE = "pi-web.subsession.spawned";
-/** customType marking a parent-facing subsession-completion notice. */
-const SUBSESSION_NOTIFICATION_CUSTOM_TYPE = "subsession.completion";
-const SUBSESSION_NOTIFICATION_MAX_OUTPUT_CHARS = 2000;
-/** Avoid duplicating a partial result in context when deliberate inspection can return the full output. */
-function formatSubsessionNotificationOutput(childSessionId, text) {
-    if (text.length > SUBSESSION_NOTIFICATION_MAX_OUTPUT_CHARS) {
-        return `Output from subsession ${childSessionId} was too long for this completion notice and was omitted. Call check_subsession with sessionId "${childSessionId}" to retrieve the final output.`;
-    }
-    return `--- SUBSESSION OUTPUT: ${childSessionId} ---\n${text === "" ? "(no output)" : text}`;
+/** A filtered read is a receipt only when it contains the complete latest final text. */
+function transcriptReturnsFinalOutput(messages, view, finalText) {
+    if (finalText === "")
+        return false;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const text = finalAssistantText([messages[index]]);
+        if (text === "")
+            continue;
+        const entry = view.entries.find((candidate) => candidate.index === index && candidate.role === "assistant");
+        if (entry === undefined || text !== finalText)
+            return false;
+        const texts = entry.parts.filter((part) => part.kind === "text");
+        return texts.every((part) => part.truncated === undefined)
+            && texts.map((part) => part.text).join("\n").trim() === finalText.trim();
+    }
+    return false;
 }
 /** Most recent assistant text from a history message list, or "" if none. */
 function finalAssistantText(messages) {
@@ -4290,6 +4623,11 @@ function finalAssistantText(messages) {
 }
 function toClientEvent(event, thinkingLevel) {
     const eventType = getString(event, "type");
+    // Nested execution belongs to the parent tool result, not a durable message.
+    // Do not create standalone transcript rows that disappear on reconnect.
+    if (getString(event, "parentToolCallId") !== undefined && eventType?.startsWith("tool_execution_") === true) {
+        return { type: "pi.event", eventType };
+    }
     const assistantMessageEvent = getProperty(event, "assistantMessageEvent");
     if (eventType === "message_update" && getString(assistantMessageEvent, "type") === "text_delta") {
         return { type: "assistant.delta", text: getString(assistantMessageEvent, "delta") ?? "" };