@duckmind/dm-darwin-x64 0.66.4 → 0.66.6

package/extensions/dm-lens/index.js

@@ -1,6 +1,6 @@
 import"./clients/console-guard-install.js";
 import { BoundedSet } from "./clients/bounded-cache.js";
-import { bounded } from "./clients/deadline-utils.js";
+import { bounded, withDeadline } from "./clients/deadline-utils.js";
 import { HOOK_WALL_BUDGET_MS } from "./clients/hook-budgets.js";
 import {
   closeModuleLoadConsoleWindow,
@@ -31,6 +31,7 @@ import {
   suppressesUserNotify,
   supportsTuiWidget
 } from "./clients/extension-mode.js";
+import { randomUUID } from "node:crypto";
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
@@ -48,11 +49,8 @@ import {
 import { CacheManager } from "./clients/cache-manager.js";
 import { resolveSkillPaths } from "./clients/skills-resolver.js";
 import {
-  clearWidgetState,
-  exportWidgetState,
   getFailedLspServerIds,
   getSessionLanguages,
-  importWidgetState,
   reconcileCascadeNeighborLspErrors,
   renderWidget,
   scheduleStaleReconcile,
@@ -60,7 +58,29 @@ import {
   wireWidgetDispositionSubscriber
 } from "./clients/widget-state.js";
 import { selectLspStatus } from "./clients/lsp-status.js";
-import { registerMutationBridge } from "./clients/mutation-bridge.js";
+import {
+  branchToolResultIds,
+  logReadGuardBranchMove,
+  READ_GUARD_CELL,
+  readSessionHeaderId
+} from "./clients/read-guard-branch.js";
+import {
+  adoptHandoff,
+  beginScope,
+  discardHandoff,
+  forwardHandoff,
+  logScopeTransition,
+  retireScope,
+  reserveSessionStart,
+  scopeCell,
+  startKey,
+  stashHandoff,
+  successorStartKey
+} from "./clients/session-scope.js";
+import { sanitizeCorrelationId } from "./clients/read-guard-logger.js";
+import {
+  registerMutationBridge
+} from "./clients/mutation-bridge.js";
 import {
   OBSERVED_TRACKED_MAX_FILES,
   refreshObservedMutationLedger,
@@ -76,13 +96,21 @@ import { isEditClassToolResult } from "./clients/bash-file-access.js";
 import { resolveLanguageRootForFile } from "./clients/language-profile.js";
 import { countFileLines } from "./clients/read-guard-tool-lines.js";
 import { registerReadBridge } from "./clients/read-bridge.js";
-import { normalizeFilePath } from "./clients/path-utils.js";
-import { isRecordableProjectPath } from "./clients/file-utils.js";
 import {
-  dropStaleFiles,
+  recordIOEntry,
+  registerIOBridge
+} from "./clients/io-bridge.js";
+import {
+  rebindableProcessBridgeDeps
+} from "./clients/process-bridge.js";
+import { isExternalOrVendorFile } from "./clients/path-utils.js";
+import {
+  isPathIgnoredByProject,
+  isRecordableProjectPath
+} from "./clients/file-utils.js";
+import {
   loadSessionState,
-  saveSessionState,
-  sessionStartMode
+  persistScope
 } from "./clients/session-state-store.js";
 import { getDiagnosticTracker } from "./clients/diagnostic-tracker.js";
 import {
@@ -105,6 +133,7 @@ import {
   resolveLensToolEnabled
 } from "./clients/tool-config.js";
 import { recordDegradationOnce } from "./clients/degradation-ledger.js";
+import { flushAllNdjsonWriters } from "./clients/ndjson-logger.js";
 import { wrapToolsForCompactLine } from "./clients/tool-render.js";
 import {
   finalizeToolResultWithDelivery,
@@ -117,6 +146,7 @@ import { wireDiagnosticsBusEmitterGetter } from "./clients/diagnostics-publish.j
 import { wireDispositionBusEmitterGetter } from "./clients/disposition-publish.js";
 import { wireFormatEventsBusEmitterGetter } from "./clients/format-events-publish.js";
 import { emitBusEventRollupAtSessionEnd } from "./clients/bus-events-logger.js";
+import { emitFenceRollupAtSessionEnd } from "./clients/generation-guard.js";
 import {
   emitVerifiedPathAttributionRollup,
   resetVerifiedPathAttributionGuessCount
@@ -133,7 +163,7 @@ import {
 import { registerCascadeTierReconcileTask } from "./clients/lsp/cascade-tier.js";
 import { buildResolvedFoundCascadeRun } from "./clients/cascade-format.js";
 import { initLSPConfig } from "./clients/lsp/config.js";
-import { getLSPService, resetLSPService } from "./clients/lsp/index.js";
+import { getLSPService, resetLSPService } from "./clients/lsp/capabilities.js";
 import { shouldInitializeSessionRoot } from "./clients/lsp/session-roots.js";
 import { warmLspService } from "./clients/lsp-lazy.js";
 import {
@@ -196,6 +226,8 @@ import {
   decideSessionStart,
   decrementSecondarySessionCount,
   getActivePrimaryRoot,
+  namedSuccessorReason,
+  expiredSuccessorReason,
   noteSessionShutdown,
   releasePrimarySession,
   probeCtxActive
@@ -203,6 +235,7 @@ import {
 import {
   clearLastAnalyzedStateCache,
   flushDebouncedToolResults,
+  handleToolExecutionEnd,
   handleToolResult
 } from "./clients/runtime-tool-result.js";
 import { cancelLSPIdleReset, handleTurnEnd } from "./clients/runtime-turn.js";
@@ -246,9 +279,7 @@ import {
 const LOOP_BLOCK_IDENTITY = "<dm-lens>";
 import {
   isFreshSessionStart,
-  clearRememberedLazyTools,
   getRememberedLazyTools,
-  inheritRememberedLazyTools,
   planToolSet,
   recordToolSetMutation,
   rememberLazyTools,
@@ -303,6 +334,10 @@ import {
 } from "./clients/session-start-observability.js";
 import { normalizeToolDefinition } from "./clients/tool-definition.js";
 import { warmFormatters } from "./clients/formatters-lazy.js";
+import {
+  noteHostSessionManager,
+  setHostFileMutationQueueLoader
+} from "./clients/file-mutation-queue.js";
 let loadedDispatchIntegration;
 const sessionBootstrapAccess = {
   peek: () => peekBootstrapClients(),
@@ -429,12 +464,10 @@ for (const record of buildStartupTimingRecords({
 function log(_msg) {}
 const runtime = new RuntimeCoordinator;
 const cacheManager = new CacheManager;
-let _readBridgeRegistered = false;
 let _bridgeGetFlag;
-let _mutationBridgeRegistered = false;
-function getBridgeFlag(getter, bridge) {
+function getBridgeFlag(getter, bridge, name = "no-read-guard") {
   try {
-    return getter?.("no-read-guard");
+    return getter?.(name);
   } catch (err) {
     if (!isStaleExtensionCtxError(err))
       throw err;
@@ -447,7 +480,7 @@ function getBridgeFlag(getter, bridge) {
   }
 }
 let _turnSummaryEmitRegistered = false;
-let _turnSummaryEmitCtx;
+let _turnSummaryEmitCtxGetter;
 let _testRunnerDeliveryRegistered = false;
 let _nextTestRunnerDeliveryOwnerId = 0;
 const LSP_CONFIG_CWD_CAP = 128;
@@ -493,11 +526,17 @@ function cleanStaleTsBuildInfo(cwd) {
 }
 function activateExtension(hostPi) {
   const pi = withConsoleCaptureWindows(hostPi);
+  setHostFileMutationQueueLoader(() => import("@duckmind/dm-coding-agent"));
   const testRunnerDeliveryOwnerId = `activation-${++_nextTestRunnerDeliveryOwnerId}`;
   let ownEventCtx;
   let ownedSessionRole;
+  const secondaryRootHolder = `secondary:${randomUUID()}`;
+  let ownedSecondaryRoot;
+  let scope;
+  let turnStartScope;
+  let startInFlight;
   const classifyOwnedSessionEmission = (ctx, sessionId) => ownedSessionRole ?? classifyCurrentSessionEmission(ctx, sessionId);
-  const classifyOwnedSessionShutdown = (ctx, sessionId, root) => ownedSessionRole === "concurrent-secondary" ? "secondary" : ownedSessionRole === "primary" ? "primary" : noteSessionShutdown(ctx, sessionId, root);
+  const classifyOwnedSessionShutdown = (ctx, sessionId, root) => ownedSessionRole === "concurrent-secondary" ? "secondary" : ownedSessionRole === "primary" ? "primary" : noteSessionShutdown(ctx, sessionId, root, startKey(getSessionFile(ctx), getSessionManager(ctx)));
   const rememberOwnEventCtx = (ctx) => {
     if (!ctx)
       return;
@@ -599,44 +638,68 @@ function activateExtension(hostPi) {
   };
   const isToolEnabled = (name) => resolveLensToolEnabled(name, globalConfig, loadDmLensProjectConfig(runtime.projectRoot).raw, noToolFlag());
   const disabledToolNames = LENS_TOOL_NAMES.filter((name) => !isToolEnabled(name));
+  const formatDisabledToolNames = (names) => {
+    const shown = names.slice(0, 8);
+    const omitted = names.length - shown.length;
+    const suffix = omitted > 0 ? ` and ${omitted} more` : "";
+    return `${shown.join(", ")}${suffix} (${names.length} total)`;
+  };
   let lensEnabled = !getLensFlag("no-lens");
   _bridgeGetFlag = getLensFlag;
-  if (!_readBridgeRegistered) {
-    _readBridgeRegistered = true;
+  const mutationBridgeDeps = {
+    getRuntime: () => runtime,
+    getCacheManager: () => cacheManager,
+    getProjectRoot: () => runtime.projectRoot || process.cwd(),
+    getDispatchCwd: (filePath) => resolveLanguageRootForFile(filePath, runtime.projectRoot || process.cwd()),
+    countFileLines,
+    isRecordable(filePath) {
+      return isRecordableProjectPath(filePath, runtime.projectRoot);
+    },
+    shouldStampReadGuard() {
+      return !getBridgeFlag(_bridgeGetFlag, "mutation");
+    },
+    dbg
+  };
+  const ioBridgeDeps = {
+    ...mutationBridgeDeps,
+    getReadGuard: () => runtime.readGuard,
+    getTurnIndex: () => runtime.turnIndex,
+    peekWriteIndex: () => runtime.peekWriteIndex(),
+    getFlag: (name, bridge) => getBridgeFlag(_bridgeGetFlag, bridge ?? "io", name),
+    isExternalOrVendorFile: (filePath) => isExternalOrVendorFile(filePath, runtime.projectRoot),
+    isPathIgnoredByProject: (filePath) => isPathIgnoredByProject(filePath, runtime.projectRoot, false),
+    notifyExternalFileChange: (filePath, type) => getLSPService().notifyExternalFileChange(filePath, type),
+    nodeFs: { existsSync: nodeFs.existsSync, statSync: nodeFs.statSync }
+  };
+  const recordBridgeUnavailable = () => {
+    recordDegradationOnce({
+      kind: "process-bridge-unavailable",
+      subject: "primary-session-gap",
+      reason: "bridge call refused while no live primary session owns its dependencies"
+    });
+  };
+  const preSessionActivation = { role: "pre-session" };
+  const registerPrimaryBridges = (activation) => {
+    const scopedActivation = activation && typeof activation === "object" && "role" in activation && (activation.role === "primary" || activation.role === "secondary") ? activation : undefined;
+    if (scopedActivation && (scopedActivation.role !== "primary" || !scopedActivation.isLive()))
+      return;
     registerReadBridge({
-      getReadGuard: () => runtime.readGuard,
-      getTurnIndex: () => runtime.turnIndex,
-      peekWriteIndex: () => runtime.peekWriteIndex(),
+      onUnavailable: recordBridgeUnavailable,
       isRecordable(filePath) {
         if (getBridgeFlag(_bridgeGetFlag, "read"))
           return false;
         return isRecordableProjectPath(filePath, runtime.projectRoot);
-      }
-    });
-  }
-  if (!_mutationBridgeRegistered) {
-    _mutationBridgeRegistered = true;
-    registerMutationBridge({
-      getRuntime: () => runtime,
-      getCacheManager: () => cacheManager,
-      getProjectRoot: () => runtime.projectRoot || process.cwd(),
-      getDispatchCwd: (filePath) => resolveLanguageRootForFile(filePath, runtime.projectRoot || process.cwd()),
-      countFileLines,
-      isRecordable(filePath) {
-        return isRecordableProjectPath(filePath, runtime.projectRoot);
-      },
-      shouldStampReadGuard() {
-        return !getBridgeFlag(_bridgeGetFlag, "mutation");
       },
-      dbg
-    });
-  }
+      forward: (entry) => recordIOEntry(entry, ioBridgeDeps)
+    }, activation);
+    registerMutationBridge({ ...mutationBridgeDeps, onUnavailable: recordBridgeUnavailable }, activation);
+    registerIOBridge({ ...ioBridgeDeps, onUnavailable: recordBridgeUnavailable }, activation);
+  };
+  registerPrimaryBridges(preSessionActivation);
   let contextInjectionEnabled = !getLensFlag("no-lens-context");
   let lensWidgetVisible = globalConfig?.widget?.visible !== false;
   let mountedLensWidgetUi;
   let widgetMountFailureLogged = false;
-  let pendingForkSnapshot;
-  let pendingForkReadGuard;
   function mountLensWidget(ui, mode) {
     if (!supportsTuiWidget(mode)) {
       dbg(`widget mount ${modeSuppressionNote(mode)}`);
@@ -655,6 +718,7 @@ function activateExtension(hostPi) {
     }
     const setWidget = ui.setWidget;
     setWidget("dm-lens", (tui, theme) => {
+      const compactWidget = getLensFlag("lens-compact-widget") === true;
       renderInvalidator = () => tui.requestRender();
       setRenderCallback(() => {
         scheduleStaleReconcile();
@@ -663,7 +727,7 @@ function activateExtension(hostPi) {
       return {
         render: (width) => {
           scheduleStaleReconcile();
-          return renderWidget(width, theme);
+          return renderWidget(width, theme, { compact: compactWidget });
         },
         invalidate: () => {
           renderInvalidator = undefined;
@@ -716,7 +780,7 @@ function activateExtension(hostPi) {
       }
       const changed = nextVisible ? mountLensWidget(ctx.ui, mode) : unmountLensWidget(ctx.ui);
       if (!changed) {
-        notifyUi(ctx, "dm-lens widget is not supported by this pi version.", "warning");
+        notifyUi(ctx, "dm-lens widget is not supported by this DM version.", "warning");
         return;
       }
       lensWidgetVisible = nextVisible;
@@ -797,7 +861,7 @@ function activateExtension(hostPi) {
       const sessionAgeStr = sessionHrs > 0 ? `${sessionHrs}h ${sessionMins % 60}m` : `${sessionMins}m`;
       const startedAt = new Date(runtime.sessionStartedAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
       const lines = [
-        t("lens.health.title", "\uD83E\uDE7A PI-LENS HEALTH"),
+        t("lens.health.title", "\uD83E\uDE7A DM-LENS HEALTH"),
         `Session started: ${startedAt} (${sessionAgeStr} ago)`,
         "",
         t("lens.health.crashes", "Pipeline crashes (session): {count}", {
@@ -807,6 +871,17 @@ function activateExtension(hostPi) {
           count: crashEntries.length
         })
       ];
+      const effectiveTools = (await withDeadline(import("./clients/lens-engine.js").then(({ effectiveConfig }) => effectiveConfig({
+        cwd: runtime.projectRoot,
+        noTools: noToolFlag()
+      })), { ms: 5000 })).tools;
+      const enabledTools = effectiveTools.filter((tool) => tool.enabled).map((tool) => tool.name);
+      const disabledTools = effectiveTools.filter((tool) => !tool.enabled).map((tool) => tool.name);
+      lines.push("", `Tools enabled: ${enabledTools.join(", ") || "none"}`);
+      if (disabledTools.length > 0) {
+        lines.push(`Tools disabled: ${formatDisabledToolNames(disabledTools)}`);
+      }
+      lines.push("Skills: managed by pi package filters");
       const slopScoreLine = dispatchIntegration.getDispatchSlopScoreLine();
       if (crashEntries.length > 0) {
         lines.push("", t("lens.health.topCrashFiles", "Top crash files:"));
@@ -933,7 +1008,7 @@ ${degradationLines.join(`
         "not-installed": statuses.filter((s) => s.source === "not-installed")
       };
       const lines = [
-        "\uD83D\uDD27 PI-LENS TOOLS STATUS",
+        "\uD83D\uDD27 DM-LENS TOOLS STATUS",
         "",
         `Installed: ${statuses.filter((s) => s.installed).length}/${statuses.length}`
       ];
@@ -1000,17 +1075,17 @@ ${degradationLines.join(`
     }
   });
   const alwaysActiveTools = [
-    createLensDiagnosticsTool(cacheManager, () => runtime.projectRoot, undefined, () => flushDebouncedToolResults(), () => runtime.nextWriteIndex(), captureLspStatusRepaint, () => runtime, () => Boolean(getLensFlag("lens-guard"))),
+    createLensDiagnosticsTool(cacheManager, () => runtime.projectRoot, undefined, () => flushDebouncedToolResults(), () => runtime.nextWriteOrderToken(), captureLspStatusRepaint, () => runtime, () => Boolean(getLensFlag("lens-guard"))),
     createSymbolSearchTool(() => runtime.projectRoot),
     createEffectiveConfigTool(() => runtime.projectRoot, noToolFlag),
     createProjectReportTool(() => runtime.projectRoot),
     createModuleReportTool(() => runtime.projectRoot),
-    createReadSymbolTool(() => runtime.projectRoot, (filePath, symbol) => runtime.readGuard.recordSymbolRead(filePath, symbol, runtime.turnIndex, runtime.peekWriteIndex())),
-    createReadEnclosingTool(() => runtime.projectRoot, (filePath, symbol) => runtime.readGuard.recordSymbolRead(filePath, symbol, runtime.turnIndex, runtime.peekWriteIndex()))
+    createReadSymbolTool(() => runtime.projectRoot, (filePath, symbol, toolCallId) => runtime.readGuard.recordSymbolRead(filePath, symbol, runtime.turnIndex, runtime.peekWriteIndex(), sanitizeCorrelationId(toolCallId))),
+    createReadEnclosingTool(() => runtime.projectRoot, (filePath, symbol, toolCallId) => runtime.readGuard.recordSymbolRead(filePath, symbol, runtime.turnIndex, runtime.peekWriteIndex(), sanitizeCorrelationId(toolCallId)))
   ];
   const lazyTools = [
     createAstGrepSearchTool(astGrepClient),
-    createAstGrepReplaceTool(astGrepClient),
+    createAstGrepReplaceTool(astGrepClient, () => runtime.captureSessionGeneration()),
     createAstGrepOutlineTool(astGrepClient),
     createLspNavigationTool((name, cwd) => getLensFlag(name, cwd), {
       runtime,
@@ -1021,7 +1096,7 @@ ${degradationLines.join(`
     createLensDiagnosticMarkTool(() => runtime.projectRoot, () => ({
       model: runtime.telemetryModelId,
       provider: runtime.telemetryProviderId
-    }))
+    }), () => runtime.captureSessionGeneration())
   ];
   const LAZY_TOOL_CATALOG = TOOL_REGISTRY.filter((entry) => ("situational" in entry) && entry.situational === true).map(({ name, summary }) => ({ name, summary }));
   const enabledLazyTools = new Set(LAZY_TOOL_CATALOG.filter((tool) => isToolEnabled(tool.name)).map((tool) => tool.name));
@@ -1034,11 +1109,17 @@ ${degradationLines.join(`
       return;
     }
   };
-  let lastSessionStartIdentity;
+  const getSessionManager = (ctx) => {
+    try {
+      return ctx.sessionManager;
+    } catch {
+      return;
+    }
+  };
   const activateToolsTool = createActivateToolsTool(pi, filteredLazyCatalog, {
-    onActivated: (names, ctx) => {
+    onActivated: (names) => {
       observeSituationalToolActivation(names);
-      rememberLazyTools(getSessionFile(ctx), names);
+      rememberLazyTools(scope, names);
     },
     onRejected: (name) => {
       if (LENS_TOOL_NAMES.includes(name)) {
@@ -1101,16 +1182,36 @@ ${degradationLines.join(`
     } catch {}
   }
   pi.on("resources_discover", async (_event, _ctx) => {
-    return {
-      skillPaths: resolveSkillPaths(import.meta.url)
-    };
+    resolveSkillPaths(import.meta.url);
   });
+  const applyToolSetPlan = (ctx, reason) => {
+    try {
+      const piWithActiveTools = pi;
+      if (getLensFlag("no-lazy-tools") === true || typeof piWithActiveTools.getActiveTools !== "function" || typeof piWithActiveTools.setActiveTools !== "function")
+        return;
+      const lazyNames = new Set(enabledLazyTools);
+      const plan = planToolSet(piWithActiveTools.getActiveTools(), lazyNames, getRememberedLazyTools(scope));
+      if (!plan.changed)
+        return;
+      piWithActiveTools.setActiveTools(plan.desired);
+      recordToolSetMutation({
+        addedCount: plan.addedCount,
+        removedCount: plan.removedCount,
+        reason: isFreshSessionStart(reason) ? "fresh_session_lazy_deactivation" : "session_rebuild_restore",
+        deferralApplies: supportsDeferredTools(ctx?.model)
+      });
+    } catch (toolSetErr) {
+      dbg(`dynamic tool set restore failed (older pi host lacking getActiveTools/setActiveTools, or a genuine host error): ${toolSetErr}`);
+    }
+  };
   pi.on("session_start", wrapSessionEventHandler("session_start", async (event, ctx) => {
-    const sessionStartReason = event.reason;
-    const previousSessionFile = event.previousSessionFile;
+    const sessionStartEvent = event;
+    const isNewSessionStartEvent = reserveSessionStart(sessionStartEvent);
+    const sessionStartReason = sessionStartEvent.reason;
     const sessionIdentityParts = (() => {
       try {
         const sessionManager = ctx?.sessionManager;
+        noteHostSessionManager(sessionManager);
         return {
           sessionId: sessionManager?.getSessionId?.(),
           sessionFile: getSessionFile(ctx)
@@ -1119,24 +1220,14 @@ ${degradationLines.join(`
         return { sessionId: undefined, sessionFile: undefined };
       }
     })();
-    const sessionStartKey = sessionIdentityParts.sessionId ?? sessionIdentityParts.sessionFile;
-    const sessionStartIdentity = sessionStartKey === undefined ? undefined : `${sessionStartReason ?? ""}\x00${sessionStartKey}`;
-    const liveToolPlan = (() => {
-      if (getLensFlag("no-lazy-tools") === true || typeof pi.getActiveTools !== "function") {
-        return;
-      }
-      try {
-        const piWithActiveTools = pi;
-        const lazyNames = new Set(LAZY_TOOL_CATALOG.map((tool) => tool.name));
-        return planToolSet(piWithActiveTools.getActiveTools(), lazyNames, isFreshSessionStart(sessionStartReason) ? new Set : getRememberedLazyTools(getSessionFile(ctx)));
-      } catch {
-        return;
-      }
-    })();
-    if (sessionStartIdentity !== undefined && lastSessionStartIdentity === sessionStartIdentity && liveToolPlan?.changed !== true) {
-      emitBounded("session_start_duplicate_suppressed", sessionStartIdentity, {
+    if (!isNewSessionStartEvent) {
+      const duplicateSubject = sessionIdentityParts.sessionId ?? sessionIdentityParts.sessionFile ?? "session_start";
+      emitBounded("session_start_duplicate_suppressed", duplicateSubject, {
         durationMs: 0,
-        metadata: { reason: "duplicate start suppressed" }
+        metadata: {
+          reason: "duplicate start suppressed",
+          eventIdentity: "same-event-object"
+        }
       }, {
         ledgerKind: "session-start-duplicate",
         risingEdgePer: "identity",
@@ -1144,7 +1235,6 @@ ${degradationLines.join(`
       });
       return;
     }
-    lastSessionStartIdentity = sessionStartIdentity;
     const sessionStartMonotonicAt = performance.now();
     warmDispatchAtSessionStart();
     warmLspService().catch((err) => logExtension({
@@ -1166,7 +1256,9 @@ ${degradationLines.join(`
       if (buildIdentity)
         dbg(formatBuildIdentity(buildIdentity));
       const sessionReason = sessionStartReason;
-      dbg(`session_start: disabled tools = ${disabledToolNames.join(",") || "none"}`);
+      if (disabledToolNames.length > 0) {
+        dbg(`session_start: disabled tools = ${formatDisabledToolNames(disabledToolNames)}`);
+      }
       const trustState = adoptProjectTrustFromPorts(hostPorts);
       if (trustState !== "unknown") {
         dbg(`session_start: project trust = ${trustState}`);
@@ -1188,7 +1280,7 @@ ${degradationLines.join(`
           return;
         }
       })();
-      const sessionStartDecision = decideSessionStart(ctx, stableSessionId, sessionStartCwd);
+      const sessionStartDecision = decideSessionStart(ctx, stableSessionId, sessionStartCwd, sessionStartReason, startKey(getSessionFile(ctx), getSessionManager(ctx)));
       ownedSessionRole = sessionStartDecision.runFullSessionStart ? "primary" : "concurrent-secondary";
       if (!sessionStartDecision.runFullSessionStart) {
         dbg(`session_start: ${sessionStartDecision.classification} detected (count=${sessionStartDecision.secondaryCount}, sameRoot=${sessionStartDecision.sameRoot}) — skipping handleSessionStart`);
@@ -1201,10 +1293,39 @@ ${degradationLines.join(`
           primaryRoot: sessionStartDecision.primaryRoot
         });
         if (sessionStartDecision.sameRoot === false && typeof sessionStartCwd === "string") {
-          registerInstanceRoot(sessionStartCwd).catch(() => {});
+          ownedSecondaryRoot = sessionStartCwd;
+          registerInstanceRoot(sessionStartCwd, secondaryRootHolder).catch(() => {});
         }
+        const discardedSlot = discardHandoff({
+          reason: sessionReason,
+          sessionFile: getSessionFile(ctx),
+          sessionManager: getSessionManager(ctx)
+        });
+        scope = beginScope({ role: "secondary" });
+        logScopeTransition(scope, {
+          transition: "start",
+          reason: sessionReason,
+          sessionId: stableSessionId,
+          cwd: sessionStartCwd ?? runtime.projectRoot
+        });
+        if (sessionStartDecision.basis === "successor-pending")
+          logScopeTransition(scope, {
+            transition: "demote",
+            reason: sessionReason,
+            sessionId: stableSessionId,
+            cwd: sessionStartCwd ?? runtime.projectRoot,
+            detail: {
+              classification: sessionStartDecision.classification,
+              basis: sessionStartDecision.basis,
+              gapMs: sessionStartDecision.gapMs,
+              lineageMatch: sessionStartDecision.lineageMatch,
+              discardedSlot
+            }
+          });
         return;
       }
+      const inFlight = { reason: sessionReason, shutDown: false };
+      startInFlight = inFlight;
       resetVerifiedPathAttributionGuessCount();
       resetCurrentPhaseForSession();
       resetCacheFindingIdentitiesSession(stableSessionId, ownedSessionRole);
@@ -1212,31 +1333,6 @@ ${degradationLines.join(`
       startSituationalToolTelemetrySession("pi");
       emitConcurrentSessionBindRollupAtSessionEnd(runtime.projectRoot);
       resetConcurrentSessionBindRollupCounts();
-      try {
-        const piWithActiveTools = pi;
-        const sessionFile = getSessionFile(ctx);
-        if (sessionStartReason === "fork") {
-          inheritRememberedLazyTools(previousSessionFile, sessionFile);
-        }
-        if (isFreshSessionStart(sessionReason)) {
-          clearRememberedLazyTools(sessionFile);
-        }
-        if (getLensFlag("no-lazy-tools") !== true && typeof piWithActiveTools.getActiveTools === "function" && typeof piWithActiveTools.setActiveTools === "function") {
-          const lazyNames = new Set(LAZY_TOOL_CATALOG.map((t) => t.name));
-          const plan = planToolSet(piWithActiveTools.getActiveTools(), lazyNames, getRememberedLazyTools(sessionFile));
-          if (plan.changed) {
-            piWithActiveTools.setActiveTools(plan.desired);
-            recordToolSetMutation({
-              addedCount: plan.addedCount,
-              removedCount: plan.removedCount,
-              reason: isFreshSessionStart(sessionReason) ? "fresh_session_lazy_deactivation" : "session_rebuild_restore",
-              deferralApplies: supportsDeferredTools(ctx?.model)
-            });
-          }
-        }
-      } catch (toolSetErr) {
-        dbg(`dynamic tool set restore failed (older pi host lacking getActiveTools/setActiveTools, or a genuine host error): ${toolSetErr}`);
-      }
       await configureWarmAttach(ctx.cwd ?? process.cwd());
       registerInstance(ctx.cwd ?? process.cwd()).catch(() => {});
       readInstanceRegistry().then((registry) => logVanishedInstances(registry)).catch(() => {}).finally(() => {
@@ -1249,7 +1345,11 @@ ${degradationLines.join(`
       }).then((entries) => {
         if (entries.length === 0)
           return;
-        recordCrossProcessTouches(entries.map((e) => ({ path: e.path, reason: e.reason })));
+        recordCrossProcessTouches(entries.map((e) => ({
+          path: e.path,
+          reason: e.reason,
+          sessionId: e.sessionId
+        })));
         dbg(`session_start: cross-process nudge — ${entries.length} file(s) from other instance(s)`);
       }).catch((err) => {
         dbg(`session_start: cross-process nudge read failed: ${err}`);
@@ -1264,7 +1364,7 @@ ${degradationLines.join(`
       const emitHostReadyDelay = consumeHostReadyDelayAnchor();
       resetMemorySamplerCadence();
       resetTurnContext(stableSessionId);
-      await bounded(handleSessionStart({
+      const sessionStartWork = handleSessionStart({
         ctxCwd: ctx.cwd,
         sessionStartFiredAt,
         sessionStartMonotonicAt,
@@ -1274,8 +1374,12 @@ ${degradationLines.join(`
         handlerEnteredAt,
         globalConfig,
         projectConfig: loadDmLensProjectConfig(runtime.projectRoot),
+        disabledToolNames,
         sessionStartClassification: sessionStartDecision.classification,
         sessionStartSameRoot: sessionStartDecision.sameRoot,
+        sessionStartBasis: sessionStartDecision.basis,
+        sessionStartGapMs: sessionStartDecision.gapMs,
+        sessionStartLineageMatch: sessionStartDecision.lineageMatch,
         getFlag: (name) => getLensFlag(name),
         notify: (msg, level) => notifyUi(ctx, msg, level),
         dbg,
@@ -1288,7 +1392,20 @@ ${degradationLines.join(`
         cleanStaleTsBuildInfo,
         resetDispatchBaselines,
         resetLSPService
-      }), {
+      });
+      scope = runtime.sessionScope;
+      registerPrimaryBridges(scope);
+      _turnSummaryEmitCtxGetter = rebindableProcessBridgeDeps("turn-summary-emit-context", 1, scope, {
+        runtime,
+        pi,
+        getLensFlag: (name) => getLensFlag(name),
+        isLensEnabled: () => lensEnabled
+      });
+      runtime.setSessionLifecycle({
+        sessionId: stableSessionId,
+        reason: sessionReason
+      });
+      await bounded(sessionStartWork, {
         ms: HOOK_WALL_BUDGET_MS.session_start,
         signal: ctx.signal,
         hook: "session_start",
@@ -1296,52 +1413,37 @@ ${degradationLines.join(`
       });
       if (ctx.ui)
         updateLspStatus(ctx.ui.setStatus, ctx.ui.theme);
-      runtime.setSessionLifecycle({
+      scopeCell(scope, READ_GUARD_CELL, () => runtime.readGuard);
+      if (inFlight.shutDown)
+        return;
+      const stateCwd = ctx.cwd ?? process.cwd();
+      const handoffSource = await adoptHandoff(scope, {
+        reason: sessionReason,
+        sessionFile: getSessionFile(ctx),
+        sessionManager: ctx.sessionManager,
+        cwd: stateCwd,
+        dbg,
+        loadOwnSidecar: () => loadSessionState(stateCwd, stableSessionId),
+        loadParentSidecar: async () => {
+          const parentFile = (() => {
+            try {
+              return ctx?.sessionManager?.getHeader?.()?.parentSession;
+            } catch {
+              return;
+            }
+          })();
+          const parentId = parentFile ? await readSessionHeaderId(parentFile) : undefined;
+          return loadSessionState(stateCwd, parentId);
+        }
+      });
+      logScopeTransition(scope, {
+        transition: "start",
+        reason: sessionReason,
         sessionId: stableSessionId,
-        reason: sessionReason
+        cwd: stateCwd,
+        handoffSource
       });
-      const reasonLabel = sessionReason ?? "startup";
-      const startMode = sessionStartMode(sessionReason, !!pendingForkSnapshot);
-      if (startMode === "fork" && pendingForkSnapshot) {
-        clearWidgetState();
-        importWidgetState(pendingForkSnapshot);
-        const forkedFileCount = pendingForkSnapshot.files.length;
-        pendingForkSnapshot = undefined;
-        let forkReadImport;
-        if (pendingForkReadGuard) {
-          forkReadImport = runtime.readGuard.importState(pendingForkReadGuard);
-          pendingForkReadGuard = undefined;
-        }
-        if (stableSessionId) {
-          saveSessionState(ctx.cwd ?? process.cwd(), stableSessionId, exportWidgetState(), runtime.readGuard.exportState());
-        }
-        dbg(`session_start: fork — branched ${forkedFileCount} file(s) from source` + (forkReadImport ? `, read-guard +${forkReadImport.imported} (dropped ${forkReadImport.dropped})` : ""));
-      } else if (startMode === "keep") {
-        dbg("session_start: reload — keeping widget state");
-      } else if (startMode === "clean") {
-        pendingForkSnapshot = undefined;
-        pendingForkReadGuard = undefined;
-        clearWidgetState();
-        dbg("session_start: new — clean widget");
-      } else {
-        pendingForkSnapshot = undefined;
-        pendingForkReadGuard = undefined;
-        clearWidgetState();
-        if (stableSessionId) {
-          const persisted = await loadSessionState(ctx.cwd ?? process.cwd(), stableSessionId);
-          if (persisted?.widget) {
-            const fresh = await dropStaleFiles(persisted.widget, persisted.savedAt);
-            const dropped = persisted.widget.files.length - fresh.files.length;
-            importWidgetState(fresh);
-            const readImport = runtime.readGuard.importState(persisted.readGuard);
-            dbg(`session_start: ${reasonLabel} ${stableSessionId} — rehydrated ${fresh.files.length} file(s)` + (dropped > 0 ? `, dropped ${dropped} stale` : "") + (readImport.imported > 0 || readImport.dropped > 0 ? `; read-guard +${readImport.imported} read(s) (dropped ${readImport.dropped} stale)` : ""));
-          } else {
-            dbg(`session_start: ${reasonLabel} ${stableSessionId} — no persisted state (clean)`);
-          }
-        } else {
-          dbg(`session_start: ${reasonLabel} — no stable session id (clean)`);
-        }
-      }
+      dbg(`session_start: ${sessionReason ?? "startup"} — session stores from ${handoffSource}`);
       if (lensWidgetVisible) {
         mountLensWidget(ctx.ui, readExtensionMode(ctx));
       }
@@ -1349,17 +1451,37 @@ ${degradationLines.join(`
       if (isStaleExtensionCtxError(sessionErr))
         throw sessionErr;
       surfaceHandlerCrash("session_start", sessionErr, { dbg });
+    } finally {
+      startInFlight = undefined;
+      applyToolSetPlan(ctx, sessionStartReason);
     }
   }, { dbg }));
-  pi.on("session_before_fork", () => {
+  pi.on("session_tree", wrapSessionEventHandler("session_tree", (_event, ctx) => {
     try {
-      pendingForkSnapshot = exportWidgetState();
-      pendingForkReadGuard = runtime.readGuard.exportState();
-      dbg(`session_before_fork: stashed ${pendingForkSnapshot.files.length} file(s) + ${pendingForkReadGuard.reads.length} read-guard file(s) for the fork`);
-    } catch (forkErr) {
-      surfaceHandlerCrash("session_before_fork", forkErr, { dbg });
+      if (ownedSessionRole !== "primary")
+        return;
+      const branch = branchToolResultIds(ctx?.sessionManager);
+      const retained = runtime.readGuard.retainBranch(branch.ids);
+      logReadGuardBranchMove({
+        trigger: "tree",
+        source: "live",
+        kept: retained.kept,
+        dropped: retained.dropped,
+        branch,
+        cwd: ctx?.cwd ?? runtime.projectRoot ?? process.cwd()
+      });
+      logScopeTransition(runtime.sessionScope, {
+        transition: "tree",
+        reason: "tree",
+        sessionId: runtime.telemetrySessionId,
+        cwd: ctx?.cwd ?? runtime.projectRoot ?? process.cwd()
+      });
+    } catch (treeErr) {
+      if (isStaleExtensionCtxError(treeErr))
+        throw treeErr;
+      surfaceHandlerCrash("session_tree", treeErr, { dbg });
     }
-  });
+  }, { dbg }));
   pi.on("tool_call", async (event, ctx) => {
     const toolEntry = toolRegistryEntryForPi(event.toolName ?? "");
     if (toolEntry && "situational" in toolEntry && toolEntry.situational) {
@@ -1375,7 +1497,8 @@ ${degradationLines.join(`
       cacheManager,
       ensureLSPConfigInitialized,
       updateLspStatus,
-      resetLSPService
+      resetLSPService,
+      sessionId: getStableSessionId(ctx)
     });
   });
   const onToolResult = async (event, ctx) => {
@@ -1422,7 +1545,8 @@ ${degradationLines.join(`
         readGuard: runtime.readGuard,
         agentBehaviorRecord: (toolName, filePath) => (resident?.agentBehaviorClient ?? getAgentBehaviorClient()).recordToolCall(toolName, filePath),
         formatBehaviorWarnings: (warnings) => (resident?.agentBehaviorClient ?? getAgentBehaviorClient()).formatWarnings(warnings),
-        sessionId: getStableSessionId(ctx)
+        sessionId: getStableSessionId(ctx),
+        sessionRole: ownedSessionRole === "concurrent-secondary" ? "secondary" : "primary"
       }), {
         ms: editClass ? HOOK_WALL_BUDGET_MS.tool_result_edit : HOOK_WALL_BUDGET_MS.tool_result_read_only,
         signal: ctx.signal,
@@ -1443,26 +1567,37 @@ ${degradationLines.join(`
       }
     }
   }));
+  pi.on("tool_execution_end", (event) => {
+    handleToolExecutionEnd(event, runtime.readGuard);
+  });
   const onTurnStart = (_event, ctx) => {
     rememberOwnEventCtx(ctx);
     adoptProjectTrustFromPorts(hostPorts);
     if (lensWidgetVisible && ctx?.ui && (mountedLensWidgetUi === undefined || mountedLensWidgetUi !== ctx.ui)) {
       mountLensWidget(ctx.ui, readExtensionMode(ctx));
     }
-    runtime.beginTurn();
+    runtime.beginTurn(getStableSessionId(ctx));
+    turnStartScope = scope ?? runtime.sessionScope;
+    if (ownedSessionRole === "concurrent-secondary" && getStableSessionId(ctx) !== undefined) {
+      cacheManager.ensureSecondaryTurnStatePartition(ctx?.cwd ?? process.cwd(), getStableSessionId(ctx));
+    }
     clearLastAnalyzedStateCache();
     const cwd = ctx?.cwd ?? process.cwd();
     readCrossProcessTouchesForTurnStart({ cwd }).then((entries) => {
       if (entries.length === 0)
         return;
-      recordCrossProcessTouches(entries.map((e) => ({ path: e.path, reason: e.reason })));
+      recordCrossProcessTouches(entries.map((e) => ({
+        path: e.path,
+        reason: e.reason,
+        sessionId: e.sessionId
+      })));
       dbg(`turn_start: cross-process nudge — ${entries.length} file(s) from other instance(s)`);
     }).catch((err) => {
       dbg(`turn_start: cross-process nudge read failed: ${err}`);
     });
   };
   pi.on("turn_start", wrapSessionEventHandler("turn_start", onTurnStart, { dbg }));
-  async function runObservedSettledSweepSafely(ctx) {
+  async function runObservedSettledSweepSafely(ctx, readGuardBranchEpoch, lineage) {
     const cwd = ctx.cwd ?? runtime.projectRoot;
     try {
       const result = await runObservedSettledSweep({
@@ -1472,7 +1607,11 @@ ${degradationLines.join(`
           cwd,
           limit: OBSERVED_TRACKED_MAX_FILES
         }),
-        record: replayThroughMutationBridge,
+        record: (entry) => replayThroughMutationBridge({
+          ...entry,
+          readGuardBranchEpoch,
+          lineage
+        }),
         getStoredLineHashes: (candidate) => storedLineHashesFor(runtime.readGuard, candidate),
         isRecordable: (candidate) => isRecordableProjectPath(candidate, runtime.projectRoot),
         signal: ctx?.signal,
@@ -1591,7 +1730,8 @@ ${degradationLines.join(`
         }
       }
       resetEventLoopMonitor();
-      if (shouldEmitMemorySampleAdaptive(runtime.turnIndex)) {
+      const cadenceTurn = runtime.turnStartCount;
+      if (shouldEmitMemorySampleAdaptive(cadenceTurn)) {
         try {
           const sample = buildMemorySample(runtime.wordIndex, undefined, undefined, {
             sessionAgeMs: Math.max(0, Date.now() - runtime.sessionStartedAt),
@@ -1606,10 +1746,10 @@ ${degradationLines.join(`
             durationMs: 0,
             metadata: { turnIndex: runtime.turnIndex, ...sample }
           });
-          recordMemorySampleOutcome(sample.process.heapUsedBytes, runtime.turnIndex);
+          recordMemorySampleOutcome(sample.process.heapUsedBytes, cadenceTurn);
         } catch {}
       }
-      if (shouldCheckSmellsThisTurn(runtime.turnIndex)) {
+      if (shouldCheckSmellsThisTurn(cadenceTurn)) {
         try {
           for (const note of checkSmellsAndNoteOnce(countRecentSmells(undefined, runtime.sessionStartedAt))) {
             notifyUi(ctx, note, "warning");
@@ -1629,6 +1769,7 @@ ${degradationLines.join(`
         depChecker,
         testRunnerClient,
         sessionId: getStableSessionId(ctx),
+        sessionScope: turnStartScope ?? scope ?? runtime.sessionScope,
         signal: ctx.signal,
         onTestRunnerComplete: (delivery) => stageTestRunnerDelivery({
           ...delivery,
@@ -1650,7 +1791,7 @@ ${degradationLines.join(`
       });
       repaintLspStatus?.();
       if (runtime.hasStableSessionId) {
-        saveSessionState(ctx.cwd ?? process.cwd(), runtime.telemetrySessionId, exportWidgetState(), runtime.readGuard.exportState());
+        persistScope(ctx.cwd ?? process.cwd(), runtime.telemetrySessionId, runtime.sessionScope);
       }
     } catch (turnEndErr) {
       if (isStaleExtensionCtxError(turnEndErr))
@@ -1682,15 +1823,10 @@ ${degradationLines.join(`
       reconcileCascadeNeighborLspErrors(filePath, [], undefined, publishedAt);
     }
   });
-  _turnSummaryEmitCtx = {
-    pi,
-    getLensFlag: (name) => getLensFlag(name),
-    isLensEnabled: () => lensEnabled
-  };
   if (!_turnSummaryEmitRegistered) {
     _turnSummaryEmitRegistered = true;
     registerQuietWindowTask("turn_summary_emit", () => {
-      const emitCtx = _turnSummaryEmitCtx;
+      const emitCtx = _turnSummaryEmitCtxGetter?.();
       if (!emitCtx || !emitCtx.isLensEnabled())
         return;
       let turnSummaryEnabled;
@@ -1705,11 +1841,11 @@ ${degradationLines.join(`
       }
       if (!turnSummaryEnabled)
         return;
-      if (runtime.turnSummary.isEmpty())
+      if (emitCtx.runtime.turnSummary.isEmpty())
         return;
       const summaryStart = Date.now();
-      const cwd = runtime.projectRoot || process.cwd();
-      const details = runtime.turnSummary.consume(runtime.turnIndex, (fp) => toRunnerDisplayPath(cwd, fp));
+      const cwd = emitCtx.runtime.projectRoot || process.cwd();
+      const details = emitCtx.runtime.turnSummary.consume(emitCtx.runtime.turnIndex, (fp) => toRunnerDisplayPath(cwd, fp));
       const line = formatTurnSummaryLine(details);
       const sendMessage = emitCtx.pi.sendMessage;
       if (typeof sendMessage === "function") {
@@ -1720,7 +1856,7 @@ ${degradationLines.join(`
             display: true,
             details
           });
-          recordTurnEndAdvisoryBytes(runtime.telemetrySessionId, Buffer.byteLength(line, "utf8"));
+          recordTurnEndAdvisoryBytes(emitCtx.runtime.telemetrySessionId, Buffer.byteLength(line, "utf8"));
         } catch (sendErr) {
           if (isStaleExtensionCtxError(sendErr)) {
             dbg("turn_summary_emit: skipped emit — pi ctx went stale (session replaced/reloaded)");
@@ -1749,13 +1885,15 @@ ${degradationLines.join(`
   const onAgentSettled = async (_event, ctx) => {
     if (!lensEnabled)
       return;
+    const settleBranchEpoch = runtime.readGuard.currentBranchEpoch;
     rememberOwnEventCtx(ctx);
     try {
       setAmbientAbortSignal(ctx?.signal);
+      const settleSession = runtime.captureSessionGeneration();
       try {
-        await runObservedSettledSweepSafely(ctx);
+        await runObservedSettledSweepSafely(ctx, settleBranchEpoch, settleSession);
         await runDeferredMutationDrain(ctx);
-        await refreshObservedLedgerSafely(ctx);
+        await settleSession.guardedWrite(`observed-ledger-refresh:${ctx?.cwd ?? runtime.projectRoot}`, () => refreshObservedLedgerSafely(ctx));
       } catch (drainErr) {
         if (isStaleExtensionCtxError(drainErr))
           throw drainErr;
@@ -1764,6 +1902,13 @@ ${degradationLines.join(`
         });
       } finally {
         setAmbientAbortSignal(undefined);
+        const settledIndex = runtime.wordIndex;
+        if (settledIndex && settleSession.isCurrent() && classifyOwnedSessionEmission(ctx, getStableSessionId(ctx)) === "primary") {
+          import("./clients/word-index.js").then(({ releaseWordIndexMemoAtSettle }) => releaseWordIndexMemoAtSettle(settledIndex)).catch((err) => surfaceHandlerCrash("word_index_memo_release", err, {
+            dbg,
+            rethrow: false
+          }));
+        }
       }
       const cwd = ctx?.cwd;
       runQuietWindow({
@@ -1786,6 +1931,17 @@ ${degradationLines.join(`
   } catch (registerErr) {
     dbg(`agent_settled registration failed (older pi host?): ${registerErr}`);
   }
+  const retireOwnScope = (reason, sessionId) => {
+    if (!scope)
+      return;
+    retireScope(scope, reason);
+    logScopeTransition(scope, {
+      transition: "shutdown",
+      reason: scope.retiredBy(),
+      sessionId,
+      cwd: runtime.projectRoot
+    });
+  };
   pi.on("session_shutdown", (event, ctx) => {
     const stableSessionId = (() => {
       try {
@@ -1803,40 +1959,81 @@ ${degradationLines.join(`
     })();
     const shutdownClassification = classifyOwnedSessionShutdown(ctx, stableSessionId, shutdownCwd);
     if (shutdownClassification === "secondary") {
+      if (stableSessionId !== undefined && shutdownCwd !== undefined) {
+        cacheManager.clearTurnState(shutdownCwd, {
+          kind: "pi",
+          id: stableSessionId
+        }, stableSessionId);
+      }
       emitCacheUsageSummaryAtSessionEnd(stableSessionId, "concurrent-secondary");
       clearCachePrefixSession(stableSessionId, "concurrent-secondary");
+      runtime.forgetTurnSession(stableSessionId);
       decrementSecondarySessionCount();
-      try {
-        const secondaryRoot = shutdownCwd;
-        const primaryRoot = getActivePrimaryRoot();
-        if (typeof secondaryRoot === "string" && secondaryRoot.length > 0 && primaryRoot !== undefined && normalizeFilePath(secondaryRoot) !== primaryRoot) {
-          deregisterInstanceRoot(secondaryRoot).catch(() => {});
-        }
-      } catch {}
+      if (ownedSecondaryRoot !== undefined) {
+        deregisterInstanceRoot(ownedSecondaryRoot, secondaryRootHolder).catch(() => {});
+      }
+      retireOwnScope(event?.reason, stableSessionId);
       dbg("session_shutdown: concurrent secondary — skipping shared-infra teardown");
       return;
     }
     const shutdownEvent = event;
     const shutdownReason = shutdownEvent?.reason;
-    const switchesSessionFile = typeof shutdownEvent?.targetSessionFile === "string" && shutdownEvent.targetSessionFile.length > 0;
-    if (switchesSessionFile || shutdownReason === "quit" || shutdownReason === undefined) {
-      endSituationalToolTelemetry();
-    }
-    emitCacheUsageSummaryAtSessionEnd(stableSessionId, "primary");
-    clearCachePrefixSession(stableSessionId, "primary");
-    cancelLSPIdleReset();
-    deregisterInstance();
-    releasePrimarySession();
-    markAnalyzerBootstrapShutdown();
-    resetLSPService({
-      fast: true,
-      processExiting: true,
-      reason: "session_shutdown"
+    const shutdownBudgetKey = shutdownReason === "quit" ? "session_shutdown_quit" : "session_shutdown";
+    const ndjsonDrain = bounded(flushAllNdjsonWriters(), {
+      ms: HOOK_WALL_BUDGET_MS[shutdownBudgetKey],
+      signal: undefined,
+      hook: "session_shutdown",
+      label: "ndjson-writers"
     });
-    emitBusEventRollupAtSessionEnd(runtime.projectRoot);
-    emitVerifiedPathAttributionRollup(runtime.projectRoot);
-    emitConcurrentSessionBindRollupAtSessionEnd(runtime.projectRoot);
-    dumpActiveHandles("session_shutdown");
+    try {
+      const unstartedReason = startInFlight || scope !== undefined ? undefined : namedSuccessorReason() ?? expiredSuccessorReason();
+      if (startInFlight || unstartedReason !== undefined) {
+        if (startInFlight)
+          startInFlight.shutDown = true;
+        forwardHandoff({
+          startReason: startInFlight ? startInFlight.reason : unstartedReason,
+          reason: shutdownReason,
+          sessionFile: getSessionFile(ctx),
+          targetSessionFile: shutdownEvent?.targetSessionFile,
+          sessionManager: getSessionManager(ctx)
+        });
+      } else if (scope && stashHandoff(scope, {
+        reason: shutdownReason,
+        sessionFile: getSessionFile(ctx),
+        targetSessionFile: shutdownEvent?.targetSessionFile,
+        sessionManager: getSessionManager(ctx)
+      }) && runtime.hasStableSessionId) {
+        persistScope(shutdownCwd ?? process.cwd(), runtime.telemetrySessionId, scope);
+      }
+      const switchesSessionFile = typeof shutdownEvent?.targetSessionFile === "string" && shutdownEvent.targetSessionFile.length > 0;
+      if (switchesSessionFile || shutdownReason === "quit" || shutdownReason === undefined) {
+        endSituationalToolTelemetry();
+      }
+      emitCacheUsageSummaryAtSessionEnd(stableSessionId, "primary");
+      clearCachePrefixSession(stableSessionId, "primary");
+      cancelLSPIdleReset();
+      deregisterInstance();
+      releasePrimarySession(shutdownReason, successorStartKey({
+        reason: shutdownReason,
+        sessionFile: getSessionFile(ctx),
+        targetSessionFile: shutdownEvent?.targetSessionFile,
+        sessionManager: getSessionManager(ctx)
+      }));
+      markAnalyzerBootstrapShutdown();
+      resetLSPService({
+        fast: true,
+        processExiting: true,
+        reason: "session_shutdown"
+      });
+      emitBusEventRollupAtSessionEnd(runtime.projectRoot);
+      emitFenceRollupAtSessionEnd(runtime.projectRoot);
+      emitVerifiedPathAttributionRollup(runtime.projectRoot);
+      emitConcurrentSessionBindRollupAtSessionEnd(runtime.projectRoot);
+      dumpActiveHandles("session_shutdown");
+    } finally {
+      retireOwnScope(shutdownReason, stableSessionId);
+    }
+    return ndjsonDrain;
   });
   try {
     pi.on?.("message_end", (event, ctx) => {
@@ -1875,10 +2072,20 @@ ${degradationLines.join(`
   const isPlainUserPrompt = (msg) => {
     if (msg.role !== "user")
       return false;
-    if (!Array.isArray(msg.content))
+    if (typeof msg.content === "string")
       return true;
+    if (!Array.isArray(msg.content))
+      return false;
     return !msg.content.some((block) => typeof block === "object" && block !== null && block.type === "tool_result");
   };
+  const appendToUserPromptContent = (content, injectedText) => {
+    if (typeof content === "string") {
+      return content.length > 0 ? `${content}
+
+${injectedText}` : injectedText;
+    }
+    return [...content, { type: "text", text: injectedText }];
+  };
   pi.on("context", wrapSessionEventHandlerWithResult("context", async (event, ctx) => {
     const existingMessages = event?.messages ?? [];
     const prefixSessionId = getStableSessionId(ctx);
@@ -1917,7 +2124,7 @@ ${degradationLines.join(`
         cacheManager,
         runtime
       });
-      const agentNudge = consumeAgentNudge(dbg);
+      const agentNudge = consumeAgentNudge(dbg, scope);
       const sourceMessages = [
         {
           source: "session-guidance",
@@ -1952,12 +2159,22 @@ ${degradationLines.join(`
         logContextObservation(resultMessages, "append", sourceMessages);
         return { messages: resultMessages };
       }
+      const injectedText = injectedMessages.map((m) => m.content).join(`
+
+`);
+      if (!injectedText) {
+        logContextObservation(existingMessages, "none", []);
+        return;
+      }
+      const updatedLastMessage = {
+        ...lastMessage,
+        content: appendToUserPromptContent(lastMessage.content, injectedText)
+      };
       const resultMessages = [
         ...existingMessages.slice(0, -1),
-        ...injectedMessages,
-        lastMessage
+        updatedLastMessage
       ];
-      logContextObservation(resultMessages, "insert-before-final", sourceMessages);
+      logContextObservation(resultMessages, "append-to-last-user", sourceMessages);
       return { messages: resultMessages };
     } catch (err) {
       if (isStaleExtensionCtxError(err))