@jmfederico/pi-web 1.202606.6 → 1.202607.0

package/dist/server/sessions/piSessionService.js

@@ -1,19 +1,21 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { open, readFile, writeFile } from "node:fs/promises";
 import { AuthStorage, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, defineTool, getAgentDir, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
 import { BUILTIN_COMMANDS } from "./builtinCommands.js";
 import { SessionCommandService } from "./sessionCommandService.js";
 import { SessionArchiveStore } from "./sessionArchiveStore.js";
 import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree } from "./sessionArchiveTree.js";
-import { fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
+import { deterministicSessionName, fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
 import { computeEditPreview } from "./editPreview.js";
 import { createPiSessionManagerGateway } from "./piSessionManagerGateway.js";
 import { attachmentsToInlineImages, saveAttachmentsToWorkspace } from "./attachmentService.js";
 import { parsePromptAttachments } from "../../shared/promptAttachments.js";
-import { cwdPathsEqual } from "../workingDirectory.js";
+import { canonicalizeStoredCwd, cwdPathsEqual } from "../workingDirectory.js";
 import { createSpawnSessionToolDefinition } from "./spawnSessionTool.js";
 import { createSubsessionToolDefinitions } from "./spawnSubsessionTool.js";
 import { buildTranscriptView } from "./subsessionTranscript.js";
+import { planSessionCleanup, summarizeSessionCleanupExecution } from "./sessionCleanup.js";
 const noopLogger = { info() { } };
 function noop() {
     // Intentionally empty default unsubscribe callback.
@@ -50,20 +52,50 @@ function parsePromptStreamingBehavior(value) {
 function defaultCreateAgentRuntime(createRuntime, options) {
     if (!(options.sessionManager instanceof SessionManager))
         throw new Error("Default runtime creation requires an SDK SessionManager");
-    return createAgentSessionRuntime(createRuntime, { ...options, sessionManager: options.sessionManager });
+    const runtimeFactory = createRuntimeWithOneShotSessionOptions(createRuntime, options.initialModel, options.delegationToolsEnabled);
+    return createAgentSessionRuntime(runtimeFactory, {
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        sessionManager: options.sessionManager,
+    });
+}
+function createRuntimeWithOneShotSessionOptions(createRuntime, initialModel, delegationToolsEnabled) {
+    // These inputs belong only to the session being opened. A later runtime
+    // replacement resolves its own model and delegation capability.
+    let pendingInitialModel = initialModel;
+    let pendingDelegationToolsEnabled = delegationToolsEnabled;
+    return async (options) => {
+        const model = pendingInitialModel;
+        const toolsEnabled = pendingDelegationToolsEnabled;
+        pendingInitialModel = undefined;
+        pendingDelegationToolsEnabled = undefined;
+        return createRuntime({
+            ...options,
+            ...(model === undefined ? {} : { initialModel: model }),
+            ...(toolsEnabled === undefined ? {} : { delegationToolsEnabled: toolsEnabled }),
+        });
+    };
 }
-function createDefaultRuntimeFactory(authStorage, modelRegistry, spawn, subsessions) {
-    return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
+export function createPiWebCustomToolDefinitions(cwd, delegationEnabled, spawn, subsessions) {
+    return [
+        createPiWebEditToolDefinition(cwd),
+        ...(delegationEnabled && spawn !== undefined ? [createSpawnSessionToolDefinition(cwd, { spawn })] : []),
+        ...(delegationEnabled && subsessions !== undefined ? createSubsessionToolDefinitions(cwd, subsessions) : []),
+    ];
+}
+function createDefaultRuntimeFactory(authStorage, modelRegistry, sessionManagers, spawn, subsessions) {
+    return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel, delegationToolsEnabled }) => {
         const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
-        const customTools = [
-            createPiWebEditToolDefinition(cwd),
-            ...(spawn === undefined ? [] : [createSpawnSessionToolDefinition(cwd, { spawn })]),
-            ...(subsessions === undefined ? [] : createSubsessionToolDefinitions(cwd, subsessions)),
-        ];
-        const options = sessionStartEvent === undefined
-            ? { services, sessionManager, customTools }
-            : { services, sessionManager, sessionStartEvent, customTools };
-        const result = await createAgentSessionFromServices(options);
+        const resolvedDelegationToolsEnabled = delegationToolsEnabled
+            ?? await sessionAllowsDelegationTools(sessionManager, sessionManagers);
+        const customTools = createPiWebCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions);
+        const result = await createAgentSessionFromServices({
+            services,
+            sessionManager,
+            customTools,
+            ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
+            ...(initialModel === undefined ? {} : { model: initialModel }),
+        });
         return { ...result, services, diagnostics: services.diagnostics };
     };
 }
@@ -92,6 +124,7 @@ export class PiSessionService {
     constructor(events, deps = {}) {
         this.events = events;
         this.active = new Map();
+        this.pendingSessionOpens = new Map();
         this.activities = new Map();
         this.compactionPromptQueues = new Map();
         this.compactionDrainTimers = new Map();
@@ -100,6 +133,10 @@ export class PiSessionService {
         this.subsessionParents = new Map();
         /** Parent session id -> the set of tracked subsession ids it spawned. */
         this.subsessionChildren = new Map();
+        /** Tracked subsession id -> persisted recovery details for the child. */
+        this.subsessionLinks = new Map();
+        /** Parent id/file identities whose persisted links have already been loaded. */
+        this.subsessionHydratedParents = new Set();
         /**
          * Tracked subsession id -> whether a completion notification is armed.
          * Armed when the child starts working; firing on completion disarms it so a
@@ -112,14 +149,15 @@ export class PiSessionService {
         this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
         this.spawnTargets = deps.spawnTargets;
         this.logger = deps.logger ?? noopLogger;
+        this.now = deps.now ?? (() => new Date());
         // Subsessions are a beta capability gated behind their own flag, and they
         // also require the spawn capability (they share its project-scope resolver).
         const subsessionsActive = this.spawnTargets !== undefined && deps.subsessionsEnabled === true;
-        this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
+        this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry, this.sessionManager, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
             spawn: (input) => this.spawnSubsession(input),
-            list: (parentSessionId) => this.listSubsessions(parentSessionId),
-            check: (parentSessionId, sessionId) => this.checkSubsession(parentSessionId, sessionId),
-            read: (parentSessionId, sessionId, query) => this.readSubsession(parentSessionId, sessionId, query),
+            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),
         });
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
@@ -133,27 +171,79 @@ export class PiSessionService {
                 this.publishActivity(session, result === "success" ? "compaction complete" : "compaction failed", result === "success" ? "idle" : "error", detail);
                 this.publishStatus(session);
             },
+            reloadSession: (session) => this.reloadSessionRuntime(session),
         }, { listSessionNames: (cwd) => this.listSessionNames(cwd) });
     }
     activeCount() {
         return this.active.size;
     }
+    async cleanupPreview(request) {
+        return previewResponseFromPlan(await this.cleanupPlan(request));
+    }
+    async cleanup(request) {
+        const plan = await this.cleanupPlan(request);
+        if (plan.deleteRecords.length > 0 && this.archiveStore.deleteArchived === undefined && this.archiveStore.deleteArchivedMany === undefined)
+            throw new Error("Archive store does not support deletion");
+        const archiveInputs = [];
+        const readyArchiveInputs = [];
+        const deleteRecords = [];
+        const readyDeleteRecords = [];
+        const skippedBusySessionIds = new Set(plan.skippedBusySessionIds);
+        for (const input of plan.archiveInputs) {
+            if (this.activeSessionHasWork(input.sessionId)) {
+                skippedBusySessionIds.add(input.sessionId);
+                continue;
+            }
+            await this.closeActive(input.sessionId);
+            readyArchiveInputs.push(input);
+        }
+        await this.archiveStoreArchiveMany(readyArchiveInputs);
+        archiveInputs.push(...readyArchiveInputs);
+        for (const record of plan.deleteRecords) {
+            if (this.activeSessionHasWork(record.sessionId)) {
+                skippedBusySessionIds.add(record.sessionId);
+                continue;
+            }
+            await this.closeActive(record.sessionId);
+            readyDeleteRecords.push(record);
+        }
+        await this.ensureArchivedRecordsMoved(readyDeleteRecords);
+        const deletedSessionIds = new Set(await this.archiveStoreDeleteArchivedMany(readyDeleteRecords.map((record) => record.sessionId)));
+        deleteRecords.push(...readyDeleteRecords.filter((record) => deletedSessionIds.has(record.sessionId)));
+        return summarizeSessionCleanupExecution({
+            archiveInputs,
+            deleteRecords,
+            thresholds: plan.thresholds,
+            generatedAt: plan.generatedAt,
+            skippedBusySessionIds: [...skippedBusySessionIds],
+        });
+    }
     async dispose() {
         clearInterval(this.heartbeat);
         this.clearCompactionDrainTimers();
+        const pendingOpens = this.pendingSessionOpenPromises();
+        if (pendingOpens.length > 0)
+            await Promise.allSettled(pendingOpens);
         const activeSessions = Array.from(new Set(this.active.values()));
         this.active.clear();
+        this.pendingSessionOpens.clear();
         this.activities.clear();
         this.compactionPromptQueues.clear();
         this.authLossWarnings.clear();
         this.subsessionParents.clear();
         this.subsessionChildren.clear();
+        this.subsessionLinks.clear();
+        this.subsessionHydratedParents.clear();
         this.subsessionNotifyArmed.clear();
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
             this.workspaceActivity?.removeSession(active.runtime.session.sessionId, active.runtime.session.sessionManager.getCwd());
-            await active.runtime.session.abort();
-            await active.runtime.dispose();
+            try {
+                await active.runtime.session.abort();
+            }
+            finally {
+                await active.runtime.dispose();
+            }
         }));
     }
     async list(cwd) {
@@ -171,20 +261,27 @@ export class PiSessionService {
             .filter(isDefined);
         return [...unarchivedSessions, ...archivedSessions];
     }
-    async start(cwd, parentSession) {
-        const active = await this.create(this.sessionManager.create(cwd, parentSession === undefined ? undefined : { parentSession }), cwd);
+    async start(cwd, options = {}) {
+        return this.startSession(cwd, options);
+    }
+    async startSession(cwd, options) {
+        const active = await this.create(this.sessionManager.create(cwd, options.parentSession === undefined ? undefined : { parentSession: options.parentSession }), cwd, {
+            ...(options.initialModel === undefined ? {} : { initialModel: options.initialModel }),
+            ...(options.creationProvenance === undefined ? {} : { creationProvenance: options.creationProvenance }),
+        });
         const { session } = active.runtime;
         const created = {
             id: session.sessionId,
             path: session.sessionFile ?? "",
             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 }),
+            ...(options.parentSession === undefined ? {} : { parentSessionPath: options.parentSession }),
         };
         // Broadcast so other clients (and the spawning agent's UI) can add the new
         // session to their list without a manual reload.
@@ -202,7 +299,7 @@ export class PiSessionService {
         const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
         if (!decision.allowed)
             throw spawnTargetError(decision);
-        const created = await this.start(decision.cwd);
+        const created = await this.start(decision.cwd, input.model === undefined ? {} : { initialModel: input.model });
         await this.prompt(created.id, input.prompt);
         this.logger.info({ spawningCwd: input.spawningCwd, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length }, "spawn_session started a new session");
         return { sessionId: created.id, cwd: decision.cwd };
@@ -219,69 +316,247 @@ export class PiSessionService {
         const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
         if (!decision.allowed)
             throw spawnTargetError(decision);
-        const created = await this.start(decision.cwd, input.parentSessionFile);
-        this.registerSubsession(input.parentSessionId, created.id);
+        const created = await this.startSession(decision.cwd, {
+            ...(input.parentSessionFile === undefined ? {} : { parentSession: input.parentSessionFile }),
+            ...(input.model === undefined ? {} : { initialModel: input.model }),
+            creationProvenance: "tracked-subsession",
+        });
+        const parentSessionFile = nonEmptyString(input.parentSessionFile);
+        const link = {
+            parentSessionId: input.parentSessionId,
+            childSessionId: created.id,
+            ...(created.path === "" ? {} : { childSessionFile: created.path }),
+            ...(parentSessionFile === undefined ? {} : { parentSessionFile }),
+            cwd: decision.cwd,
+        };
+        this.registerVerifiedSubsession(link);
+        this.persistSubsessionLink(link);
+        this.persistSubsessionChildMarker(input.parentSessionId, created.id);
         await this.prompt(created.id, 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 { sessionId: created.id, cwd: decision.cwd };
     }
     /** Summaries of the tracked subsessions spawned by `parentSessionId`. */
-    async listSubsessions(parentSessionId) {
+    async listSubsessions(parentSessionId, parentSessionFile) {
+        const parentFile = nonEmptyString(parentSessionFile);
+        await this.hydrateSubsessionsForParent(parentSessionId, parentFile);
         const childIds = this.subsessionChildren.get(parentSessionId);
         if (childIds === undefined)
             return [];
-        return Promise.all([...childIds].map(async (childId) => ({ sessionId: childId, ...(await this.subsessionSummaryFields(childId)) })));
+        const authorizedChildIds = [...childIds].filter((childId) => this.subsessionLinkBelongsToParent(parentSessionId, parentFile, childId));
+        return Promise.all(authorizedChildIds.map(async (childId) => ({ sessionId: childId, ...(await this.subsessionSummaryFields(childId)) })));
     }
     /** Status and final result of a subsession, scoped to the caller's children. */
-    async checkSubsession(parentSessionId, sessionId) {
-        const session = await this.openSubsession(parentSessionId, sessionId);
+    async checkSubsession(parentSessionId, sessionId, parentSessionFile) {
+        const session = await this.openSubsession(parentSessionId, sessionId, parentSessionFile);
         const messages = historyMessages(session);
         return {
             sessionId,
             cwd: session.sessionManager.getCwd(),
-            status: await this.subsessionStatus(session),
+            status: this.subsessionStatus(session),
             finalText: finalAssistantText(messages),
             messageCount: messages.length,
         };
     }
     /** Filtered, paginated transcript of a subsession, scoped to the caller's children. */
-    async readSubsession(parentSessionId, sessionId, query) {
-        const session = await this.openSubsession(parentSessionId, sessionId);
+    async readSubsession(parentSessionId, sessionId, query, parentSessionFile) {
+        const session = await this.openSubsession(parentSessionId, sessionId, parentSessionFile);
         const view = buildTranscriptView(historyMessages(session), query);
         return {
             sessionId,
             cwd: session.sessionManager.getCwd(),
-            status: await this.subsessionStatus(session),
+            status: this.subsessionStatus(session),
             ...view,
         };
     }
     /** Open a session after verifying it is one of the caller's tracked children. */
-    async openSubsession(parentSessionId, sessionId) {
-        if (this.subsessionParents.get(sessionId) !== parentSessionId) {
+    async openSubsession(parentSessionId, sessionId, parentSessionFile) {
+        const parentFile = nonEmptyString(parentSessionFile);
+        await this.hydrateSubsessionsForParent(parentSessionId, parentFile);
+        if (this.subsessionParents.get(sessionId) !== parentSessionId || !this.subsessionLinkBelongsToParent(parentSessionId, parentFile, sessionId)) {
             throw new Error(`Session ${sessionId} is not one of your subsessions`);
         }
-        return this.getOrOpen(sessionId);
+        return this.getOrOpenTrackedSubsession(sessionId);
+    }
+    subsessionLinkBelongsToParent(parentSessionId, parentSessionFile, childSessionId) {
+        const link = this.subsessionLinks.get(childSessionId);
+        if (link?.parentSessionId !== parentSessionId)
+            return false;
+        return parentSessionFile === undefined || trackedLinkParentFileMatches(link, parentSessionFile);
+    }
+    activeChildForSubsessionLink(link) {
+        const active = this.active.get(link.childSessionId);
+        if (active === undefined)
+            return undefined;
+        return activeSessionFileMatches(active, link.childSessionFile) ? active : undefined;
+    }
+    activeParentForSubsessionLink(link) {
+        const active = this.active.get(link.parentSessionId);
+        if (active === undefined)
+            return undefined;
+        return activeSessionFileMatches(active, link.parentSessionFile) ? active : undefined;
     }
-    registerSubsession(parentSessionId, childSessionId) {
+    subsessionLinkForActiveChild(session) {
+        const childId = session.sessionId;
+        const parentId = this.subsessionParents.get(childId);
+        const link = this.subsessionLinks.get(childId);
+        if (parentId === undefined || link?.parentSessionId !== parentId)
+            return undefined;
+        return sessionFileMatches(session, link.childSessionFile) ? link : undefined;
+    }
+    registerVerifiedSubsession(link) {
+        const { childSessionId, parentSessionId } = link;
+        const previousParentId = this.subsessionParents.get(childSessionId);
+        if (previousParentId !== undefined && previousParentId !== parentSessionId) {
+            const previousChildren = this.subsessionChildren.get(previousParentId);
+            previousChildren?.delete(childSessionId);
+            if (previousChildren?.size === 0)
+                this.subsessionChildren.delete(previousParentId);
+        }
         this.subsessionParents.set(childSessionId, parentSessionId);
         const children = this.subsessionChildren.get(parentSessionId) ?? new Set();
         children.add(childSessionId);
         this.subsessionChildren.set(parentSessionId, children);
-        this.subsessionNotifyArmed.set(childSessionId, false);
+        this.subsessionLinks.set(childSessionId, link);
+        if (!this.subsessionNotifyArmed.has(childSessionId))
+            this.subsessionNotifyArmed.set(childSessionId, false);
+    }
+    unregisterSubsession(childSessionId) {
+        const parentSessionId = this.subsessionParents.get(childSessionId);
+        this.subsessionParents.delete(childSessionId);
+        this.subsessionLinks.delete(childSessionId);
+        this.subsessionNotifyArmed.delete(childSessionId);
+        if (parentSessionId === undefined)
+            return;
+        const children = this.subsessionChildren.get(parentSessionId);
+        children?.delete(childSessionId);
+        if (children?.size === 0)
+            this.subsessionChildren.delete(parentSessionId);
+    }
+    persistSubsessionLink(link) {
+        const parent = this.activeParentForSubsessionLink(link)?.runtime.session;
+        if (parent === undefined)
+            return;
+        if (parent.sessionManager.appendCustomEntry === undefined)
+            return;
+        try {
+            parent.sessionManager.appendCustomEntry(SUBSESSION_LINK_CUSTOM_TYPE, persistedParentSubsessionLinkData(link));
+        }
+        catch (error) {
+            this.logger.info({ parentSessionId: link.parentSessionId, sessionId: link.childSessionId, error: error instanceof Error ? error.message : String(error) }, "failed to persist subsession link");
+        }
+    }
+    persistSubsessionChildMarker(parentSessionId, childSessionId) {
+        const child = this.active.get(childSessionId)?.runtime.session;
+        if (child === undefined)
+            return;
+        if (child.sessionManager.appendCustomEntry === undefined)
+            return;
+        try {
+            child.sessionManager.appendCustomEntry(SUBSESSION_CHILD_LINK_CUSTOM_TYPE, persistedChildSubsessionLinkData(parentSessionId, childSessionId));
+        }
+        catch (error) {
+            this.logger.info({ parentSessionId, sessionId: childSessionId, error: error instanceof Error ? error.message : String(error) }, "failed to persist subsession child marker");
+        }
+    }
+    async hydrateSubsessionsForParent(parentSessionId, parentSessionFile) {
+        const hydrationKey = subsessionHydratedParentKey(parentSessionId, parentSessionFile);
+        if (this.subsessionHydratedParents.has(hydrationKey))
+            return;
+        const activeParent = this.active.get(parentSessionId);
+        if (activeParent !== undefined && (parentSessionFile === undefined || activeSessionFileMatches(activeParent, parentSessionFile))) {
+            const activeParentFile = nonEmptyString(activeParent.runtime.session.sessionFile);
+            await this.registerPersistedSubsessionLinks(parentSessionId, activeParent.runtime.session.sessionManager, activeParentFile);
+            this.subsessionHydratedParents.add(hydrationKey);
+            return;
+        }
+        if (parentSessionFile === undefined)
+            return;
+        if ((await readSessionHeaderSummary(parentSessionFile))?.id !== parentSessionId) {
+            this.subsessionHydratedParents.add(hydrationKey);
+            return;
+        }
+        let parentManager;
+        try {
+            parentManager = this.sessionManager.open(parentSessionFile);
+        }
+        catch {
+            this.subsessionHydratedParents.add(hydrationKey);
+            return;
+        }
+        await this.registerPersistedSubsessionLinks(parentSessionId, parentManager, parentSessionFile);
+        this.subsessionHydratedParents.add(hydrationKey);
+    }
+    async registerPersistedSubsessionLinks(parentSessionId, parentManager, parentSessionFile) {
+        // Parent custom links are the authoritative recovery record: verify the
+        // exact live child file/header before tracking.
+        const entries = parentManager.getEntries?.() ?? parentManager.getBranch();
+        for (const entry of entries) {
+            const link = parsePersistedParentSubsessionLink(entry);
+            if (link === undefined)
+                continue;
+            const verified = await this.verifiedSubsessionLinkFromParentLink(parentSessionId, parentSessionFile, link);
+            if (verified === undefined)
+                continue;
+            this.registerVerifiedSubsession(verified);
+        }
+    }
+    async verifiedSubsessionLinkFromParentLink(parentSessionId, parentSessionFile, link) {
+        if (parentSessionFile === undefined)
+            return undefined;
+        if (link.spawnedBySessionId !== parentSessionId)
+            return undefined;
+        if (!(await this.parentLinkHasValidChildTarget(parentSessionFile, link)))
+            return undefined;
+        return trackedSubsessionLinkFromParentLink(parentSessionId, link, parentSessionFile);
+    }
+    async parentLinkHasValidChildTarget(parentSessionFile, link) {
+        return link.spawnedSessionFile !== undefined
+            && await sessionFileHeaderMatches(link.spawnedSessionFile, { sessionId: link.spawnedSessionId, parentSessionFile });
+    }
+    async recoverSubsessionTrackingForOpenedSession(session) {
+        const link = await this.verifiedSubsessionLinkFromOpenedChild(session);
+        if (link === undefined)
+            return;
+        this.registerVerifiedSubsession(link);
+    }
+    verifiedSubsessionLinkFromOpenedChild(session) {
+        return verifiedTrackedSubsessionLink(this.sessionManager, {
+            sessionId: session.sessionId,
+            sessionFile: session.sessionFile,
+            sessionManager: session.sessionManager,
+            cwd: session.sessionManager.getCwd(),
+        });
+    }
+    async getOrOpenTrackedSubsession(sessionId) {
+        const link = this.subsessionLinks.get(sessionId);
+        if (link === undefined)
+            throw new Error("Session not found");
+        const active = this.activeChildForSubsessionLink(link);
+        if (active !== undefined)
+            return active.runtime.session;
+        if (link.childSessionFile !== undefined) {
+            if (!(await sessionFileHeaderMatches(link.childSessionFile, { sessionId, parentSessionFile: link.parentSessionFile })))
+                throw new Error("Session not found");
+            const sessionManager = this.sessionManager.open(link.childSessionFile);
+            return (await this.create(sessionManager, link.cwd ?? sessionManager.getCwd())).runtime.session;
+        }
+        throw new Error("Session not found");
     }
     async subsessionSummaryFields(childSessionId) {
-        const active = this.active.get(childSessionId);
+        const link = this.subsessionLinks.get(childSessionId);
+        const active = link === undefined ? undefined : this.activeChildForSubsessionLink(link);
         if (active !== undefined) {
-            return { cwd: active.runtime.cwd, status: await this.subsessionStatus(active.runtime.session) };
+            return { cwd: active.runtime.cwd, status: this.subsessionStatus(active.runtime.session) };
         }
-        const archived = await this.archiveStore.get(childSessionId);
-        if (archived !== undefined)
-            return { cwd: archived.cwd, status: "archived" };
+        if (link?.childSessionFile !== undefined && (await sessionFileHeaderMatches(link.childSessionFile, { sessionId: childSessionId, parentSessionFile: link.parentSessionFile }))) {
+            return { cwd: link.cwd ?? "", status: "idle" };
+        }
+        if (link?.cwd !== undefined)
+            return { cwd: link.cwd, status: "unknown" };
         return { cwd: "", status: "unknown" };
     }
-    async subsessionStatus(session) {
-        if (await this.archiveStore.isArchived(session.sessionId))
-            return "archived";
+    subsessionStatus(session) {
         if (this.hasActiveWork(session))
             return "working";
         if (this.activities.get(session.sessionId)?.phase === "error")
@@ -295,10 +570,10 @@ export class PiSessionService {
      * parent is busy and delivers immediately when it is idle).
      */
     updateSubsessionTracking(session) {
-        const childId = session.sessionId;
-        const parentId = this.subsessionParents.get(childId);
-        if (parentId === undefined)
+        const link = this.subsessionLinkForActiveChild(session);
+        if (link === undefined)
             return;
+        const childId = link.childSessionId;
         if (this.hasActiveWork(session)) {
             this.subsessionNotifyArmed.set(childId, true);
             return;
@@ -309,8 +584,24 @@ export class PiSessionService {
         const status = this.activities.get(childId)?.phase === "error" ? "error" : "idle";
         const finalText = finalAssistantText(historyMessages(session));
         const preview = finalText === "" ? "(no output)" : truncateForNotification(finalText);
-        const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nUse check_subsession with sessionId "${childId}" for its status and latest output, or read_subsession to look through its full transcript.`;
-        void this.notifyParentOfSubsession(parentId, childId, text);
+        const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nStatus and latest output are available through check_subsession with sessionId "${childId}"; its full transcript is available through read_subsession.`;
+        void this.notifyParentOfSubsession(link.parentSessionId, childId, text);
+    }
+    async getOrOpenParentForSubsession(parentSessionId, childSessionId) {
+        const link = this.subsessionLinks.get(childSessionId);
+        if (link?.parentSessionId !== parentSessionId)
+            throw new Error(`Parent session ${parentSessionId} is not available for subsession notification`);
+        const active = this.activeParentForSubsessionLink(link);
+        if (active !== undefined)
+            return active.runtime.session;
+        const parentSessionFile = link.parentSessionFile;
+        if (parentSessionFile === undefined)
+            throw new Error(`Parent session ${parentSessionId} is not available for subsession notification`);
+        if ((await readSessionHeaderSummary(parentSessionFile))?.id !== parentSessionId) {
+            throw new Error(`Parent session ${parentSessionId} is not available for subsession notification`);
+        }
+        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
@@ -321,7 +612,7 @@ export class PiSessionService {
      */
     async notifyParentOfSubsession(parentId, childId, text) {
         try {
-            const session = await this.getOrOpen(parentId);
+            const session = await this.getOrOpenParentForSubsession(parentId, childId);
             await session.sendCustomMessage({ customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, content: text, display: true, details: { sessionId: childId } }, { triggerTurn: true, deliverAs: "followUp" });
             this.publishStatus(session);
         }
@@ -459,7 +750,7 @@ export class PiSessionService {
         this.publishStatus(session);
     }
     async saveAttachments(ref, attachments, folder) {
-        const parsed = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
+        const parsed = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false, allowFileAttachments: true });
         if (parsed.length === 0)
             return [];
         await this.assertWritable(ref);
@@ -511,6 +802,23 @@ export class PiSessionService {
         const active = await this.getActive(ref);
         return this.commandService.respond(active.runtime.session.sessionId, requestId, value);
     }
+    async reloadSessionRuntime(session) {
+        if (this.hasActiveWork(session))
+            throw new Error("Stop current session activity before reloading");
+        this.publishActivity(session, "reloading resources", "active");
+        try {
+            await session.reload();
+            this.publishActivity(session, "resources reloaded", "idle");
+            this.publishStatus(session);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.publishActivity(session, "reload failed", "error", message);
+            this.events.publish(session.sessionId, { type: "session.error", message });
+            this.publishStatus(session);
+            throw error;
+        }
+    }
     async archive(ref) {
         const session = await this.getOrOpen(ref);
         if (this.hasActiveWork(session))
@@ -519,6 +827,69 @@ export class PiSessionService {
         await this.closeActive(session.sessionId);
         await this.archiveStore.archive(archiveInput);
     }
+    async archiveMany(refs) {
+        const uniqueRefs = uniqueBulkSessionRefs(refs);
+        const [archivedRecords, sessionContext] = await Promise.all([
+            this.archiveStore.list(),
+            this.bulkSessionLookupContext(uniqueRefs),
+        ]);
+        const failures = [];
+        const alreadyArchivedSessionIds = [];
+        const planItems = [];
+        for (const ref of uniqueRefs) {
+            const archived = findArchivedRecordForBulkRef(archivedRecords, ref);
+            if (archived !== undefined) {
+                alreadyArchivedSessionIds.push(archived.sessionId);
+                continue;
+            }
+            const active = this.activeForLookup(bulkRefToLookup(ref));
+            const listed = findListedSessionForBulkRef(sessionContext, ref);
+            const resolvedSessionId = active?.runtime.session.sessionId ?? listed?.id ?? ref.id;
+            if (active !== undefined && this.hasActiveWork(active.runtime.session)) {
+                failures.push({ sessionId: resolvedSessionId, error: "Stop current session activity before archiving" });
+                continue;
+            }
+            try {
+                if (listed !== undefined) {
+                    planItems.push({ input: archiveInputFromListEntry(listed) });
+                }
+                else if (active !== undefined) {
+                    planItems.push({ input: archiveInputFromActiveSession(active.runtime.session) });
+                }
+                else {
+                    failures.push({ sessionId: ref.id, error: "Session not found" });
+                }
+            }
+            catch (error) {
+                failures.push({ sessionId: resolvedSessionId, error: errorMessage(error) });
+            }
+        }
+        const readyInputs = [];
+        for (const item of planItems) {
+            try {
+                await this.closeActive(item.input.sessionId);
+                readyInputs.push(item.input);
+            }
+            catch (error) {
+                failures.push({ sessionId: item.input.sessionId, error: errorMessage(error) });
+            }
+        }
+        const archivedSessionIds = [...alreadyArchivedSessionIds];
+        try {
+            const archived = await this.archiveStoreArchiveMany(readyInputs);
+            archivedSessionIds.push(...archived.map((record) => record.sessionId));
+        }
+        catch (error) {
+            for (const input of readyInputs)
+                failures.push({ sessionId: input.sessionId, error: errorMessage(error) });
+        }
+        return {
+            archived: true,
+            archivedSessionIds: uniqueStrings(archivedSessionIds),
+            failures,
+            generatedAt: new Date().toISOString(),
+        };
+    }
     async archiveTree(ref) {
         const session = await this.getOrOpen(ref);
         const catalog = await this.workspaceArchiveCandidates(session.sessionManager.getCwd());
@@ -530,8 +901,7 @@ export class PiSessionService {
         const archiveInputs = plan.unarchivedTargets.map((target) => archiveInputFromCandidate(target));
         for (const input of archiveInputs)
             await this.closeActive(input.sessionId);
-        for (const input of archiveInputs)
-            await this.archiveStore.archive(input);
+        await this.archiveStoreArchiveMany(archiveInputs);
         return {
             archived: true,
             sessionIds: archiveInputs.map((input) => input.sessionId),
@@ -557,6 +927,57 @@ export class PiSessionService {
             await this.ensureArchivedRecordMoved(record);
         await this.archiveStore.deleteArchived(record.sessionId);
     }
+    async deleteArchivedMany(refs) {
+        if (this.archiveStore.deleteArchived === undefined && this.archiveStore.deleteArchivedMany === undefined)
+            throw new Error("Archive store does not support deletion");
+        const uniqueRefs = uniqueBulkSessionRefs(refs);
+        const archivedRecords = await this.archiveStore.list();
+        const failures = [];
+        const planItems = [];
+        for (const ref of uniqueRefs) {
+            const record = findArchivedRecordForBulkRef(archivedRecords, ref);
+            if (record === undefined) {
+                failures.push({ sessionId: ref.id, error: "Archived session not found" });
+                continue;
+            }
+            const active = this.activeForLookup({ id: record.sessionId, cwd: record.cwd });
+            if (active !== undefined && this.hasActiveWork(active.runtime.session)) {
+                failures.push({ sessionId: record.sessionId, error: "Stop current session activity before deleting archived session" });
+                continue;
+            }
+            planItems.push({ record });
+        }
+        const readyRecords = [];
+        for (const item of planItems) {
+            try {
+                await this.closeActive(item.record.sessionId);
+                readyRecords.push(item.record);
+            }
+            catch (error) {
+                failures.push({ sessionId: item.record.sessionId, error: errorMessage(error) });
+            }
+        }
+        const moveFailures = await this.moveLegacyArchivedRecordsForDelete(readyRecords);
+        failures.push(...moveFailures);
+        const moveFailureIds = new Set(moveFailures.map((failure) => failure.sessionId));
+        const deleteIds = readyRecords
+            .map((record) => record.sessionId)
+            .filter((sessionId) => !moveFailureIds.has(sessionId));
+        let deletedSessionIds = [];
+        try {
+            deletedSessionIds = await this.archiveStoreDeleteArchivedMany(deleteIds);
+        }
+        catch (error) {
+            for (const sessionId of deleteIds)
+                failures.push({ sessionId, error: errorMessage(error) });
+        }
+        return {
+            deleted: true,
+            deletedSessionIds,
+            failures,
+            generatedAt: new Date().toISOString(),
+        };
+    }
     async reload(ref) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
@@ -572,6 +993,8 @@ export class PiSessionService {
         if (sessionFile === undefined || sessionFile === "")
             throw new Error("Session is not persisted");
         await clearParentSession(sessionFile);
+        clearParentSessionHeader(session.sessionManager);
+        this.unregisterSubsession(session.sessionId);
     }
     async abort(ref) {
         const active = this.activeForLookup(ref);
@@ -592,6 +1015,96 @@ export class PiSessionService {
             // Best-effort shutdown; callers that need errors await closeActive directly.
         });
     }
+    async bulkSessionLookupContext(refs) {
+        const cwdSet = new Set();
+        let needsAllSessions = false;
+        for (const ref of refs) {
+            if (ref.cwd === undefined)
+                needsAllSessions = true;
+            else
+                cwdSet.add(ref.cwd);
+        }
+        const [sessionsByCwd, allSessions] = await Promise.all([
+            this.listSessionsByCwd([...cwdSet]),
+            needsAllSessions ? this.sessionManager.listAll?.() ?? Promise.resolve([]) : Promise.resolve(undefined),
+        ]);
+        return allSessions === undefined ? { sessionsByCwd } : { sessionsByCwd, allSessions };
+    }
+    async listSessionsByCwd(cwds) {
+        const uniqueCwds = uniqueStrings(cwds);
+        const entries = await Promise.all(uniqueCwds.map(async (cwd) => [cwd, await this.sessionManager.list(cwd)]));
+        return new Map(entries);
+    }
+    async archiveStoreArchiveMany(inputs) {
+        if (inputs.length === 0)
+            return [];
+        if (this.archiveStore.archiveMany !== undefined)
+            return this.archiveStore.archiveMany(inputs);
+        const records = [];
+        for (const input of inputs)
+            records.push(await this.archiveStore.archive(input));
+        return records;
+    }
+    async archiveStoreDeleteArchivedMany(sessionIds) {
+        if (sessionIds.length === 0)
+            return [];
+        if (this.archiveStore.deleteArchivedMany !== undefined)
+            return this.archiveStore.deleteArchivedMany(sessionIds);
+        if (this.archiveStore.deleteArchived === undefined)
+            throw new Error("Archive store does not support deletion");
+        for (const sessionId of sessionIds)
+            await this.archiveStore.deleteArchived(sessionId);
+        return [...sessionIds];
+    }
+    async moveLegacyArchivedRecordsForDelete(records) {
+        const legacyRecords = records.filter((record) => record.archivePath === undefined);
+        if (legacyRecords.length === 0)
+            return [];
+        let sessionsByCwd;
+        try {
+            sessionsByCwd = await this.listSessionsByCwd(legacyRecords.map((record) => record.cwd));
+        }
+        catch (error) {
+            return legacyRecords.map((record) => ({ sessionId: record.sessionId, error: errorMessage(error) }));
+        }
+        const moveInputs = legacyRecords
+            .map((record) => findSessionByIdOrPrefix(sessionsByCwd.get(record.cwd) ?? [], record.sessionId))
+            .filter(isDefined)
+            .map(archiveInputFromListEntry);
+        if (moveInputs.length === 0)
+            return [];
+        try {
+            await this.archiveStoreArchiveMany(moveInputs);
+            return [];
+        }
+        catch (error) {
+            const failedIds = new Set(moveInputs.map((input) => input.sessionId));
+            return legacyRecords
+                .filter((record) => failedIds.has(record.sessionId))
+                .map((record) => ({ sessionId: record.sessionId, error: errorMessage(error) }));
+        }
+    }
+    async cleanupPlan(request) {
+        const [sessions, archivedRecords] = await Promise.all([this.sessionManager.listAll?.() ?? [], this.archiveStore.list()]);
+        return planSessionCleanup({
+            sessions,
+            archivedRecords,
+            activeSessions: this.cleanupActiveSessionStatuses(),
+            thresholds: request.thresholds,
+            ...(request.projectCwds === undefined ? {} : { projectCwds: request.projectCwds }),
+            now: this.now(),
+        });
+    }
+    cleanupActiveSessionStatuses() {
+        return [...new Set(this.active.values())].map((active) => ({
+            sessionId: active.runtime.session.sessionId,
+            hasActiveWork: this.hasActiveWork(active.runtime.session),
+        }));
+    }
+    activeSessionHasWork(sessionId) {
+        const active = this.active.get(sessionId);
+        return active !== undefined && this.hasActiveWork(active.runtime.session);
+    }
     reconcilableSessionIds(cwd, listedSessionIds, archivedById) {
         const sessionIds = new Set(listedSessionIds);
         for (const active of new Set(this.active.values())) {
@@ -615,7 +1128,19 @@ export class PiSessionService {
         const session = (await this.sessionManager.list(record.cwd)).find((candidate) => candidate.id === record.sessionId);
         if (session === undefined)
             return record;
-        return this.archiveStore.archive(archiveInputFromListEntry(session));
+        const [moved] = await this.archiveStoreArchiveMany([archiveInputFromListEntry(session)]);
+        return moved ?? record;
+    }
+    async ensureArchivedRecordsMoved(records) {
+        const legacyRecords = records.filter((record) => record.archivePath === undefined);
+        if (legacyRecords.length === 0)
+            return;
+        const sessionsByCwd = await this.listSessionsByCwd(legacyRecords.map((record) => record.cwd));
+        const moveInputs = legacyRecords
+            .map((record) => sessionsByCwd.get(record.cwd)?.find((candidate) => candidate.id === record.sessionId))
+            .filter(isDefined)
+            .map(archiveInputFromListEntry);
+        await this.archiveStoreArchiveMany(moveInputs);
     }
     async archiveInputForSession(session) {
         const cwd = session.sessionManager.getCwd();
@@ -678,6 +1203,9 @@ export class PiSessionService {
         return [...names];
     }
     async closeActive(sessionId) {
+        const pendingOpens = this.pendingSessionOpenPromises(sessionId);
+        if (pendingOpens.length > 0)
+            await Promise.allSettled(pendingOpens);
         const active = this.active.get(sessionId);
         if (!active)
             return;
@@ -689,7 +1217,8 @@ export class PiSessionService {
         // Disarm subsession notification before teardown so the abort below cannot
         // emit a "stopped working" event that notifies the parent (e.g. on archive).
         // The parent/children link is kept so the parent can still see the child.
-        this.subsessionNotifyArmed.delete(sessionId);
+        if (this.subsessionLinkForActiveChild(active.runtime.session) !== undefined)
+            this.subsessionNotifyArmed.delete(sessionId);
         clearSessionQueue(active.runtime.session);
         active.unsubscribe();
         try {
@@ -711,14 +1240,40 @@ export class PiSessionService {
         if (active !== undefined)
             return active;
         const archived = await this.getArchived(ref);
-        if (archived?.archivePath !== undefined)
-            return this.create(this.sessionManager.open(archived.archivePath), archived.cwd);
+        if (archived?.archivePath !== undefined) {
+            const { archivePath } = archived;
+            return this.openExistingSession(archived.sessionId, archived.cwd, () => this.sessionManager.open(archivePath));
+        }
         const match = isPiSessionRef(ref)
             ? (await this.sessionManager.list(ref.cwd)).find((s) => s.id === ref.id || s.id.startsWith(ref.id))
             : (await this.sessionManager.listAll?.() ?? []).find((s) => s.id === ref || s.id.startsWith(ref));
         if (!match)
             throw new Error("Session not found");
-        return this.create(this.sessionManager.open(match.path), match.cwd);
+        return this.openExistingSession(match.id, match.cwd, () => this.sessionManager.open(match.path));
+    }
+    openExistingSession(sessionId, cwd, openSessionManager) {
+        const active = this.activeForLookup({ id: sessionId, cwd });
+        if (active !== undefined)
+            return Promise.resolve(active);
+        const key = JSON.stringify([canonicalizeStoredCwd(cwd), sessionId]);
+        const existing = this.pendingSessionOpens.get(key);
+        if (existing !== undefined)
+            return existing.promise;
+        const pending = {
+            sessionId,
+            promise: this.create(openSessionManager(), cwd),
+        };
+        pending.promise = pending.promise.finally(() => {
+            if (this.pendingSessionOpens.get(key) === pending)
+                this.pendingSessionOpens.delete(key);
+        });
+        this.pendingSessionOpens.set(key, pending);
+        return pending.promise;
+    }
+    pendingSessionOpenPromises(sessionId) {
+        return [...this.pendingSessionOpens.values()]
+            .filter((pending) => sessionId === undefined || pending.sessionId === sessionId)
+            .map((pending) => pending.promise);
     }
     async getArchived(ref) {
         const archived = await this.archiveStore.get(sessionIdFromLookup(ref));
@@ -739,18 +1294,53 @@ export class PiSessionService {
         }
         return undefined;
     }
-    async create(sessionManager, cwd) {
-        const runtime = await this.createAgentRuntime(this.createRuntime, { cwd, agentDir: this.agentDir, sessionManager });
-        await this.bindSessionExtensions(runtime.session);
+    async create(sessionManager, cwd, options = {}) {
+        const delegationToolsEnabled = options.creationProvenance !== "tracked-subsession"
+            && await sessionAllowsDelegationTools(sessionManager, this.sessionManager);
+        const runtime = await this.createAgentRuntime(this.createRuntime, {
+            cwd,
+            agentDir: this.agentDir,
+            sessionManager,
+            delegationToolsEnabled,
+            ...(options.initialModel === undefined ? {} : { initialModel: options.initialModel }),
+        });
         const active = { runtime, unsubscribe: noop };
-        this.bindRuntime(active);
-        runtime.setRebindSession(async (session) => {
-            await this.bindSessionExtensions(session);
+        try {
+            await this.bindSessionExtensions(runtime.session);
             this.bindRuntime(active);
-        });
-        this.active.set(runtime.session.sessionId, active);
-        this.publishStatus(runtime.session);
-        return active;
+            runtime.setRebindSession(async (session) => {
+                await this.bindSessionExtensions(session);
+                this.bindRuntime(active);
+                await this.recoverSubsessionTrackingForOpenedSession(session);
+            });
+            this.active.set(runtime.session.sessionId, active);
+            await this.recoverSubsessionTrackingForOpenedSession(runtime.session);
+            this.publishStatus(runtime.session);
+            return active;
+        }
+        catch (error) {
+            active.unsubscribe();
+            let removedActive = false;
+            for (const [sessionId, candidate] of this.active.entries()) {
+                if (candidate !== active)
+                    continue;
+                this.active.delete(sessionId);
+                this.activities.delete(sessionId);
+                this.clearAuthLossWarningsForSession(sessionId);
+                this.clearCompactionPromptQueue(sessionId);
+                removedActive = true;
+            }
+            if (removedActive) {
+                this.workspaceActivity?.removeSession(runtime.session.sessionId, runtime.session.sessionManager.getCwd());
+            }
+            try {
+                await runtime.session.abort();
+            }
+            finally {
+                await runtime.dispose();
+            }
+            throw error;
+        }
     }
     async bindSessionExtensions(session) {
         await session.bindExtensions({
@@ -846,10 +1436,15 @@ 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;
-        void generateShortSessionName(this.modelRegistry, model, firstMessage).then((name) => {
+        void generateShortSessionName(session.agent.streamFn, model, firstMessage).then((name) => {
             this.applyGeneratedSessionName(session, name ?? fallbackSessionName(firstMessage));
         }).catch(() => {
             this.applyGeneratedSessionName(session, fallbackSessionName(firstMessage));
@@ -1026,6 +1621,7 @@ export class PiSessionService {
         const contextUsage = session.getContextUsage();
         return {
             sessionId: session.sessionId,
+            persisted: sessionFileExists(session.sessionFile),
             ...(model === undefined ? {} : { model }),
             thinkingLevel: session.thinkingLevel,
             isStreaming: session.isStreaming,
@@ -1049,6 +1645,47 @@ export class PiSessionService {
         return queuedMessagesFromSession(session, this.compactionQueuedMessages(session.sessionId)).some((message) => message.text === text);
     }
 }
+function previewResponseFromPlan(plan) {
+    return {
+        generatedAt: plan.generatedAt,
+        thresholds: plan.thresholds,
+        projects: plan.projects,
+        totals: plan.totals,
+        ...(plan.skippedBusySessionIds.length === 0 ? {} : { skippedBusySessionIds: plan.skippedBusySessionIds }),
+    };
+}
+function uniqueBulkSessionRefs(refs) {
+    const seen = new Set();
+    const unique = [];
+    for (const ref of refs) {
+        const key = `${ref.cwd ?? ""}\0${ref.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(ref);
+    }
+    return unique;
+}
+function bulkRefToLookup(ref) {
+    return ref.cwd === undefined ? ref.id : { id: ref.id, cwd: ref.cwd };
+}
+function findArchivedRecordForBulkRef(records, ref) {
+    return records.find((record) => (ref.cwd === undefined || record.cwd === ref.cwd) && (record.sessionId === ref.id || record.sessionId.startsWith(ref.id)));
+}
+function findListedSessionForBulkRef(context, ref) {
+    if (ref.cwd !== undefined)
+        return findSessionByIdOrPrefix(context.sessionsByCwd.get(ref.cwd) ?? [], ref.id);
+    return context.allSessions === undefined ? undefined : findSessionByIdOrPrefix(context.allSessions, ref.id);
+}
+function findSessionByIdOrPrefix(sessions, sessionId) {
+    return sessions.find((session) => session.id === sessionId) ?? sessions.find((session) => session.id.startsWith(sessionId));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function modelToClientModel(model) {
     if (model === undefined)
         return {};
@@ -1067,6 +1704,7 @@ function clientSessionFromListEntry(session) {
         id: session.id,
         path: session.path,
         cwd: session.cwd,
+        persisted: true,
         ...(session.name === undefined ? {} : { name: session.name }),
         created: session.created.toISOString(),
         modified: session.modified.toISOString(),
@@ -1195,6 +1833,191 @@ function archivedTimestamp(record) {
 function isDefined(value) {
     return value !== undefined;
 }
+/**
+ * Resolve the delegation capability from server-owned, persisted session
+ * provenance. A copied marker is not enough: the child header and reciprocal
+ * parent link must identify the exact same session files.
+ */
+export async function sessionAllowsDelegationTools(sessionManager, managers) {
+    const trackedLink = await verifiedTrackedSubsessionLink(managers, {
+        sessionId: sessionManager.getSessionId(),
+        sessionFile: sessionManager.getSessionFile(),
+        sessionManager,
+        cwd: sessionManager.getCwd(),
+    });
+    return trackedLink === undefined;
+}
+async function verifiedTrackedSubsessionLink(managers, session) {
+    // Child markers are only hints; the current child header and reciprocal
+    // parent custom link must agree on the exact ids and files before relinking.
+    const entries = session.sessionManager.getEntries?.() ?? session.sessionManager.getBranch();
+    let marker;
+    for (const entry of entries) {
+        const parsed = parsePersistedChildSubsessionLink(entry);
+        if (parsed?.spawnedSessionId === session.sessionId)
+            marker = parsed;
+    }
+    if (marker === undefined)
+        return undefined;
+    const childSessionFile = nonEmptyString(session.sessionFile);
+    if (childSessionFile === undefined)
+        return undefined;
+    const childHeader = await readSessionHeaderSummary(childSessionFile);
+    if (childHeader?.id !== session.sessionId)
+        return undefined;
+    const parentSessionFile = nonEmptyString(childHeader.parentSession);
+    if (parentSessionFile === undefined)
+        return undefined;
+    const parentHeader = await readSessionHeaderSummary(parentSessionFile);
+    if (parentHeader?.id !== marker.spawnedBySessionId)
+        return undefined;
+    const parentLink = findReciprocalParentSubsessionLink(managers, parentSessionFile, marker.spawnedBySessionId, session.sessionId, childSessionFile);
+    if (parentLink === undefined)
+        return undefined;
+    return {
+        parentSessionId: marker.spawnedBySessionId,
+        childSessionId: session.sessionId,
+        childSessionFile,
+        parentSessionFile,
+        cwd: parentLink.cwd ?? session.cwd,
+    };
+}
+function findReciprocalParentSubsessionLink(managers, parentSessionFile, parentSessionId, childSessionId, childSessionFile) {
+    let parentManager;
+    try {
+        parentManager = managers.open(parentSessionFile);
+    }
+    catch {
+        return undefined;
+    }
+    const entries = parentManager.getEntries?.() ?? parentManager.getBranch();
+    for (const entry of entries) {
+        const link = parsePersistedParentSubsessionLink(entry);
+        if (link === undefined)
+            continue;
+        if (link.spawnedBySessionId !== parentSessionId || link.spawnedSessionId !== childSessionId)
+            continue;
+        if (link.spawnedSessionFile === undefined || !sessionPathsEqual(link.spawnedSessionFile, childSessionFile))
+            continue;
+        return link;
+    }
+    return undefined;
+}
+function trackedSubsessionLinkFromParentLink(parentSessionId, link, parentSessionFile) {
+    return {
+        parentSessionId,
+        childSessionId: link.spawnedSessionId,
+        ...(link.spawnedSessionFile === undefined ? {} : { childSessionFile: link.spawnedSessionFile }),
+        parentSessionFile,
+        ...(link.cwd === undefined ? {} : { cwd: link.cwd }),
+    };
+}
+function persistedParentSubsessionLinkData(link) {
+    return {
+        version: 1,
+        spawnedBySessionId: link.parentSessionId,
+        spawnedSessionId: link.childSessionId,
+        ...(link.childSessionFile === undefined ? {} : { spawnedSessionFile: link.childSessionFile }),
+        ...(link.cwd === undefined ? {} : { cwd: link.cwd }),
+    };
+}
+function persistedChildSubsessionLinkData(parentSessionId, childSessionId) {
+    return {
+        version: 1,
+        spawnedBySessionId: parentSessionId,
+        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;
+}
+function subsessionHydratedParentKey(parentSessionId, parentSessionFile) {
+    return `${parentSessionId}\0${parentSessionFile ?? ""}`;
+}
+function sessionPathsEqual(a, b) {
+    return cwdPathsEqual(a, b);
+}
+function sessionFileExists(sessionFile) {
+    if (sessionFile === undefined || sessionFile === "")
+        return false;
+    try {
+        return statSync(sessionFile).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function sessionFileMatches(session, expectedSessionFile) {
+    const sessionFile = nonEmptyString(session.sessionFile);
+    return sessionFile !== undefined && expectedSessionFile !== undefined && sessionPathsEqual(sessionFile, expectedSessionFile);
+}
+function activeSessionFileMatches(active, expectedSessionFile) {
+    return sessionFileMatches(active.runtime.session, expectedSessionFile);
+}
+function trackedLinkParentFileMatches(link, parentSessionFile) {
+    return link.parentSessionFile !== undefined && sessionPathsEqual(link.parentSessionFile, parentSessionFile);
+}
+async function readSessionHeaderSummary(sessionFile) {
+    let file;
+    try {
+        file = await open(sessionFile, "r");
+        const buffer = Buffer.alloc(4096);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        const firstLine = buffer.toString("utf8", 0, bytesRead).split("\n", 1)[0];
+        if (firstLine === undefined || firstLine === "")
+            return undefined;
+        const header = JSON.parse(firstLine);
+        if (!isRecord(header) || header["type"] !== "session" || typeof header["id"] !== "string")
+            return undefined;
+        const parentSession = getString(header, "parentSession");
+        return { id: header["id"], ...(parentSession === undefined ? {} : { parentSession }) };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await file?.close().catch(() => undefined);
+    }
+}
+async function sessionFileHeaderMatches(sessionFile, expected) {
+    const header = await readSessionHeaderSummary(sessionFile);
+    if (header?.id !== expected.sessionId)
+        return false;
+    if (expected.parentSessionFile === undefined)
+        return true;
+    return header.parentSession !== undefined && sessionPathsEqual(header.parentSession, expected.parentSessionFile);
+}
 async function clearParentSession(sessionFile) {
     const content = await readFile(sessionFile, "utf8");
     const newlineIndex = content.indexOf("\n");
@@ -1208,6 +2031,11 @@ async function clearParentSession(sessionFile) {
     delete header["parentSession"];
     await writeFile(sessionFile, `${JSON.stringify(header)}${rest}`, "utf8");
 }
+function clearParentSessionHeader(sessionManager) {
+    const header = sessionManager.getHeader?.();
+    if (header !== undefined && header !== null)
+        delete header.parentSession;
+}
 function clearSessionQueue(session) {
     session.clearQueue();
 }
@@ -1262,6 +2090,10 @@ function historyMessages(session) {
     }
     return messages;
 }
+/** custom entry type used to persist parent -> child subsession links outside LLM context. */
+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_PREVIEW_CHARS = 2000;