@hyperdreamer/pi-webui 1.11.0-beta.8 → 1.11.0

package/dist/server/sessions/piSessionService.js

@@ -10,7 +10,7 @@ import { BUILTIN_COMMANDS } from "./builtinCommands.js";
 import { SessionCommandService, clientSessionFromRuntime, } from "./sessionCommandService.js";
 import { projectSessionTree, } from "./sessionTreeProjection.js";
 import { SessionArchiveStore, } from "./sessionArchiveStore.js";
-import { SessionMetadataStore } from "./sessionMetadataStore.js";
+import { SessionMetadataStore, SessionMetadataOrderConflictError } from "./sessionMetadataStore.js";
 import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree, } from "./sessionArchiveTree.js";
 import { deterministicSessionName, fallbackSessionName, generateShortSessionName, } from "./sessionNameGenerator.js";
 import { computeEditPreview } from "./editPreview.js";
@@ -18,6 +18,7 @@ import { attachmentsToInlineImages, saveAttachmentsToWorkspace, } from "./attach
 import { parsePromptAttachments } from "../../shared/promptAttachments.js";
 import { isKnownThinkingLevel } from "../../shared/thinkingLevels.js";
 import { SESSION_TREE_CUSTOM_INSTRUCTIONS_MAX_LENGTH, SESSION_UNREAD_LIMIT, } from "../../shared/apiTypes.js";
+import { assertSubmittedSessionsCurrent, SessionReorderDomainError, validateSessionReorder, } from "./sessionReorder.js";
 import { canonicalizeStoredCwd, cwdPathsEqual } from "../workingDirectory.js";
 import { createSpawnSessionToolDefinition, } from "./spawnSessionTool.js";
 import { createSubsessionToolDefinitions, } from "./spawnSubsessionTool.js";
@@ -29,7 +30,13 @@ import { SessionNotificationStore, } from "./sessionNotificationStore.js";
 import { plainTextTheme } from "./plainTextTheme.js";
 import { SessionUnreadStore, } from "./sessionUnreadStore.js";
 import { createModelTierRegistry, isModelTier, runtimeThinkingLevels, } from "./modelTierRegistry.js";
-import { inspectSessionModelPolicy, planSessionModelPolicyUpdate, serializeSessionModelPolicy, SESSION_MODEL_POLICY_CUSTOM_TYPE, } from "./sessionModelPolicy.js";
+import { createUtilityModelExtension, } from "./utilityModelExtension.js";
+import { createUtilityModelResolver, runWithUtilityModelFallback, } from "./utilityModelResolver.js";
+import { inspectSessionModelPolicy, planSessionModelPolicyInitialization, planSessionModelPolicyUpdate, serializeSessionModelPolicy, SESSION_MODEL_POLICY_CUSTOM_TYPE, } from "./sessionModelPolicy.js";
+import { inspectSessionCreationRootEligibility, inspectSessionCreationSource, serializeSessionCreationSource, SESSION_CREATION_SOURCE_CUSTOM_TYPE, } from "./sessionCreationSource.js";
+import { RememberCurrentModelPolicyCommand, } from "./rememberCurrentModelPolicy.js";
+import { StarterModelPolicyPreferenceStore } from "./starterModelPolicyPreferenceStore.js";
+import { captureModelPolicySettings, modelPolicySettingsPersistence, restoreModelPolicySettings, settleModelPolicySettings, } from "./modelPolicySettingsPersistence.js";
 const noopLogger = {
     info() {
         /* no-op */
@@ -43,6 +50,33 @@ const MIN_GENERATION_RATE_ELAPSED_MS = 500;
 function noop() {
     // Intentionally empty default unsubscribe callback.
 }
+function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+class SessionInitializationCleanupAggregateError extends AggregateError {
+    constructor(initializationError, cleanupFailures, completeInitialization) {
+        super([initializationError, ...cleanupFailures], completeInitialization
+            ? `Complete session initialization failed and rollback was incomplete: ${initializationError.message}`
+            : `Session initialization failed and cleanup was incomplete: ${initializationError.message}`);
+        this.initializationError = initializationError;
+        this.cleanupFailures = [...cleanupFailures];
+        this.completeInitialization = completeInitialization;
+    }
+}
+function sessionInitializationCleanupFailure(error, cleanupFailures, completeInitialization = false) {
+    if (error instanceof SessionInitializationCleanupAggregateError) {
+        if (cleanupFailures.length === 0)
+            return error;
+        return new SessionInitializationCleanupAggregateError(error.initializationError, [...error.cleanupFailures, ...cleanupFailures], error.completeInitialization || completeInitialization);
+    }
+    const initializationError = normalizeError(error);
+    if (cleanupFailures.length === 0)
+        return initializationError;
+    return new SessionInitializationCleanupAggregateError(initializationError, cleanupFailures, completeInitialization);
+}
+function completeInitializationFailure(error, rollbackFailures) {
+    return sessionInitializationCleanupFailure(error, rollbackFailures, true);
+}
 function spawnTargetError(decision) {
     if (decision.reason === "not-registered")
         return new Error("Spawning session is not in a registered project");
@@ -284,17 +318,34 @@ export function createPiWebUiCustomToolDefinitions(cwd, delegationEnabled, spawn
             : []),
     ];
 }
-function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subsessions, modelPolicy) {
+export function createDefaultRuntimeFactory(modelRuntime, sessionManagers, utilityModelResolver, logger, spawn, subsessions, modelPolicy, sdk = {
+    createServices: createAgentSessionServices,
+    createFromServices: createAgentSessionFromServices,
+}) {
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel, initialThinkingLevel, delegationToolsEnabled, }) => {
-        const services = await createAgentSessionServices({
+        const runtimeRefs = {};
+        const services = await sdk.createServices({
             cwd,
             agentDir,
             modelRuntime,
+            resourceLoaderOptions: {
+                extensionFactories: [
+                    createUtilityModelExtension({
+                        // Pi's ExtensionContext exposes Model<any>; production candidates still come from ModelRuntime's Model<Api> snapshot.
+                        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                        resolver: utilityModelResolver,
+                        modelRuntime,
+                        refs: runtimeRefs,
+                        logger,
+                    }),
+                ],
+            },
         });
+        runtimeRefs.settingsManager = services.settingsManager;
         const resolvedDelegationToolsEnabled = delegationToolsEnabled ??
             (await sessionAllowsDelegationTools(sessionManager, sessionManagers));
         const customTools = createPiWebUiCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions, modelPolicy);
-        const result = await createAgentSessionFromServices({
+        const result = await sdk.createFromServices({
             services,
             sessionManager,
             customTools,
@@ -304,6 +355,7 @@ function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subse
                 ? {}
                 : { thinkingLevel: initialThinkingLevel }),
         });
+        runtimeRefs.streamFunction = result.session.agent.streamFunction;
         return { ...result, services, diagnostics: services.diagnostics };
     };
 }
@@ -415,13 +467,40 @@ export class PiSessionService {
         this.pendingUnreadMutations = [];
         this.unreadPublicationFlushRequested = false;
         this.unreadPublicationStopped = false;
+        /**
+         * Serializes reorder against every other mutation that can change sibling
+         * membership, pin state, or current/archive membership (pin, unpin,
+         * detach-parent, archive, archiveMany, archiveTree, restore, and cleanup),
+         * so no such mutation can interleave with a reorder's before/after catalog
+         * reads and its atomic metadata write.
+         */
+        this.sessionOrderMutationQueue = Promise.resolve();
         this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
         this.metadataStore = deps.metadataStore ?? new SessionMetadataStore();
+        this.clearParentSessionFile = deps.clearParentSession ?? clearParentSession;
         this.agentDir = deps.agentDir;
         this.sessionManager = deps.sessionManager;
         this.modelRuntime = deps.modelRuntime;
         this.spawnTargets = deps.spawnTargets;
         this.logger = deps.logger ?? noopLogger;
+        this.utilityModelResolver =
+            deps.utilityModelResolver ??
+                createUtilityModelResolver({
+                    loadConfig: () => {
+                        const loaded = loadPiWebUiConfig();
+                        return {
+                            ...(loaded.config.utilityModels === undefined
+                                ? {}
+                                : { utilityModels: loaded.config.utilityModels }),
+                            ...(loaded.utilityModelsError === undefined
+                                ? {}
+                                : { utilityModelsError: loaded.utilityModelsError }),
+                        };
+                    },
+                    modelRuntime: this.modelRuntime,
+                    thinkingLevelsForModel: runtimeThinkingLevels,
+                    logger: this.logger,
+                });
         this.now = deps.now ?? (() => new Date());
         this.notificationStore =
             deps.notificationStore ?? new SessionNotificationStore();
@@ -433,7 +512,7 @@ export class PiSessionService {
         const subsessionsActive = this.spawnTargets !== undefined && deps.subsessionsEnabled === true;
         this.createRuntime =
             deps.createRuntime ??
-                createDefaultRuntimeFactory(this.modelRuntime, this.sessionManager, this.spawnTargets === undefined
+                createDefaultRuntimeFactory(this.modelRuntime, this.sessionManager, this.utilityModelResolver, this.logger, this.spawnTargets === undefined
                     ? undefined
                     : (input) => this.spawnSession(input), !subsessionsActive
                     ? undefined
@@ -467,6 +546,11 @@ export class PiSessionService {
                     supportedThinkingLevels: runtimeThinkingLevels,
                 });
         this.workspaceActivity = deps.workspaceActivity;
+        this.rememberCurrentModelPolicyCommand = new RememberCurrentModelPolicyCommand({
+            loadSnapshot: (session) => this.confirmedPolicySnapshot(session),
+            preferenceStore: deps.starterModelPolicyPreferenceStore ??
+                new StarterModelPolicyPreferenceStore(),
+        });
         this.heartbeat = setInterval(() => {
             this.publishHeartbeats();
         }, deps.heartbeatIntervalMs ?? 2000);
@@ -530,51 +614,53 @@ export class PiSessionService {
         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;
+        return await this.runSessionOrderMutation(async () => {
+            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, {
+                    kind: "clear",
+                    reason: "archive",
+                });
+                readyArchiveInputs.push(input);
             }
-            await this.closeActive(input.sessionId, {
-                kind: "clear",
-                reason: "archive",
-            });
-            readyArchiveInputs.push(input);
-        }
-        await this.archiveStoreArchiveMany(readyArchiveInputs);
-        archiveInputs.push(...readyArchiveInputs);
-        await this.forgetUnreadSessions(readyArchiveInputs);
-        for (const record of plan.deleteRecords) {
-            if (this.activeSessionHasWork(record.sessionId)) {
-                skippedBusySessionIds.add(record.sessionId);
-                continue;
+            await this.archiveStoreArchiveMany(readyArchiveInputs);
+            archiveInputs.push(...readyArchiveInputs);
+            await this.forgetUnreadSessions(readyArchiveInputs);
+            for (const record of plan.deleteRecords) {
+                if (this.activeSessionHasWork(record.sessionId)) {
+                    skippedBusySessionIds.add(record.sessionId);
+                    continue;
+                }
+                await this.closeActive(record.sessionId, {
+                    kind: "clear",
+                    reason: "delete",
+                });
+                readyDeleteRecords.push(record);
             }
-            await this.closeActive(record.sessionId, {
-                kind: "clear",
-                reason: "delete",
+            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)));
+            await this.forgetUnreadSessions(deleteRecords);
+            return summarizeSessionCleanupExecution({
+                archiveInputs,
+                deleteRecords,
+                thresholds: plan.thresholds,
+                generatedAt: plan.generatedAt,
+                skippedBusySessionIds: [...skippedBusySessionIds],
             });
-            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)));
-        await this.forgetUnreadSessions(deleteRecords);
-        return summarizeSessionCleanupExecution({
-            archiveInputs,
-            deleteRecords,
-            thresholds: plan.thresholds,
-            generatedAt: plan.generatedAt,
-            skippedBusySessionIds: [...skippedBusySessionIds],
         });
     }
     async forceCleanup() {
@@ -649,12 +735,68 @@ export class PiSessionService {
         await this.publishUnreadMutations([]);
     }
     async list(cwd) {
-        const [sessions, archivedRecords, pinnedPaths] = await Promise.all([
+        const [sessions, archivedRecords, metadata] = await Promise.all([
             this.sessionManager.list(cwd),
             this.archiveStore.list(),
-            this.metadataStore.pinnedPaths(),
+            this.metadataStore.snapshot(),
         ]);
-        const pinnedPathSet = new Set(pinnedPaths);
+        return this.listFromSnapshots(cwd, sessions, archivedRecords, metadata);
+    }
+    /**
+     * Run `operation` inside the exclusive ordering queue shared by every
+     * mutation that can change sibling membership, pin state, or
+     * current/archive membership, so reorder's before/after catalog reads
+     * never interleave with a concurrent pin, detach, archive, or restore.
+     */
+    async runSessionOrderMutation(operation) {
+        const previous = this.sessionOrderMutationQueue;
+        let release = () => undefined;
+        this.sessionOrderMutationQueue = new Promise((resolve) => { release = resolve; });
+        await previous.catch(() => undefined);
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async reorder(ref, request) {
+        return await this.runSessionOrderMutation(async () => {
+            const target = { id: ref.id, cwd: canonicalizeStoredCwd(ref.cwd) };
+            const before = await this.listReorderCatalog(request.catalogCwds);
+            const validated = validateSessionReorder(target, request, uniqueSessionsByIdentity(before));
+            try {
+                await this.metadataStore.replaceOrder(validated.sessionPaths, request.scope, request.pinned);
+            }
+            catch (error) {
+                if (error instanceof SessionMetadataOrderConflictError) {
+                    throw new SessionReorderDomainError("conflict", error.message);
+                }
+                throw error;
+            }
+            const after = await this.listReorderCatalog(request.catalogCwds);
+            assertSubmittedSessionsCurrent(target, request, uniqueSessionsByIdentity(after));
+            return validated.response;
+        });
+    }
+    /**
+     * Read one coherent metadata/archive view across every requested CWD.
+     * Gateway session-list reads run in parallel per CWD, but the metadata and
+     * archive snapshots are each taken exactly once for the whole call, so the
+     * result is one atomic before/after catalog rather than one per CWD.
+     */
+    async listReorderCatalog(cwds) {
+        const metadataPromise = this.metadataStore.snapshot();
+        const archivePromise = this.archiveStore.list();
+        const sessionListsPromise = Promise.all(cwds.map((cwd) => this.sessionManager.list(cwd)));
+        const [metadata, archivedRecords, sessionLists] = await Promise.all([
+            metadataPromise,
+            archivePromise,
+            sessionListsPromise,
+        ]);
+        return (await Promise.all(cwds.map((cwd, index) => this.listFromSnapshots(cwd, sessionLists[index] ?? [], archivedRecords, metadata)))).flat();
+    }
+    async listFromSnapshots(cwd, sessions, archivedRecords, metadata) {
         const sessionsById = new Map(sessions.map((session) => [session.id, session]));
         const archivedForCwd = await Promise.all(archivedRecords
             .filter((record) => record.cwd === cwd)
@@ -665,7 +807,7 @@ export class PiSessionService {
         }
         const unarchivedSessions = sessions
             .filter((session) => !archivedById.has(session.id))
-            .map((entry) => mergeSessionMetadata(clientSessionFromListEntry(entry), pinnedPathSet));
+            .map((entry) => mergeSessionMetadata(clientSessionFromListEntry(entry), metadata));
         const reconcilableSessionIds = this.reconcilableSessionIds(cwd, unarchivedSessions.map((session) => session.id), archivedById);
         this.workspaceActivity?.reconcileSessionActivity(cwd, reconcilableSessionIds);
         await this.publishUnreadMutations(this.unreadStore.reconcileCwd(canonicalizeStoredCwd(cwd), reconcilableSessionIds));
@@ -673,13 +815,30 @@ export class PiSessionService {
             .sort(compareArchivedRecords)
             .map((record) => clientSessionFromArchivedRecord(record, sessionsById.get(record.sessionId)))
             .filter(isDefined)
-            .map((session) => mergeSessionMetadata(session, pinnedPathSet));
+            .map((session) => mergeSessionMetadata(session, metadata));
         return [...unarchivedSessions, ...archivedSessions];
     }
     async start(cwd, options) {
+        const creationSource = options?.creationSource;
+        const initialModelPolicy = options?.initialModelPolicy;
+        if (creationSource !== undefined || initialModelPolicy !== undefined) {
+            if (creationSource === undefined)
+                throw new Error("A complete initial model policy requires a session creation source");
+            if (initialModelPolicy === undefined)
+                throw new Error("A session creation source requires a complete initial model policy");
+            return this.startSession(cwd, {
+                creationSource,
+                initializeModelPolicy: {
+                    kind: "complete-policy",
+                    policy: initialModelPolicy,
+                },
+            });
+        }
         const modelPolicy = options?.modelPolicy;
         return this.startSession(cwd, {
-            initializeModelPolicy: modelPolicy ?? true,
+            initializeModelPolicy: modelPolicy === undefined
+                ? { kind: "runtime-default" }
+                : { kind: "legacy-update", update: modelPolicy },
         });
     }
     async startSession(cwd, options) {
@@ -695,11 +854,15 @@ export class PiSessionService {
             ...(options.creationProvenance === undefined
                 ? {}
                 : { creationProvenance: options.creationProvenance }),
+            ...(options.creationSource === undefined
+                ? {}
+                : { creationSource: options.creationSource }),
             ...(options.initializeModelPolicy === undefined
                 ? {}
                 : { initializeModelPolicy: options.initializeModelPolicy }),
         });
         const { session } = active.runtime;
+        const creationSource = validSessionCreationSource(session.sessionManager);
         const created = {
             id: session.sessionId,
             path: session.sessionFile ?? "",
@@ -714,6 +877,7 @@ export class PiSessionService {
             ...(options.parentSession === undefined
                 ? {}
                 : { parentSessionPath: options.parentSession }),
+            ...(creationSource === undefined ? {} : { creationSource }),
         };
         // Broadcast so other clients (and the spawning agent's UI) can add the new
         // session to their list without a manual reload.
@@ -1199,6 +1363,9 @@ export class PiSessionService {
             session: this.statusFromSession(session),
         };
     }
+    async rememberCurrentModelPolicy(ref) {
+        return this.rememberCurrentModelPolicyCommand.remember(ref);
+    }
     /**
      * The only interface that changes a session's Exact/Tiered policy. Applies one
      * complete transition atomically and publishes a single confirmed status; a
@@ -1688,173 +1855,181 @@ export class PiSessionService {
         });
     }
     async archive(ref) {
-        const session = await this.getOrOpen(ref);
-        if (this.hasActiveWork(session))
-            throw new Error("Stop current session activity before archiving");
-        await this.runTreeExclusiveOperation([{ sessionId: session.sessionId, session }], "Stop current session activity before archiving", async () => {
-            const archiveInput = await this.archiveInputForSession(session);
-            await this.closeActive(session.sessionId, {
-                kind: "clear",
-                reason: "archive",
+        await this.runSessionOrderMutation(async () => {
+            const session = await this.getOrOpen(ref);
+            if (this.hasActiveWork(session))
+                throw new Error("Stop current session activity before archiving");
+            await this.runTreeExclusiveOperation([{ sessionId: session.sessionId, session }], "Stop current session activity before archiving", async () => {
+                const archiveInput = await this.archiveInputForSession(session);
+                await this.closeActive(session.sessionId, {
+                    kind: "clear",
+                    reason: "archive",
+                });
+                await this.archiveStore.archive(archiveInput);
+                await this.forgetUnreadSessions([archiveInput]);
             });
-            await this.archiveStore.archive(archiveInput);
-            await this.forgetUnreadSessions([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 unreadArchivedIdentities = [];
-        const planItems = [];
-        for (const ref of uniqueRefs) {
-            const archived = findArchivedRecordForBulkRef(archivedRecords, ref);
-            if (archived !== undefined) {
-                this.publishNotificationMutations(this.notificationStore.clearSession(archived.sessionId, "archive"));
-                alreadyArchivedSessionIds.push(archived.sessionId);
-                unreadArchivedIdentities.push(archived);
-                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) });
+        return await this.runSessionOrderMutation(async () => {
+            const uniqueRefs = uniqueBulkSessionRefs(refs);
+            const [archivedRecords, sessionContext] = await Promise.all([
+                this.archiveStore.list(),
+                this.bulkSessionLookupContext(uniqueRefs),
+            ]);
+            const failures = [];
+            const alreadyArchivedSessionIds = [];
+            const unreadArchivedIdentities = [];
+            const planItems = [];
+            for (const ref of uniqueRefs) {
+                const archived = findArchivedRecordForBulkRef(archivedRecords, ref);
+                if (archived !== undefined) {
+                    this.publishNotificationMutations(this.notificationStore.clearSession(archived.sessionId, "archive"));
+                    alreadyArchivedSessionIds.push(archived.sessionId);
+                    unreadArchivedIdentities.push(archived);
+                    continue;
                 }
-                else if (active !== undefined) {
-                    planItems.push({
-                        input: archiveInputFromActiveSession(active.runtime.session),
+                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;
                 }
-                else {
-                    failures.push({ sessionId: ref.id, error: "Session not found" });
-                }
-            }
-            catch (error) {
-                failures.push({
-                    sessionId: resolvedSessionId,
-                    error: errorMessage(error),
-                });
-            }
-        }
-        const readyPlanItems = [];
-        for (const item of planItems) {
-            const active = this.activeForLookup({
-                id: item.input.sessionId,
-                cwd: item.input.cwd,
-            });
-            if (active !== undefined && this.hasActiveWork(active.runtime.session)) {
-                failures.push({
-                    sessionId: item.input.sessionId,
-                    error: "Stop current session activity before archiving",
-                });
-                continue;
-            }
-            readyPlanItems.push(active === undefined ? item : { ...item, active });
-        }
-        const readyInputs = [];
-        const archivedSessionIds = [...alreadyArchivedSessionIds];
-        await this.runTreeExclusiveOperation(readyPlanItems.map(({ input, active }) => ({
-            sessionId: input.sessionId,
-            ...(active === undefined
-                ? {}
-                : { session: active.runtime.session, runtime: active.runtime }),
-        })), "Stop current session activity before archiving", async () => {
-            for (const item of readyPlanItems) {
                 try {
-                    await this.closeActive(item.input.sessionId, {
-                        kind: "clear",
-                        reason: "archive",
-                    });
-                    readyInputs.push(item.input);
+                    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: item.input.sessionId,
+                        sessionId: resolvedSessionId,
                         error: errorMessage(error),
                     });
                 }
             }
-            try {
-                const archived = await this.archiveStoreArchiveMany(readyInputs);
-                archivedSessionIds.push(...archived.map((record) => record.sessionId));
-                unreadArchivedIdentities.push(...archived);
-            }
-            catch (error) {
-                for (const input of readyInputs)
+            const readyPlanItems = [];
+            for (const item of planItems) {
+                const active = this.activeForLookup({
+                    id: item.input.sessionId,
+                    cwd: item.input.cwd,
+                });
+                if (active !== undefined && this.hasActiveWork(active.runtime.session)) {
                     failures.push({
-                        sessionId: input.sessionId,
-                        error: errorMessage(error),
+                        sessionId: item.input.sessionId,
+                        error: "Stop current session activity before archiving",
                     });
+                    continue;
+                }
+                readyPlanItems.push(active === undefined ? item : { ...item, active });
             }
+            const readyInputs = [];
+            const archivedSessionIds = [...alreadyArchivedSessionIds];
+            await this.runTreeExclusiveOperation(readyPlanItems.map(({ input, active }) => ({
+                sessionId: input.sessionId,
+                ...(active === undefined
+                    ? {}
+                    : { session: active.runtime.session, runtime: active.runtime }),
+            })), "Stop current session activity before archiving", async () => {
+                for (const item of readyPlanItems) {
+                    try {
+                        await this.closeActive(item.input.sessionId, {
+                            kind: "clear",
+                            reason: "archive",
+                        });
+                        readyInputs.push(item.input);
+                    }
+                    catch (error) {
+                        failures.push({
+                            sessionId: item.input.sessionId,
+                            error: errorMessage(error),
+                        });
+                    }
+                }
+                try {
+                    const archived = await this.archiveStoreArchiveMany(readyInputs);
+                    archivedSessionIds.push(...archived.map((record) => record.sessionId));
+                    unreadArchivedIdentities.push(...archived);
+                }
+                catch (error) {
+                    for (const input of readyInputs)
+                        failures.push({
+                            sessionId: input.sessionId,
+                            error: errorMessage(error),
+                        });
+                }
+            });
+            await this.forgetUnreadSessions(unreadArchivedIdentities);
+            return {
+                archived: true,
+                archivedSessionIds: uniqueStrings(archivedSessionIds),
+                failures,
+                generatedAt: new Date().toISOString(),
+            };
         });
-        await this.forgetUnreadSessions(unreadArchivedIdentities);
-        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());
-        const root = findArchiveCandidateByIdOrPrefix(catalog, session.sessionId) ??
-            archiveCandidateFromActiveSession(session, false);
-        const plan = planSessionArchiveTree(root, catalog);
-        const busy = plan.targets
-            .map((target) => target.activeSession)
-            .find((target) => target !== undefined && this.hasActiveWork(target));
-        if (busy !== undefined)
-            throw new Error(`Stop current session activity before archiving ${sessionDisplayName(busy)}`);
-        const archiveInputs = plan.unarchivedTargets.map((target) => archiveInputFromCandidate(target));
-        await this.runTreeExclusiveOperation(plan.unarchivedTargets.map((target) => ({
-            sessionId: target.id,
-            ...(target.activeSession === undefined
-                ? {}
-                : { session: target.activeSession }),
-        })), `Stop current session activity before archiving ${sessionDisplayName(session)}`, async () => {
-            for (const target of plan.targets) {
-                if (target.archived)
-                    this.publishNotificationMutations(this.notificationStore.clearSession(target.id, "archive"));
-            }
-            for (const input of archiveInputs)
-                await this.closeActive(input.sessionId, {
-                    kind: "clear",
-                    reason: "archive",
-                });
-            await this.archiveStoreArchiveMany(archiveInputs);
+        return await this.runSessionOrderMutation(async () => {
+            const session = await this.getOrOpen(ref);
+            const catalog = await this.workspaceArchiveCandidates(session.sessionManager.getCwd());
+            const root = findArchiveCandidateByIdOrPrefix(catalog, session.sessionId) ??
+                archiveCandidateFromActiveSession(session, false);
+            const plan = planSessionArchiveTree(root, catalog);
+            const busy = plan.targets
+                .map((target) => target.activeSession)
+                .find((target) => target !== undefined && this.hasActiveWork(target));
+            if (busy !== undefined)
+                throw new Error(`Stop current session activity before archiving ${sessionDisplayName(busy)}`);
+            const archiveInputs = plan.unarchivedTargets.map((target) => archiveInputFromCandidate(target));
+            await this.runTreeExclusiveOperation(plan.unarchivedTargets.map((target) => ({
+                sessionId: target.id,
+                ...(target.activeSession === undefined
+                    ? {}
+                    : { session: target.activeSession }),
+            })), `Stop current session activity before archiving ${sessionDisplayName(session)}`, async () => {
+                for (const target of plan.targets) {
+                    if (target.archived)
+                        this.publishNotificationMutations(this.notificationStore.clearSession(target.id, "archive"));
+                }
+                for (const input of archiveInputs)
+                    await this.closeActive(input.sessionId, {
+                        kind: "clear",
+                        reason: "archive",
+                    });
+                await this.archiveStoreArchiveMany(archiveInputs);
+            });
+            await this.forgetUnreadSessions(plan.targets.map((target) => ({ sessionId: target.id, cwd: target.cwd })));
+            return {
+                archived: true,
+                sessionIds: archiveInputs.map((input) => input.sessionId),
+                archivedCount: archiveInputs.length,
+                skippedAlreadyArchivedCount: plan.skippedAlreadyArchivedCount,
+            };
         });
-        await this.forgetUnreadSessions(plan.targets.map((target) => ({ sessionId: target.id, cwd: target.cwd })));
-        return {
-            archived: true,
-            sessionIds: archiveInputs.map((input) => input.sessionId),
-            archivedCount: archiveInputs.length,
-            skippedAlreadyArchivedCount: plan.skippedAlreadyArchivedCount,
-        };
     }
     async restore(ref) {
-        const archived = await this.getArchived(ref);
-        if (archived === undefined)
-            throw new Error("Session not found");
-        await this.closeActive(archived.sessionId, {
-            kind: "clear",
-            reason: "restore",
+        await this.runSessionOrderMutation(async () => {
+            const archived = await this.getArchived(ref);
+            if (archived === undefined)
+                throw new Error("Session not found");
+            await this.closeActive(archived.sessionId, {
+                kind: "clear",
+                reason: "restore",
+            });
+            await this.archiveStore.restore(archived.sessionId);
+            await this.forgetUnreadSessions([archived]);
         });
-        await this.archiveStore.restore(archived.sessionId);
-        await this.forgetUnreadSessions([archived]);
     }
     async deleteArchived(ref) {
         const record = await this.getArchived(ref);
@@ -1978,35 +2153,43 @@ export class PiSessionService {
         this.publishStatus(reopenedSession);
     }
     async detachParent(ref) {
-        const session = await this.getOrOpen(ref);
-        const sessionFile = session.sessionFile;
-        if (sessionFile === undefined || sessionFile === "")
-            throw new Error("Session is not persisted");
-        await clearParentSession(sessionFile);
-        clearParentSessionHeader(session.sessionManager);
-        this.unregisterSubsession(session.sessionId);
-        await this.forgetUnreadSessions([
-            { sessionId: session.sessionId, cwd: session.sessionManager.getCwd() },
-        ]);
+        await this.runSessionOrderMutation(async () => {
+            const session = await this.getOrOpen(ref);
+            const sessionFile = session.sessionFile;
+            if (sessionFile === undefined || sessionFile === "")
+                throw new Error("Session is not persisted");
+            await this.clearParentSessionFile(sessionFile);
+            clearParentSessionHeader(session.sessionManager);
+            await this.metadataStore.clearOrder(sessionFile);
+            this.unregisterSubsession(session.sessionId);
+            await this.forgetUnreadSessions([
+                { sessionId: session.sessionId, cwd: session.sessionManager.getCwd() },
+            ]);
+        });
     }
     async pin(ref) {
-        const session = await this.getOrOpen(ref);
-        const sessionFile = session.sessionFile;
-        if (sessionFile === undefined || sessionFile === "")
-            throw new Error("Session is not persisted");
-        await this.metadataStore.pin(sessionFile);
-        return this.sessionInfoFromActive(session, { pinned: true });
+        return await this.runSessionOrderMutation(async () => {
+            const session = await this.getOrOpen(ref);
+            const sessionFile = session.sessionFile;
+            if (sessionFile === undefined || sessionFile === "")
+                throw new Error("Session is not persisted");
+            await this.metadataStore.pin(sessionFile);
+            return this.sessionInfoFromActive(session, { pinned: true });
+        });
     }
     async unpin(ref) {
-        const session = await this.getOrOpen(ref);
-        const sessionFile = session.sessionFile;
-        if (sessionFile === undefined || sessionFile === "")
-            throw new Error("Session is not persisted");
-        await this.metadataStore.unpin(sessionFile);
-        return this.sessionInfoFromActive(session, { pinned: false });
+        return await this.runSessionOrderMutation(async () => {
+            const session = await this.getOrOpen(ref);
+            const sessionFile = session.sessionFile;
+            if (sessionFile === undefined || sessionFile === "")
+                throw new Error("Session is not persisted");
+            await this.metadataStore.unpin(sessionFile);
+            return this.sessionInfoFromActive(session, { pinned: false });
+        });
     }
     sessionInfoFromActive(session, overrides) {
         const parentSessionPath = session.sessionManager.getHeader?.()?.parentSession;
+        const creationSource = validSessionCreationSource(session.sessionManager);
         return {
             id: session.sessionId,
             path: session.sessionFile ?? "",
@@ -2020,6 +2203,7 @@ export class PiSessionService {
                 ? {}
                 : { name: session.sessionName }),
             ...(parentSessionPath === undefined ? {} : { parentSessionPath }),
+            ...(creationSource === undefined ? {} : { creationSource }),
             ...overrides,
         };
     }
@@ -2459,6 +2643,7 @@ export class PiSessionService {
             : notificationGeneration === undefined
                 ? "registered"
                 : "external";
+        let completeInitialization;
         if (notificationOwnership === "registered") {
             const notificationIdentity = notificationIdentityForSession(runtime.session);
             const existingCandidate = this.notificationStore.beginReplacementForSession(notificationIdentity.sessionId, notificationIdentity.cwd);
@@ -2483,7 +2668,6 @@ export class PiSessionService {
                 await this.recoverSubsessionTrackingForOpenedSession(runtime.session);
             }
             await this.bindSessionExtensions(runtime.session, notificationGeneration);
-            this.bindRuntime(active);
             runtime.setRebindSession(async (session) => {
                 const priorGeneration = notificationGeneration;
                 let candidateGeneration;
@@ -2512,10 +2696,20 @@ export class PiSessionService {
                     throw error;
                 }
             });
-            this.active.set(runtime.session.sessionId, active);
-            if (options.initializeModelPolicy !== undefined) {
+            if (options.initializeModelPolicy?.kind === "complete-policy") {
+                if (options.creationSource === undefined) {
+                    throw new Error("A complete initial model policy requires a session creation source");
+                }
+                completeInitialization =
+                    await this.initializeCompleteSessionModelPolicy(runtime.session, options.initializeModelPolicy.policy, options.creationSource);
+            }
+            else if (options.initializeModelPolicy !== undefined) {
                 await this.initializeSessionModelPolicy(runtime.session, options.initializeModelPolicy);
             }
+            if (options.creationSource !== undefined &&
+                options.initializeModelPolicy?.kind !== "complete-policy")
+                throw new Error("A session creation source requires a complete initial model policy");
+            this.bindRuntime(active);
             if (notificationOwnership === "replacement" &&
                 notificationGeneration !== undefined) {
                 this.publishNotificationMutations(this.notificationStore.commitReplacement(notificationGeneration));
@@ -2548,13 +2742,28 @@ export class PiSessionService {
             if (removedActive) {
                 this.workspaceActivity?.removeSession(runtime.session.sessionId, runtime.session.sessionManager.getCwd());
             }
+            let failure = error;
+            if (completeInitialization !== undefined) {
+                const rollbackFailures = await this.rollbackCompleteSessionInitialization(runtime.session, completeInitialization);
+                failure = completeInitializationFailure(error, rollbackFailures);
+            }
+            const teardownFailures = [];
             try {
                 await runtime.session.abort();
             }
-            finally {
+            catch (abortError) {
+                teardownFailures.push(normalizeError(abortError));
+            }
+            try {
                 await runtime.dispose();
             }
-            throw error;
+            catch (disposeError) {
+                teardownFailures.push(normalizeError(disposeError));
+            }
+            if (teardownFailures.length > 0) {
+                failure = sessionInitializationCleanupFailure(failure, teardownFailures, completeInitialization !== undefined);
+            }
+            throw failure;
         }
     }
     async bindSessionExtensions(session, generation) {
@@ -2885,12 +3094,22 @@ export class PiSessionService {
         const model = session.model;
         if (model === undefined)
             return;
-        void generateShortSessionName(session.agent.streamFunction, model, firstMessage)
+        void runWithUtilityModelFallback(this.utilityModelResolver, "lightweight", { model, thinkingLevel: "minimal" }, (attempt) => generateShortSessionName(session.agent.streamFunction, attempt.model, firstMessage, attempt.thinkingLevel), (attempt, error) => {
+            this.logger.info({
+                provider: attempt.model.provider,
+                modelId: attempt.model.id,
+                thinkingLevel: attempt.thinkingLevel,
+                error: error instanceof Error ? error.message : String(error),
+            }, "utility title model failed");
+        })
             .then((name) => {
             this.applyGeneratedSessionName(session, name ?? fallbackSessionName(firstMessage));
         })
-            .catch(() => {
-            this.applyGeneratedSessionName(session, fallbackSessionName(firstMessage));
+            .catch((error) => {
+            this.logger.info({
+                sessionId: session.sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            }, "failed to apply generated session name");
         });
     }
     applyGeneratedSessionName(session, name) {
@@ -3241,8 +3460,57 @@ export class PiSessionService {
         };
     }
     policyEntries(session) {
-        return (session.sessionManager.getEntries?.() ??
-            session.sessionManager.getBranch());
+        return session.sessionManager.getBranch();
+    }
+    async confirmedPolicySnapshot(ref) {
+        const session = await this.getOrOpen(ref);
+        const sessionFile = session.sessionManager.getSessionFile();
+        const persisted = sessionFileExists(sessionFile);
+        const manager = persisted
+            ? this.sessionManager.open(sessionFile)
+            : session.sessionManager;
+        const activeEntries = manager.getBranch();
+        // Creation provenance belongs to the durable root file, even when its
+        // original entry is not on the currently selected conversation branch.
+        const creationSourceEntries = manager.getEntries?.() ?? activeEntries;
+        const creationSource = inspectSessionCreationSource(creationSourceEntries);
+        return {
+            cwd: canonicalizeStoredCwd(manager.getCwd()),
+            creationSource,
+            persisted,
+            rootEligibility: this.sessionCreationRootEligibility(manager, creationSource),
+            modelPolicy: inspectSessionModelPolicy(activeEntries, this.exactSelectionFromSession(session)),
+            transitionInFlight: this.isModelPolicyMutationActive(session),
+        };
+    }
+    sessionCreationRootEligibility(manager, source) {
+        const sessionFile = manager.getSessionFile();
+        const header = manager.getHeader?.();
+        if (sessionFile === undefined || sessionFile === "") {
+            return {
+                kind: "ineligible",
+                reason: "the session has no durable transcript path",
+            };
+        }
+        if (header === undefined || header === null || typeof header.id !== "string") {
+            return {
+                kind: "ineligible",
+                reason: "the session header does not identify its root",
+            };
+        }
+        if (header.id !== manager.getSessionId()) {
+            return {
+                kind: "ineligible",
+                reason: "the session header id does not match the opened session",
+            };
+        }
+        return inspectSessionCreationRootEligibility(source, {
+            sessionId: header.id,
+            sessionFile,
+            ...(header.parentSession === undefined
+                ? {}
+                : { parentSession: header.parentSession }),
+        });
     }
     inspectAndCacheSessionModelPolicy(session) {
         const inspection = inspectSessionModelPolicy(this.policyEntries(session), this.exactSelectionFromSession(session));
@@ -3260,26 +3528,113 @@ export class PiSessionService {
         return (this.modelPolicyRuntimeBlocks.get(session.sessionId) ??
             this.modelPolicyEntryReasons.get(session));
     }
-    /**
-     * Root-session policy initialization. `true` records the runtime's own tuple;
-     * an update applies the requested transition. Both complete before the caller
-     * of `start()` sees the session, so no prompt can precede the policy.
-     */
+    /** Root-session policy initialization, completed before the root is visible. */
     async initializeSessionModelPolicy(session, initializer) {
         const current = {
             mode: "exact",
             exact: this.exactSelectionFromSession(session),
         };
-        if (initializer === true) {
+        if (initializer.kind === "runtime-default") {
             this.appendSessionModelPolicy(session, current);
             this.inspectAndCacheSessionModelPolicy(session);
             return;
         }
-        // Root creation reports failure through its own abort/dispose cleanup rather
-        // than publishing a failed transition for a session no client has seen.
-        await this.applySessionModelPolicy(session, current, initializer, {
-            action: "initialize the session model policy",
+        if (initializer.kind === "legacy-update") {
+            // Root creation reports failure through its own abort/dispose cleanup
+            // rather than publishing a transition for a session no client has seen.
+            await this.applySessionModelPolicy(session, current, initializer.update, {
+                action: "initialize the session model policy",
+            });
+            return;
+        }
+        throw new Error("A complete initial model policy requires durable plus-root initialization");
+    }
+    async initializeCompleteSessionModelPolicy(session, policy, source) {
+        const plan = planSessionModelPolicyInitialization(policy, (tier) => {
+            const resolved = this.modelTierRegistry.resolve(tier);
+            return {
+                model: { provider: resolved.model.provider, id: resolved.model.id },
+                thinkingLevel: resolved.thinkingLevel,
+            };
         });
+        // Only the active target is checked against the current runtime catalog.
+        // The inactive branch remains remembered even when it is unavailable.
+        const target = await this.resolveAvailableExactSelection(session, plan.target);
+        const settings = modelPolicySettingsPersistence(session.settingsManager);
+        await settleModelPolicySettings(settings, "before complete session initialization");
+        this.assertModelPolicyMutationIdle(session, "initialize the session model policy");
+        const initialization = {
+            previousSelection: this.exactSelectionFromSession(session),
+            previousSettings: captureModelPolicySettings(settings),
+        };
+        try {
+            await this.runSessionModelPolicyMutation(session, "initialize the session model policy", async () => {
+                await this.applyExactSelection(session, target);
+                // Pi queues global default writes behind its setters and swallows their
+                // storage failures, so prove durability before any transcript record
+                // exists: everything after this point must be reversible.
+                await settleModelPolicySettings(settings, "while applying initial model defaults");
+                this.appendSessionModelPolicy(session, plan.policy);
+                this.verifyPersistedSessionModelPolicy(session, plan.policy);
+                this.appendSessionCreationSource(session, source);
+                await this.commitAndVerifyInitialSessionEntries(session, plan.policy);
+            });
+            this.inspectAndCacheSessionModelPolicy(session);
+            return initialization;
+        }
+        catch (error) {
+            const rollbackFailures = await this.rollbackCompleteSessionInitialization(session, initialization);
+            throw completeInitializationFailure(error, rollbackFailures);
+        }
+    }
+    async rollbackCompleteSessionInitialization(session, initialization) {
+        const failures = [];
+        if (!(await this.restoreExactSelection(session, initialization.previousSelection))) {
+            failures.push(new Error("the previous runtime model and thinking pair was not restored"));
+        }
+        try {
+            await restoreModelPolicySettings(modelPolicySettingsPersistence(session.settingsManager), initialization.previousSettings);
+        }
+        catch (error) {
+            failures.push(normalizeError(error));
+        }
+        try {
+            await this.sessionManager.discardInitialEntries?.(session.sessionManager);
+        }
+        catch (error) {
+            failures.push(normalizeError(error));
+        }
+        try {
+            this.inspectAndCacheSessionModelPolicy(session);
+        }
+        catch (error) {
+            failures.push(normalizeError(error));
+        }
+        return failures;
+    }
+    async commitAndVerifyInitialSessionEntries(session, expectedPolicy) {
+        if (this.sessionManager.commitInitialEntries === undefined) {
+            throw new Error("Cannot durably commit the complete initial session policy and provenance");
+        }
+        await this.sessionManager.commitInitialEntries(session.sessionManager);
+        const sessionFile = session.sessionManager.getSessionFile();
+        if (!sessionFileExists(sessionFile))
+            throw new Error("Cannot verify the durable initial session transcript");
+        const reopened = this.sessionManager.open(sessionFile);
+        const entries = reopened.getEntries?.() ?? reopened.getBranch();
+        const policyInspection = inspectSessionModelPolicy(entries, expectedPolicy.exact);
+        if (policyInspection.kind !== "persisted" ||
+            !sameSessionModelPolicy(policyInspection.policy, expectedPolicy)) {
+            throw new Error("Cannot verify the complete initial session model policy after reopen");
+        }
+        const sourceInspection = inspectSessionCreationSource(entries);
+        if (sourceInspection.kind !== "valid") {
+            throw new Error("Cannot verify the session creation source after reopen");
+        }
+        const rootEligibility = this.sessionCreationRootEligibility(reopened, sourceInspection);
+        if (rootEligibility.kind !== "eligible") {
+            throw new Error(`Cannot verify the durable plus-session root origin: ${rootEligibility.reason}`);
+        }
     }
     /**
      * The single policy transition path. Validates the complete target before any
@@ -3539,6 +3894,35 @@ export class PiSessionService {
         }
         session.sessionManager.appendCustomEntry(SESSION_MODEL_POLICY_CUSTOM_TYPE, serializeSessionModelPolicy(policy));
     }
+    verifyPersistedSessionModelPolicy(session, expected) {
+        const inspection = this.inspectAndCacheSessionModelPolicy(session);
+        if (inspection.kind !== "persisted" ||
+            !sameSessionModelPolicy(inspection.policy, expected)) {
+            throw new Error("Cannot verify the complete initial session model policy");
+        }
+    }
+    appendSessionCreationSource(session, source) {
+        if (session.sessionManager.appendCustomEntry === undefined) {
+            throw new Error("Cannot persist the session creation source: session persistence is unavailable");
+        }
+        const sessionFile = session.sessionManager.getSessionFile();
+        if (sessionFile === undefined || sessionFile === "") {
+            throw new Error("Cannot persist the session creation source without a session file");
+        }
+        if (session.sessionManager.getSessionId() !== session.sessionId) {
+            throw new Error("Cannot persist the session creation source for a mismatched session id");
+        }
+        session.sessionManager.appendCustomEntry(SESSION_CREATION_SOURCE_CUSTOM_TYPE, serializeSessionCreationSource(source, {
+            sessionId: session.sessionId,
+            sessionFile,
+        }));
+        const inspection = inspectSessionCreationSource(this.policyEntries(session));
+        const rootEligibility = this.sessionCreationRootEligibility(session.sessionManager, inspection);
+        if (inspection.kind !== "valid" ||
+            rootEligibility.kind !== "eligible") {
+            throw new Error("Cannot verify the session creation source");
+        }
+    }
     modelPolicyStatusFromSession(session) {
         const inspection = this.modelPolicyInspections.get(session);
         if (inspection === undefined)
@@ -3668,6 +4052,19 @@ function findSessionByIdOrPrefix(sessions, sessionId) {
 function uniqueStrings(values) {
     return [...new Set(values)];
 }
+/**
+ * Reconcile duplicate catalog entries by canonical CWD + id, matching the
+ * last-writer-wins convention other catalog reconciliation helpers use. The
+ * reorder loader can read the same session more than once when overlapping
+ * catalog CWDs are requested (e.g. a cross-workspace children scope).
+ */
+function uniqueSessionsByIdentity(sessions) {
+    const byIdentity = new Map();
+    for (const session of sessions) {
+        byIdentity.set(JSON.stringify([canonicalizeStoredCwd(session.cwd), session.id]), session);
+    }
+    return [...byIdentity.values()];
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -3704,6 +4101,9 @@ function clientSessionFromListEntry(session) {
         ...(session.parentSessionPath === undefined
             ? {}
             : { parentSessionPath: session.parentSessionPath }),
+        ...(session.creationSource === undefined
+            ? {}
+            : { creationSource: session.creationSource }),
     };
 }
 function archiveInputFromListEntry(session) {
@@ -3719,6 +4119,9 @@ function archiveInputFromListEntry(session) {
         ...(session.parentSessionPath === undefined
             ? {}
             : { parentSessionPath: session.parentSessionPath }),
+        ...(session.creationSource === undefined
+            ? {}
+            : { creationSource: session.creationSource }),
     };
 }
 function archiveInputFromActiveSession(session) {
@@ -3726,6 +4129,7 @@ function archiveInputFromActiveSession(session) {
     if (sessionFile === undefined || sessionFile === "")
         throw new Error("Session is not persisted");
     const parentSessionPath = session.sessionManager.getHeader?.()?.parentSession;
+    const creationSource = validSessionCreationSource(session.sessionManager);
     return {
         sessionId: session.sessionId,
         cwd: session.sessionManager.getCwd(),
@@ -3736,6 +4140,7 @@ function archiveInputFromActiveSession(session) {
         firstMessage: "",
         ...(session.sessionName === undefined ? {} : { name: session.sessionName }),
         ...(parentSessionPath === undefined ? {} : { parentSessionPath }),
+        ...(creationSource === undefined ? {} : { creationSource }),
     };
 }
 function archiveCandidateFromListEntry(session) {
@@ -3808,6 +4213,7 @@ function clientSessionFromArchivedRecord(record, fallback) {
         return undefined;
     const name = record.name ?? fallback?.name;
     const parentSessionPath = record.parentSessionPath ?? fallback?.parentSessionPath;
+    const creationSource = record.creationSource ?? fallback?.creationSource;
     return {
         id: record.sessionId,
         path,
@@ -3818,10 +4224,22 @@ function clientSessionFromArchivedRecord(record, fallback) {
         messageCount,
         firstMessage,
         ...(parentSessionPath === undefined ? {} : { parentSessionPath }),
+        ...(creationSource === undefined ? {} : { creationSource }),
         archived: true,
         archivedAt: record.archivedAt,
     };
 }
+function validSessionCreationSource(manager) {
+    const inspection = inspectSessionCreationSource(manager.getEntries?.() ?? manager.getBranch());
+    return inspection.kind === "valid" ? inspection.source : undefined;
+}
+function sameSessionModelPolicy(left, right) {
+    return (left.mode === right.mode &&
+        left.tier === right.tier &&
+        left.exact.model.provider === right.exact.model.provider &&
+        left.exact.model.id === right.exact.model.id &&
+        left.exact.thinkingLevel === right.exact.thinkingLevel);
+}
 function addSessionName(names, name) {
     const trimmed = name?.replace(/\s+/g, " ").trim();
     if (trimmed !== undefined && trimmed !== "")
@@ -3837,10 +4255,28 @@ function archivedTimestamp(record) {
 function isDefined(value) {
     return value !== undefined;
 }
-function mergeSessionMetadata(session, pinnedPaths) {
-    if (!pinnedPaths.has(session.path))
-        return session;
-    return { ...session, pinned: true };
+function mergeSessionMetadata(session, metadata) {
+    const entry = metadata[session.path];
+    const pinned = entry?.pinned === true;
+    const scope = session.parentSessionPath === undefined
+        ? { kind: "root", cwd: canonicalizeStoredCwd(session.cwd) }
+        : { kind: "children", parentSessionPath: session.parentSessionPath };
+    const order = entry?.order;
+    const manualOrder = session.archived !== true
+        && order?.pinned === pinned
+        && sessionReorderScopesEqual(order.scope, scope)
+        ? order.position
+        : undefined;
+    return {
+        ...session,
+        ...(pinned ? { pinned: true } : {}),
+        ...(manualOrder === undefined ? {} : { manualOrder }),
+    };
+}
+function sessionReorderScopesEqual(a, b) {
+    if (a.kind === "root")
+        return b.kind === "root" && a.cwd === b.cwd;
+    return b.kind === "children" && a.parentSessionPath === b.parentSessionPath;
 }
 /**
  * Resolve the delegation capability from server-owned, persisted session