@chainingintention/pi-web-cn 1.202606.25 → 1.202606.26

package/dist/server/sessions/piSessionService.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { open, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import { AuthStorage, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, defineTool, getAgentDir, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
@@ -15,6 +15,7 @@ import { 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";
 import { createManagedAgentToolOptions, createManagedPythonToolDefinition } from "./managementAgentTools.js";
 import { PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR, managementAgentToolNames, withRuntimeCreationEnvironment, writeManagementPermissionSystemPolicy } from "./managementPermissionSystem.js";
 import { archiveCandidateFromActiveSession, archiveCandidateFromArchivedRecord, archiveCandidateFromListEntry, archiveInputFromActiveSession, archiveInputFromCandidate, archiveInputFromListEntry, clientSessionFromArchivedRecord, compareArchivedRecords, } from "./sessionArchiveMapping.js";
@@ -85,19 +86,36 @@ function pathInsideOrEqual(parent, child) {
 function defaultCreateAgentRuntime(createRuntime, options) {
     if (!(options.sessionManager instanceof SessionManager))
         throw new Error("Default runtime creation requires an SDK SessionManager");
-    const runtimeFactory = (runtimeOptions) => {
-        return createRuntime(options.managementContext === undefined ? runtimeOptions : { ...runtimeOptions, managementContext: options.managementContext });
+    const runtimeFactory = createRuntimeWithContextAndOneShotInitialModel(createRuntime, options.managementContext, options.initialModel);
+    return createAgentSessionRuntime(runtimeFactory, {
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        sessionManager: options.sessionManager,
+    });
+}
+function createRuntimeWithContextAndOneShotInitialModel(createRuntime, managementContext, initialModel) {
+    // The inherited model belongs only to the session being spawned. Do not keep
+    // reapplying it if that runtime later creates/forks/switches sessions itself.
+    let pendingInitialModel = initialModel;
+    return async (options) => {
+        const model = pendingInitialModel;
+        pendingInitialModel = undefined;
+        return createRuntime({
+            ...options,
+            ...(managementContext === undefined ? {} : { managementContext }),
+            ...(model === undefined ? {} : { initialModel: model }),
+        });
     };
-    return createAgentSessionRuntime(runtimeFactory, { ...options, sessionManager: options.sessionManager });
 }
 function createDefaultRuntimeFactory(authStorage, modelRegistry, spawn, subsessions) {
-    return async ({ cwd, agentDir, sessionManager, sessionStartEvent, managementContext }) => {
+    return async ({ cwd, agentDir, sessionManager, sessionStartEvent, managementContext, initialModel }) => {
         if (managementContext !== undefined) {
             return createManagementRuntimeFactory(authStorage, modelRegistry, spawn, subsessions, managementContext)({
                 cwd,
                 agentDir,
                 sessionManager,
                 ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
+                ...(initialModel === undefined ? {} : { initialModel }),
             });
         }
         const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
@@ -106,18 +124,18 @@ function createDefaultRuntimeFactory(authStorage, modelRegistry, spawn, subsessi
             ...(spawn === undefined ? [] : [defineTool(createSpawnSessionToolDefinition(cwd, { spawn }))]),
             ...(subsessions === undefined ? [] : createSubsessionToolDefinitions(cwd, subsessions).map((tool) => defineTool(tool))),
         ];
-        const options = {
+        const result = await createAgentSessionFromServices({
             services,
             sessionManager,
-            ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
             customTools,
-        };
-        const result = await createAgentSessionFromServices(options);
+            ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
+            ...(initialModel === undefined ? {} : { model: initialModel }),
+        });
         return { ...result, services, diagnostics: services.diagnostics };
     };
 }
 function createManagementRuntimeFactory(authStorage, modelRegistry, spawn, subsessions, managementContext) {
-    return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
+    return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel }) => {
         const policyAgentDir = await writeManagementPermissionSystemPolicy(agentDir, cwd, managementContext);
         return withRuntimeCreationEnvironment({ [PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR]: policyAgentDir }, async () => {
             const services = await createAgentSessionServices({
@@ -142,6 +160,7 @@ function createManagementRuntimeFactory(authStorage, modelRegistry, spawn, subse
                 ...(sessionStartEvent === undefined ? {} : { sessionStartEvent }),
                 customTools,
                 tools: managementAgentToolNames(managementContext),
+                ...(initialModel === undefined ? {} : { model: initialModel }),
             };
             const result = await createAgentSessionFromServices(options);
             return { ...result, services, diagnostics: services.diagnostics };
@@ -193,6 +212,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
@@ -205,14 +228,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 : {
             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;
@@ -231,6 +255,44 @@ export class PiSessionService {
     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)
+            throw new Error("Archive store does not support deletion");
+        const archiveInputs = [];
+        const deleteRecords = [];
+        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);
+            await this.archiveStore.archive(input);
+            archiveInputs.push(input);
+        }
+        for (const record of plan.deleteRecords) {
+            if (this.activeSessionHasWork(record.sessionId)) {
+                skippedBusySessionIds.add(record.sessionId);
+                continue;
+            }
+            await this.closeActive(record.sessionId);
+            if (record.archivePath === undefined)
+                await this.ensureArchivedRecordMoved(record);
+            await this.archiveStore.deleteArchived?.(record.sessionId);
+            deleteRecords.push(record);
+        }
+        return summarizeSessionCleanupExecution({
+            archiveInputs,
+            deleteRecords,
+            thresholds: plan.thresholds,
+            generatedAt: plan.generatedAt,
+            skippedBusySessionIds: [...skippedBusySessionIds],
+        });
+    }
     async dispose() {
         clearInterval(this.heartbeat);
         this.clearCompactionDrainTimers();
@@ -241,6 +303,8 @@ export class PiSessionService {
         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();
@@ -265,7 +329,10 @@ export class PiSessionService {
         return [...unarchivedSessions, ...archivedSessions];
     }
     async start(cwd, options = {}) {
-        const active = await this.create(this.sessionManager.create(cwd, options.parentSession === undefined ? undefined : { parentSession: options.parentSession }), cwd, options.managementContext);
+        const active = await this.create(this.sessionManager.create(cwd, options.parentSession === undefined ? undefined : { parentSession: options.parentSession }), cwd, {
+            ...(options.managementContext === undefined ? {} : { managementContext: options.managementContext }),
+            ...(options.initialModel === undefined ? {} : { initialModel: options.initialModel }),
+        });
         const { session } = active.runtime;
         const created = {
             id: session.sessionId,
@@ -295,7 +362,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 };
@@ -312,69 +379,294 @@ 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 === undefined ? undefined : { parentSession: input.parentSessionFile });
-        this.registerSubsession(input.parentSessionId, created.id);
+        const created = await this.start(decision.cwd, {
+            ...(input.parentSessionFile === undefined ? {} : { parentSession: input.parentSessionFile }),
+            ...(input.model === undefined ? {} : { initialModel: input.model }),
+        });
+        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);
+    }
+    async verifiedSubsessionLinkFromOpenedChild(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 = this.findReciprocalParentSubsessionLink(parentSessionFile, marker.spawnedBySessionId, session.sessionId, childSessionFile);
+        if (parentLink === undefined)
+            return undefined;
+        return {
+            parentSessionId: marker.spawnedBySessionId,
+            childSessionId: session.sessionId,
+            childSessionFile,
+            parentSessionFile,
+            cwd: parentLink.cwd ?? session.sessionManager.getCwd(),
+        };
+    }
+    findReciprocalParentSubsessionLink(parentSessionFile, parentSessionId, childSessionId, childSessionFile) {
+        let parentManager;
+        try {
+            parentManager = this.sessionManager.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;
+    }
+    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")
@@ -388,10 +680,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;
@@ -403,7 +695,23 @@ export class PiSessionService {
         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);
+        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
@@ -414,7 +722,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);
         }
@@ -552,7 +860,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);
@@ -665,6 +973,8 @@ export class PiSessionService {
         if (sessionFile === undefined || sessionFile === "")
             throw new Error("会话尚未持久化");
         await clearParentSession(sessionFile);
+        clearParentSessionHeader(session.sessionManager);
+        this.unregisterSubsession(session.sessionId);
     }
     async abort(ref) {
         const active = this.activeForLookupAny(ref);
@@ -685,6 +995,27 @@ export class PiSessionService {
             // Best-effort shutdown; callers that need errors await closeActive directly.
         });
     }
+    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())) {
@@ -782,7 +1113,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 {
@@ -807,14 +1139,15 @@ export class PiSessionService {
         if (mismatched !== undefined)
             await this.closeActive(mismatched.runtime.session.sessionId);
         const archived = await this.getArchived(ref);
-        if (archived?.archivePath !== undefined)
-            return this.create(this.sessionManager.open(archived.archivePath), archived.cwd, managementContext);
+        if (archived?.archivePath !== undefined) {
+            return this.create(this.sessionManager.open(archived.archivePath), archived.cwd, managementContext === undefined ? {} : { managementContext });
+        }
         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("未找到会话");
-        return this.create(this.sessionManager.open(match.path), match.cwd, managementContext);
+        return this.create(this.sessionManager.open(match.path), match.cwd, managementContext === undefined ? {} : { managementContext });
     }
     async getArchived(ref) {
         const archived = await this.archiveStore.get(sessionIdFromLookup(ref));
@@ -847,16 +1180,24 @@ export class PiSessionService {
         }
         return undefined;
     }
-    async create(sessionManager, cwd, managementContext) {
-        const runtime = await this.createAgentRuntime(this.createRuntime, managementContext === undefined ? { cwd, agentDir: this.agentDir, sessionManager } : { cwd, agentDir: this.agentDir, sessionManager, managementContext });
+    async create(sessionManager, cwd, options = {}) {
+        const runtime = await this.createAgentRuntime(this.createRuntime, {
+            cwd,
+            agentDir: this.agentDir,
+            sessionManager,
+            ...(options.managementContext === undefined ? {} : { managementContext: options.managementContext }),
+            ...(options.initialModel === undefined ? {} : { initialModel: options.initialModel }),
+        });
         await this.bindSessionExtensions(runtime.session);
-        const active = { runtime, unsubscribe: noop, managementContextKey: managementContextKey(managementContext) };
+        const active = { runtime, unsubscribe: noop, managementContextKey: managementContextKey(options.managementContext) };
         this.bindRuntime(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;
     }
@@ -1157,6 +1498,15 @@ 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 modelToClientModel(model) {
     if (model === undefined)
         return {};
@@ -1197,6 +1547,111 @@ function addSessionName(names, name) {
 function isDefined(value) {
     return value !== 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 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");
@@ -1210,6 +1665,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();
 }
@@ -1264,6 +1724,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;