@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/dist/clients/runtime-session.js

@@ -0,0 +1,1768 @@
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { resetBoundedTelemetry } from "./bounded-telemetry.js";
+import { rotateMessageEndAttribution } from "./message-end-attribution.js";
+import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
+import { deadCodeIssueCount } from "./dead-code-client.js";
+import { logDeadCodeScan } from "./dead-code-logger.js";
+import { incrementDegradationCount, recordDegradationOnce, resetDegradationLedger } from "./degradation-ledger.js";
+import { getDiagnosticTracker } from "./diagnostic-tracker.js";
+import { resetPsScriptAnalyzerAvailability } from "./dispatch/runners/psscriptanalyzer.js";
+import { resetInstallRetryLatches } from "./dispatch/runners/utils/availability-policy.js";
+import { resetLazyInstallAttempts } from "./dispatch/runners/utils/lazy-installer.js";
+import { resetDispatchAvailabilityState } from "./dispatch/runners/utils/runner-helpers.js";
+import { resetObservedRunnerLatency } from "./dispatch/collect-later-tier.js";
+import { resetPendingRunnerFindings } from "./dispatch/pending-runner-findings.js";
+import { clearAllSessions as clearFileTimeSessions } from "./file-time.js";
+import { drainProjectDataDirMigrations, sweepDeadEphemeralDataDirs, getGlobalDmLensDir, getKnipIgnorePatterns, getProjectDataDir, resetProjectDataDirSessionState } from "./file-utils.js";
+import { GitleaksClient } from "./gitleaks-client.js";
+import { resetGoAvailability } from "./go-client.js";
+import { GovulncheckClient } from "./govulncheck-client.js";
+import { realIsPidAlive, sweepAtomicWriteStages } from "./instance-reaper.js";
+import { canRunStartupHeavyScans } from "./language-policy.js";
+import { detectProjectLanguageProfile, getDefaultStartupTools } from "./language-profile.js";
+import { logLatency } from "./latency-logger.js";
+import { runLogCleanup } from "./log-cleanup.js";
+import { resetCascadeTierSessionState } from "./lsp/cascade-tier.js";
+import { initLSPConfig, loadLSPConfig } from "./lsp/config.js";
+import { resetWorkspaceDiagnosticsCacheSession } from "./lsp/workspace-diagnostics-session.js";
+import { resetDirectLspCommandAvailability, resetLSPCaseSensitivityState } from "./lsp/server.js";
+import { loadLspService } from "./lsp-lazy.js";
+import { resetManagedToolRefreshSession } from "./installer/managed-tool-refresh-session.js";
+import { resetResolvedPathCache } from "./installer/index.js";
+import { _resetPackageManagerCache } from "./package-manager.js";
+import { clearFormatterCache } from "./formatters.js";
+import { isAtOrAboveHomeDir } from "./path-utils.js";
+import { isPrintMode } from "./print-mode.js";
+import { readLatestProjectSequence, readLatestProjectSequenceAsync } from "./project-changes.js";
+import { getProjectSnapshotPath, getProjectSnapshotLegacyPath, hydrateRuntimeFromProjectSnapshot, hydrateRuntimeFromProjectSnapshotIfIdle, isProjectSnapshotFresh, isProjectSnapshotMetaStale, loadProjectSnapshot, loadProjectSnapshotExportsAndRules, PROJECT_SNAPSHOT_VERSION, readProjectSnapshotMeta, saveRuntimeProjectSnapshot } from "./project-snapshot.js";
+import { scanProjectRules } from "./rules-scanner.js";
+import { resetRustAvailability } from "./rust-client.js";
+import { resetSafeSpawnWindowsCommandCache } from "./safe-spawn.js";
+import { resetAnalyzerBootstrapSessionState } from "./bootstrap.js";
+import { getSlowFsVerdict, isSlowFs, slowFsDegradationNotice } from "./slow-fs.js";
+import { countRecentSmells, formatSmellsSessionStartLine, resetSmellsSessionState } from "./smells-rollup.js";
+import { resetSituationalToolTelemetry } from "./situational-tool-telemetry.js";
+import { findNearestProjectRoot, isStartupScanVerdictFresh, resolveStartupScanContext } from "./startup-scan.js";
+import { getSubagentIdentity, isSubagentSession, subagentLightModeNotice } from "./subagent-mode.js";
+import { TrivyClient } from "./trivy-client.js";
+import { isWarmAttached } from "./warm-attach.js";
+import { setSessionLanguages } from "./widget-state.js";
+import { logWordIndex } from "./word-index-logger.js";
+import { resetOpaqueMutationState } from "./opaque-mutation-scan.js";
+import { primePersistedMutationAttribution, resetMutationAttribution } from "./mutation-attribution.js";
+import { resetObservedMutationNet } from "./observed-mutation.js";
+import { resetPendingAuxiliaryCoverage } from "./lsp/pending-aux-coverage.js";
+import { resetWorkspaceTopology } from "./workspace-topology.js";
+import { resetZizmorTokenAvailability } from "./zizmor-config.js";
+import { resetSpawnTimeoutCooldowns } from "./spawn-timeout-cooldown.js";
+import { resetTestRunnerDelivery } from "./test-runner-delivery.js";
+import { resetLspMutationNoBridgeDbgLatch } from "./lsp-mutation.js";
+function notifyStartupWarmSkip(args) {
+  if (!args.runtime.isCurrentSession(args.sessionGeneration))
+    return;
+  const reason = args.scan.reason;
+  if (reason !== "too-many-source-files" && reason !== "too-many-entries") {
+    return;
+  }
+  const bound = reason === "too-many-entries" ? {
+    name: "maxScanEntries",
+    value: args.scan.maxScanEntries,
+    hint: `set DM_LENS_STARTUP_SCAN_MAX_ENTRIES=<n> to override the ${args.scan.maxScanEntries}-entry cap`
+  } : {
+    name: "maxProjectFiles",
+    value: args.scan.maxProjectFiles,
+    hint: `set maxProjectFiles in .dm-lens.json to override the ${args.scan.maxProjectFiles}-source-file cap`
+  };
+  recordDegradationOnce({
+    kind: "startup-warm-skipped",
+    subject: args.analysisRoot,
+    reason: `${reason}; ${bound.name}=${bound.value}`,
+    metadata: { reason, [bound.name]: bound.value }
+  });
+  args.notify(`\uD83D\uDCE6 Project-size limits disabled background warm scans (heavy scans, TODO scan, LSP pre-warm) (${bound.hint}).`, "warning");
+}
+async function demandBootstrapDeps(deps, reason) {
+  const clients = await deps.bootstrap.request(reason);
+  if (!clients)
+    return null;
+  return { ...deps, ...clients };
+}
+const HOST_STALL_THRESHOLD_MS = 30000;
+function logHostReadyDelay(deps, cwd) {
+  if (!deps.emitHostReadyDelay || deps.sessionStartMonotonicAt === undefined || deps.extensionLoadedAt === undefined) {
+    return;
+  }
+  const durationMs = Math.max(0, deps.sessionStartMonotonicAt - deps.extensionLoadedAt);
+  logLatency({
+    type: "phase",
+    filePath: cwd,
+    phase: "host_ready_delay",
+    durationMs,
+    metadata: {
+      hostStallSuspected: durationMs > HOST_STALL_THRESHOLD_MS,
+      sessionStart: "first-process-session",
+      reason: deps.sessionReason
+    }
+  });
+}
+function resolveSnapshotRoot(cwd) {
+  const resolvedCwd = path.resolve(cwd);
+  const nearest = findNearestProjectRoot(resolvedCwd);
+  if (!nearest || isAtOrAboveHomeDir(nearest)) {
+    return resolvedCwd;
+  }
+  return nearest;
+}
+function snapshotSequenceBase(root) {
+  const meta = readProjectSnapshotMeta(root);
+  if (!meta || meta.version !== PROJECT_SNAPSHOT_VERSION)
+    return;
+  const index = meta.sequenceIndex;
+  if (!index)
+    return;
+  return {
+    projectSeq: index.projectSeq,
+    fileSeqByPath: index.fileSeqByPath,
+    sinceSeq: meta.seq,
+    logEntries: meta.logEntries ?? 0
+  };
+}
+function recordSnapshotSequenceTimeout(args) {
+  let reason = "sequence read timed out; no snapshot on disk";
+  try {
+    const stat = nodeFs.statSync(args.snapshotPath);
+    reason = `sequence read timed out; snapshot age=${Math.round(Date.now() - stat.mtimeMs)}ms size=${stat.size}b`;
+  } catch {}
+  incrementDegradationCount({
+    kind: "snapshot-sequence-read-timeout",
+    subject: args.snapshotRoot,
+    reason
+  });
+}
+function retroactivelyHydrateAfterDeferredSequence(args) {
+  return (latestSeq) => {
+    const published = args.getWarmupOwnSnapshotRead();
+    const snapshot = published !== undefined ? published : loadProjectSnapshotExportsAndRules(args.snapshotRoot);
+    if (!snapshot || snapshot.version !== PROJECT_SNAPSHOT_VERSION || snapshot.incomplete || (snapshot.logEntries ?? 0) < (latestSeq.unlockedThrough ?? 0) || snapshot.seq !== latestSeq.projectSeq) {
+      return;
+    }
+    const hydrated = hydrateRuntimeFromProjectSnapshotIfIdle(args.runtime, snapshot);
+    if (hydrated) {
+      args.dbg(`session_start: deferred sequence read confirmed snapshot freshness — hydrating cachedExports/projectRulesScan late (seq=${snapshot.seq})`);
+    } else {
+      args.dbg(`session_start: deferred sequence read confirmed snapshot freshness (seq=${snapshot.seq}), but the runtime already has live state (warmup or another task got there first) — skipping late hydration to avoid clobbering it`);
+    }
+  };
+}
+function loadSnapshotBodyUnlessStale(args) {
+  const meta = readProjectSnapshotMeta(args.root);
+  if (meta && isProjectSnapshotMetaStale(meta, args.currentProjectSeq, args.unlockedThrough)) {
+    args.dbg(`project_snapshot: meta gate stale (metaSeq=${meta.seq} metaVersion=${meta.version} current=${args.currentProjectSeq}) — skipping body parse`);
+    return { snapshot: null, skippedStale: true };
+  }
+  return {
+    snapshot: loadProjectSnapshot(args.root),
+    skippedStale: false
+  };
+}
+function describeSnapshotMiss(snapshot, currentProjectSeq, args) {
+  if (args.skippedStale)
+    return "stale-meta-gate";
+  if (!snapshot)
+    return args.bodyPresent ? "invalid-body" : "missing";
+  if (snapshot.seq !== currentProjectSeq) {
+    return `stale(seq=${snapshot.seq}, current=${currentProjectSeq})`;
+  }
+  if ((snapshot.logEntries ?? 0) < args.unlockedThrough) {
+    return `unlocked-entry-after-fold(folded=${snapshot.logEntries ?? 0}, unlocked=${args.unlockedThrough})`;
+  }
+  return "incompatible";
+}
+function logProjectSnapshotProbe(args) {
+  args.dbg(`project_snapshot: probe root=${args.root} path=${getProjectSnapshotPath(args.root)} currentSeq=${args.currentProjectSeq}`);
+  if (isProjectSnapshotFresh(args.snapshot, args.currentProjectSeq, args.unlockedThrough)) {
+    args.dbg(`project_snapshot: loaded seq=${args.snapshot.seq} exports=${args.snapshot.cachedExports.length} files=${Object.keys(args.snapshot.files ?? {}).length} reverseDeps=${Object.keys(args.snapshot.reverseDeps ?? {}).length} startupScan=${Boolean(args.snapshot.startupScan)} languageProfile=${Boolean(args.snapshot.languageProfile)}`);
+  } else {
+    args.dbg(`project_snapshot: miss reason=${args.missReason}`);
+  }
+}
+function resolveStartupMode(projectConfig, globalConfig) {
+  const envMode = (process.env.DM_LENS_STARTUP_MODE ?? "").trim().toLowerCase();
+  if (envMode === "full" || envMode === "minimal" || envMode === "quick") {
+    return envMode;
+  }
+  const configMode = projectConfig?.startup?.mode ?? globalConfig?.startup?.mode;
+  if (configMode)
+    return configMode;
+  if (isPrintMode()) {
+    return "quick";
+  }
+  return "full";
+}
+function sequenceReadBudgetMs() {
+  const raw = Number(process.env.DM_LENS_SEQUENCE_READ_BUDGET_MS ?? 250);
+  return Number.isFinite(raw) && raw > 0 ? raw : 250;
+}
+const UNKNOWN_PROJECT_SEQ = -1;
+async function readSequenceWithBudget(args) {
+  const { snapshotRoot, base, cwd, runtime, sessionGeneration, dbg, onDeferredSequenceResolved } = args;
+  const readPromise = readLatestProjectSequenceAsync(snapshotRoot, base);
+  let timeoutHandle;
+  const timeoutPromise = new Promise((resolve) => {
+    timeoutHandle = setTimeout(() => resolve({ timedOut: true }), sequenceReadBudgetMs());
+    timeoutHandle.unref();
+  });
+  const raced = await Promise.race([
+    readPromise.then((latestSeq) => ({ timedOut: false, latestSeq })),
+    timeoutPromise
+  ]);
+  if (timeoutHandle)
+    clearTimeout(timeoutHandle);
+  if (!raced.timedOut) {
+    return { latestSeq: raced.latestSeq, timedOut: false };
+  }
+  dbg(`session_start: sequence read exceeded ${sequenceReadBudgetMs()}ms budget — falling back to cold-start sequence`);
+  if (!isPrintMode()) {
+    readPromise.then((latestSeq) => {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      if (runtime.projectSeq > 0) {
+        const mergeStartedAt = Date.now();
+        runtime.mergeProjectSequence?.(latestSeq.projectSeq, latestSeq.fileSeqByPath, latestSeq.logEntries);
+        logLatency({
+          type: "phase",
+          phase: "session_start_sequence_read_deferred_reseed",
+          filePath: cwd,
+          startedAt: new Date(mergeStartedAt).toISOString(),
+          durationMs: Date.now() - mergeStartedAt,
+          metadata: {
+            entries: latestSeq.fileSeqByPath.size,
+            deferred: true,
+            merged: true
+          }
+        });
+        dbg(`session_start: deferred sequence read completed after an in-window edit — merged projectSeq=${latestSeq.projectSeq} into the advanced session (now ${runtime.projectSeq})`);
+        return;
+      }
+      const reseedStartedAt = Date.now();
+      runtime.seedProjectSequence?.(latestSeq.projectSeq, latestSeq.fileSeqByPath, latestSeq.logEntries);
+      logLatency({
+        type: "phase",
+        phase: "session_start_sequence_read_deferred_reseed",
+        filePath: cwd,
+        startedAt: new Date(reseedStartedAt).toISOString(),
+        durationMs: Date.now() - reseedStartedAt,
+        metadata: { entries: latestSeq.fileSeqByPath.size, deferred: true }
+      });
+      dbg(`session_start: deferred sequence read completed — reseeded projectSeq=${latestSeq.projectSeq} fileSeqEntries=${latestSeq.fileSeqByPath.size}`);
+      onDeferredSequenceResolved?.(latestSeq);
+    }).catch((err) => {
+      dbg(`session_start: deferred sequence read failed: ${err}`);
+    });
+  }
+  return {
+    latestSeq: { projectSeq: 0, fileSeqByPath: new Map },
+    timedOut: true
+  };
+}
+async function igniteWarmFiles(cwd, warmFiles, runtime, sessionGeneration, dbg) {
+  try {
+    dbg(`session_start lsp-warm: ${warmFiles.length} warm file(s) configured`);
+    await initLSPConfig(cwd);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const lspService = (await loadLspService()).getLSPService();
+    const total = warmFiles.length;
+    let loaded = 0;
+    let errors = 0;
+    for (const relPath of warmFiles) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      const filePath = path.isAbsolute(relPath) ? relPath : path.resolve(cwd, relPath);
+      if (!nodeFs.existsSync(filePath)) {
+        dbg(`session_start lsp-warm: not found: ${relPath}`);
+        errors++;
+        continue;
+      }
+      try {
+        const content = nodeFs.readFileSync(filePath, "utf-8");
+        await lspService.touchFile(filePath, content, {
+          diagnostics: "none",
+          source: "startup-warm",
+          clientScope: "primary",
+          maxClientWaitMs: 2000
+        });
+        loaded++;
+      } catch (err) {
+        dbg(`session_start lsp-warm: error ${relPath}: ${err}`);
+        errors++;
+      }
+    }
+    dbg(`session_start lsp-warm: ${loaded}/${total} opened (${errors} err)`);
+  } catch (err) {
+    dbg(`session_start lsp-warm: config/init error: ${err}`);
+  }
+}
+async function igniteDominantLanguageWarm(cwd, runtime, sessionGeneration, dbg) {
+  try {
+    await initLSPConfig(cwd);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const lspService = (await loadLspService()).getLSPService();
+    const { collectSourceFilesAsync } = await import("./source-filter.js");
+    const { CODE_KINDS, detectFileKind } = await import("./file-kinds.js");
+    const files = await collectSourceFilesAsync(cwd, {
+      inspectGeneratedHeaders: false
+    });
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const counts = new Map;
+    for (const f of files) {
+      const kind = detectFileKind(f);
+      if (kind)
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+    }
+    if (counts.size === 0) {
+      dbg("session_start lsp-warm: no detected languages to auto-warm");
+      return;
+    }
+    const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    const warmOrder = [
+      ...ranked.filter(([kind]) => CODE_KINDS.has(kind)),
+      ...ranked.filter(([kind]) => !CODE_KINDS.has(kind))
+    ];
+    for (const [kind] of warmOrder) {
+      const sample = files.find((f) => detectFileKind(f) === kind && lspService.supportsLSP(f));
+      if (!sample)
+        continue;
+      const content = await nodeFs.promises.readFile(sample, "utf-8");
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      await lspService.touchFile(sample, content, {
+        diagnostics: "none",
+        source: "startup-warm-dominant",
+        clientScope: "primary",
+        maxClientWaitMs: 2000
+      });
+      dbg(`session_start lsp-warm: dominant=${kind} via ${path.basename(sample)}`);
+      return;
+    }
+    dbg("session_start lsp-warm: no dominant-language LSP file found to warm");
+  } catch (err) {
+    dbg(`session_start lsp-warm: dominant warm error: ${err}`);
+  }
+}
+function firePreinstallDefaults(ensureTool, dbg, startupDefaults) {
+  for (const tool of startupDefaults) {
+    const startedAt = Date.now();
+    dbg(`session_start preinstall ${tool}: start`);
+    ensureTool(tool).then((toolPath) => {
+      if (toolPath) {
+        dbg(`session_start: ${tool} ready at ${toolPath}`);
+        dbg(`session_start preinstall ${tool}: success (${Date.now() - startedAt}ms)`);
+      } else {
+        dbg(`session_start: ${tool} installation unavailable`);
+        dbg(`session_start preinstall ${tool}: unavailable (${Date.now() - startedAt}ms)`);
+      }
+    }).catch((err) => {
+      dbg(`session_start: ${tool} pre-install error: ${err}`);
+      dbg(`session_start preinstall ${tool}: error (${Date.now() - startedAt}ms)`);
+    });
+  }
+}
+const MANAGED_TOOL_REFRESH_DELAY_MS = 30000;
+function scheduleManagedToolRefresh(dbg) {
+  const delayMs = Number(process.env.DM_LENS_TOOL_REFRESH_DELAY_MS ?? MANAGED_TOOL_REFRESH_DELAY_MS);
+  const timer = setTimeout(() => {
+    (async () => {
+      try {
+        const refresh = await import("./installer/managed-tool-refresh.js");
+        const outcome = await refresh.runManagedToolRefresh();
+        if (outcome.skipped) {
+          dbg(`session_start tool-refresh: skipped (${outcome.skipped})`);
+          return;
+        }
+        for (const result of outcome.refreshed) {
+          dbg(`session_start tool-refresh: ${result.toolId} ${result.ok ? "ok" : "failed"}${result.changed ? ` ${result.previousVersion ?? "unknown"} → ${result.currentVersion}` : " (unchanged)"}`);
+        }
+      } catch (err) {
+        dbg(`session_start tool-refresh: error ${err}`);
+      }
+    })();
+  }, Number.isFinite(delayMs) ? delayMs : MANAGED_TOOL_REFRESH_DELAY_MS);
+  timer.unref?.();
+}
+async function probePrettierInstall(ensureTool, dbg, analysisRoot) {
+  const pkgPath = path.join(analysisRoot, "package.json");
+  try {
+    const raw = await nodeFs.promises.readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    const usesPrettier = !!pkg.devDependencies?.prettier || !!pkg.dependencies?.prettier || pkg.prettier !== undefined;
+    if (usesPrettier) {
+      dbg("session_start: project uses prettier, ensuring install...");
+      ensureTool("prettier").then((p) => {
+        if (p)
+          dbg(`session_start: prettier ready at ${p}`);
+        else
+          dbg("session_start: prettier install failed silently");
+      }).catch((err) => dbg(`session_start: prettier install error: ${err}`));
+    }
+  } catch {}
+}
+function scanOneTodoFile(scanner, filePath, items) {
+  if (typeof scanner.scanFile !== "function")
+    return;
+  try {
+    const result = scanner.scanFile(filePath);
+    if (Array.isArray(result))
+      items.push(...result);
+  } catch {}
+}
+async function collectTodoBaselineItems(scanner, analysisRoot, stillCurrent) {
+  const items = [];
+  try {
+    const { getSourceFilesAsync } = await import("./scan-utils.js");
+    const files = await getSourceFilesAsync(analysisRoot, true);
+    if (!stillCurrent())
+      return items;
+    const deadline = createDeadline(8);
+    for (const file of files) {
+      if (!stillCurrent())
+        return items;
+      scanOneTodoFile(scanner, file, items);
+      await yieldIfOverBudget(deadline);
+    }
+  } catch {
+    const todoResult = scanner.scanDirectory(analysisRoot);
+    items.push(...todoResult.items);
+  }
+  return items;
+}
+async function buildOrRefreshWordIndex(args) {
+  const { runtime, sessionGeneration, analysisRoot, snapshotRoot, dbg } = args;
+  if (!runtime.isCurrentSession(sessionGeneration))
+    return;
+  const startMs = Date.now();
+  let rebuildPreflightFiles;
+  const latestSeq = readLatestProjectSequence(snapshotRoot, snapshotSequenceBase(snapshotRoot));
+  const effectiveSeq = runtime.projectSeq ?? latestSeq.projectSeq;
+  const snapshotLoadStartMs = Date.now();
+  const snapshot = loadProjectSnapshot(snapshotRoot);
+  const snapshotLoadMs = Date.now() - snapshotLoadStartMs;
+  if (snapshot?.wordIndex) {
+    const { deserializeWordIndex, refreshWordIndexIncrementally, countWordIndexPostingEntries, estimateWordIndexResidentBytes } = await import("./word-index.js");
+    const deserializeStartMs = Date.now();
+    const index = deserializeWordIndex(snapshot.wordIndex);
+    const deserializeMs = Date.now() - deserializeStartMs;
+    if (index) {
+      try {
+        const result = await refreshWordIndexIncrementally(index, analysisRoot, () => runtime.isCurrentSession(sessionGeneration));
+        if (!runtime.isCurrentSession(sessionGeneration))
+          return;
+        if (result.mode === "full-required") {
+          rebuildPreflightFiles = result.preflightFiles;
+          dbg(`session_start word-index: incremental preflight selected full rebuild (${result.reason})`);
+          logWordIndex({
+            phase: "incremental_fallback",
+            cwd: snapshotRoot,
+            trigger: "session_start",
+            reason: result.reason,
+            phaseDurationsMs: {
+              snapshotLoadMs,
+              deserializeMs,
+              ...result.timings
+            }
+          });
+        } else {
+          runtime.wordIndex = index;
+          let snapshotSaveSyncMs = 0;
+          if (!isProjectSnapshotFresh(snapshot, effectiveSeq, latestSeq.unlockedThrough) || result.refreshed > 0 || result.dropped > 0 || snapshot.wordIndex.truncated !== index.truncated) {
+            const serializeSaveEnqueueStartMs = Date.now();
+            saveRuntimeProjectSnapshot({ cwd: snapshotRoot, runtime, dbg });
+            snapshotSaveSyncMs = Date.now() - serializeSaveEnqueueStartMs;
+          }
+          const phases = `snapshot-load=${snapshotLoadMs}ms, deserialize=${deserializeMs}ms, source-walk=${result.timings.sourceWalkMs}ms, stat-walk=${result.timings.statWalkMs}ms, refresh-reads=${result.timings.refreshReadsMs}ms, snapshot-save-sync=${snapshotSaveSyncMs}ms`;
+          dbg(`session_start word-index: incremental (seq=${effectiveSeq}, refreshed=${result.refreshed}, dropped=${result.dropped}, skipped=${result.skipped}, reused=${result.reused}, ${Date.now() - startMs}ms, phases: ${phases})`);
+          logWordIndex({
+            phase: "incremental_refresh",
+            cwd: snapshotRoot,
+            trigger: "session_start",
+            durationMs: Date.now() - startMs,
+            indexedFileCount: index.docCount,
+            tokens: index.postings.size,
+            postingEntries: countWordIndexPostingEntries(index),
+            residentBytes: estimateWordIndexResidentBytes(index),
+            truncated: index.truncated,
+            phaseDurationsMs: {
+              snapshotLoadMs,
+              deserializeMs,
+              ...result.timings,
+              snapshotSaveSyncMs
+            },
+            refreshed: result.refreshed,
+            dropped: result.dropped,
+            skipped: result.skipped,
+            reused: result.reused
+          });
+          return result;
+        }
+      } catch (err) {
+        if (!runtime.isCurrentSession(sessionGeneration)) {
+          dbg("session_start word-index: incremental refresh superseded");
+          return;
+        }
+        dbg(`session_start word-index: incremental refresh failed; falling back to full rebuild (${err})`);
+        logWordIndex({
+          phase: "incremental_fallback",
+          cwd: snapshotRoot,
+          trigger: "session_start",
+          reason: err instanceof Error ? err.message : String(err),
+          phaseDurationsMs: { snapshotLoadMs, deserializeMs }
+        });
+      }
+    }
+  }
+  const { buildWordIndexAsync, collectWordIndexDocs, countWordIndexPostingEntries, estimateWordIndexResidentBytes } = await import("./word-index.js");
+  const docs = await collectWordIndexDocs(analysisRoot, () => runtime.isCurrentSession(sessionGeneration), rebuildPreflightFiles);
+  if (!runtime.isCurrentSession(sessionGeneration))
+    return;
+  let rebuiltIndex;
+  try {
+    rebuiltIndex = await buildWordIndexAsync(docs, () => runtime.isCurrentSession(sessionGeneration));
+  } catch (err) {
+    if (!runtime.isCurrentSession(sessionGeneration)) {
+      dbg("session_start word-index: rebuild superseded");
+      return;
+    }
+    throw err;
+  }
+  if (!runtime.isCurrentSession(sessionGeneration))
+    return;
+  runtime.wordIndex = rebuiltIndex;
+  saveRuntimeProjectSnapshot({ cwd: snapshotRoot, runtime, dbg });
+  dbg(`session_start word-index: rebuilt (absent/stale, seq=${effectiveSeq}) ${runtime.wordIndex.docCount} files, ${runtime.wordIndex.postings.size} tokens (${Date.now() - startMs}ms)`);
+  logWordIndex({
+    phase: "full_rebuild",
+    cwd: snapshotRoot,
+    trigger: "session_start",
+    durationMs: Date.now() - startMs,
+    indexedFileCount: runtime.wordIndex.docCount,
+    tokens: runtime.wordIndex.postings.size,
+    postingEntries: countWordIndexPostingEntries(runtime.wordIndex),
+    residentBytes: estimateWordIndexResidentBytes(runtime.wordIndex),
+    truncated: runtime.wordIndex.truncated,
+    skipped: docs.skipped
+  });
+  return {
+    mode: "full",
+    refreshed: runtime.wordIndex.docCount,
+    dropped: 0,
+    skipped: docs.skipped,
+    reused: 0
+  };
+}
+function scheduleStartupScans(deps, runtime, sessionGeneration, analysisRoot, snapshotRoot, languageProfile, dbg) {
+  (async () => {
+    const resolved = await demandBootstrapDeps(deps, "session-start-scans");
+    if (!resolved) {
+      dbg("session_start scans: analyzer bootstrap unavailable — skipped");
+      return;
+    }
+    scheduleStartupScansWithClients(resolved, runtime, sessionGeneration, analysisRoot, snapshotRoot, languageProfile, dbg);
+  })();
+}
+function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analysisRoot, snapshotRoot, languageProfile, dbg) {
+  const { todoScanner, cacheManager, knipClient, jscpdClient, deadCodeClients, govulncheckClient, gitleaksClient, trivyClient, opengrepClient, astGrepClient, depChecker } = deps;
+  const analyzerEnabled = (flag) => !deps.getFlag(flag);
+  if (!analyzerEnabled("no-complexity")) {
+    dbg("session_start complexity: skipped (disabled by config)");
+    recordDegradationOnce({
+      kind: "startup-analyzer-disabled",
+      subject: "complexity",
+      reason: "skipped (disabled by config)"
+    });
+  }
+  const taskDeferMsByName = {
+    "call-graph": 5000,
+    "codebase-model": 5200,
+    "ast-grep exports": 5400,
+    "project index": 5400
+  };
+  const runTask = (name, task) => {
+    const queuedAt = Date.now();
+    dbg(`session_start task ${name}: scheduled`);
+    runtime.markStartupScanInFlight(name, sessionGeneration);
+    const completion = new Promise((resolve) => {
+      const fire = () => {
+        const startedAt = Date.now();
+        dbg(`session_start task ${name}: start queuedMs=${startedAt - queuedAt}`);
+        task().then(() => {
+          dbg(`session_start task ${name}: success runMs=${Date.now() - startedAt} queuedMs=${startedAt - queuedAt}`);
+        }).catch((err) => {
+          dbg(`session_start: ${name} background scan failed: ${err}`);
+          dbg(`session_start task ${name}: failed runMs=${Date.now() - startedAt} queuedMs=${startedAt - queuedAt}`);
+        }).finally(() => {
+          runtime.clearStartupScanInFlight(name, sessionGeneration);
+          dbg(`session_start task ${name}: end`);
+          resolve();
+        });
+      };
+      const delay = taskDeferMsByName[name] ?? 0;
+      if (delay > 0) {
+        setTimeout(fire, delay).unref?.();
+      } else {
+        setImmediate(fire);
+      }
+    });
+    return completion;
+  };
+  const canRunJsTsHeavyScans = canRunStartupHeavyScans(languageProfile, "jsts");
+  const scanNames = ["todo", "dead-code"];
+  if (canRunJsTsHeavyScans) {
+    scanNames.push("knip", "jscpd", "ast-grep exports", "project index");
+  }
+  dbg(`session_start: launching background scans (${scanNames.join(", ")})`);
+  runTask("todo", async () => {
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const items = await collectTodoBaselineItems(todoScanner, analysisRoot, () => runtime.isCurrentSession(sessionGeneration));
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    dbg(`session_start TODO scan: ${items.length} items (baseline stored)`);
+    cacheManager.writeCache("todo-baseline", { items }, analysisRoot);
+  });
+  if (!canRunJsTsHeavyScans) {
+    dbg("session_start: skipping JS/TS startup scans (requires JS/TS language + project config)");
+    return;
+  }
+  const isSubagent = isSubagentSession();
+  const skipHeavyweightScans = isSlowFs(analysisRoot) || isSubagent;
+  const runHeavyweightTask = (name, task) => {
+    const flag = `no-${name}`;
+    if (name !== "opengrep" && name !== "trivy" && !analyzerEnabled(flag)) {
+      dbg(`session_start ${name}: skipped (disabled by config)`);
+      recordDegradationOnce({
+        kind: "startup-analyzer-disabled",
+        subject: name,
+        reason: "skipped (disabled by config)"
+      });
+      return;
+    }
+    if (skipHeavyweightScans)
+      return;
+    runTask(name, task);
+  };
+  if (skipHeavyweightScans) {
+    dbg(`session_start: skipping knip/jscpd/madge/dead-code/govulncheck/gitleaks/trivy/opengrep (${isSubagent ? "subagent" : "slow-fs"})`);
+    deps.notify(`⏭️ Skipped background code-quality scans (knip/jscpd/madge/dead-code/govulncheck/gitleaks/trivy/opengrep): ${isSubagent ? subagentLightModeNotice() : slowFsDegradationNotice()}`, "info");
+  }
+  runHeavyweightTask("knip", async () => {
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("knip", analysisRoot);
+    if (cached) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start Knip: cache hit (${Math.round((Date.now() - new Date(cached.meta.timestamp).getTime()) / 1000)}s ago)`);
+    } else {
+      const startMs = Date.now();
+      const knipResult = await knipClient.analyze(analysisRoot, getKnipIgnorePatterns(), { projectSeq: runtime.projectSeq });
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      if (knipResult.success) {
+        cacheManager.writeCache("knip", knipResult, analysisRoot, {
+          scanDurationMs: Date.now() - startMs
+        });
+      }
+      dbg(`session_start Knip scan done (${Date.now() - startMs}ms)`);
+    }
+  });
+  runHeavyweightTask("jscpd", async () => {
+    if (await jscpdClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      const isTsProject = nodeFs.existsSync(path.join(analysisRoot, "tsconfig.json"));
+      const scannerKey = isTsProject ? "jscpd-ts" : "jscpd";
+      const cached = cacheManager.readCache(scannerKey, analysisRoot);
+      if (cached) {
+        if (!runtime.isCurrentSession(sessionGeneration))
+          return;
+        dbg(`session_start jscpd: cache hit (${scannerKey})`);
+      } else {
+        const startMs = Date.now();
+        const jscpdResult = await jscpdClient.scan(analysisRoot, undefined, undefined, isTsProject);
+        if (!runtime.isCurrentSession(sessionGeneration))
+          return;
+        if (jscpdResult.success) {
+          cacheManager.writeCache(scannerKey, jscpdResult, analysisRoot, {
+            scanDurationMs: Date.now() - startMs
+          });
+        }
+        dbg(`session_start jscpd scan done (${Date.now() - startMs}ms, isTsProject=${isTsProject})`);
+      }
+    } else {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start jscpd: not available");
+    }
+  });
+  runHeavyweightTask("dead-code", async () => {
+    const applicable = deadCodeClients.filter((c) => c.detect(analysisRoot));
+    if (applicable.length === 0)
+      return;
+    await Promise.all(applicable.map(async (client) => {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      const cacheKey = `dead-code-${client.id}`;
+      const cached = cacheManager.readCache(cacheKey, analysisRoot);
+      if (cached) {
+        dbg(`session_start dead-code(${client.id}): cache hit`);
+        return;
+      }
+      const startMs = Date.now();
+      const result = await client.analyze(analysisRoot);
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      if (result.success) {
+        cacheManager.writeCache(cacheKey, result, analysisRoot, {
+          scanDurationMs: Date.now() - startMs
+        });
+      }
+      logDeadCodeScan({
+        language: client.language,
+        success: result.success,
+        cached: false,
+        unusedExports: result.unusedExports.length,
+        unusedFiles: result.unusedFiles.length,
+        unusedDeps: result.unusedDeps.length,
+        unlistedDeps: result.unlistedDeps.length,
+        durationMs: result.durationMs ?? Date.now() - startMs,
+        ...!result.success && { reason: result.summary }
+      });
+      dbg(`session_start dead-code(${client.id}) done (${Date.now() - startMs}ms, ${deadCodeIssueCount(result)} issues)`);
+    }));
+  });
+  runHeavyweightTask("govulncheck", async () => {
+    if (!GovulncheckClient.hasGoModule(analysisRoot)) {
+      dbg("session_start govulncheck: no go.mod — skipped");
+      return;
+    }
+    if (!await govulncheckClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start govulncheck: not installed (go install golang.org/x/vuln/cmd/govulncheck@latest)");
+      return;
+    }
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("govulncheck", analysisRoot);
+    if (cached) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start govulncheck: cache hit (${cached.data.findings.length} findings)`);
+      return;
+    }
+    const startMs = Date.now();
+    const result = await govulncheckClient.analyze(analysisRoot);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    if (result.success) {
+      cacheManager.writeCache("govulncheck", result, analysisRoot, {
+        scanDurationMs: Date.now() - startMs
+      });
+    }
+    dbg(`session_start govulncheck: ${result.findings.length} reachable findings (${Date.now() - startMs}ms)`);
+  });
+  runHeavyweightTask("gitleaks", async () => {
+    if (!GitleaksClient.hasGitleaksSignal(analysisRoot)) {
+      dbg("session_start gitleaks: no opt-in signal — skipped");
+      return;
+    }
+    if (!await gitleaksClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start gitleaks: not available (install failed?)");
+      return;
+    }
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("gitleaks", analysisRoot);
+    if (cached) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start gitleaks: cache hit (${cached.data.findings.length} findings)`);
+      return;
+    }
+    const startMs = Date.now();
+    const result = await gitleaksClient.scan(analysisRoot);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    if (result.success) {
+      cacheManager.writeCache("gitleaks", result, analysisRoot, {
+        scanDurationMs: Date.now() - startMs
+      });
+    }
+    dbg(`session_start gitleaks: ${result.findings.length} findings (${Date.now() - startMs}ms)`);
+  });
+  runHeavyweightTask("opengrep", async () => {
+    if (!await opengrepClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start opengrep: not available (install failed?)");
+      return;
+    }
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("opengrep", analysisRoot);
+    if (cached) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start opengrep: cache hit (${cached.data.findings.length} findings)`);
+      return;
+    }
+    const startMs = Date.now();
+    const result = await opengrepClient.scan(analysisRoot);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    if (result.success) {
+      cacheManager.writeCache("opengrep", result, analysisRoot, {
+        scanDurationMs: Date.now() - startMs
+      });
+    }
+    dbg(`session_start opengrep: ${result.findings.length} findings (${Date.now() - startMs}ms)`);
+  });
+  runHeavyweightTask("madge", async () => {
+    if (!await depChecker.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start madge: not available");
+      return;
+    }
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("madge", analysisRoot);
+    if (cached) {
+      dbg(`session_start madge: cache hit (${cached.data.circular.length} cycles)`);
+      return;
+    }
+    const startMs = Date.now();
+    const result = await depChecker.scanProject(analysisRoot);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    cacheManager.writeCache("madge", result, analysisRoot, {
+      scanDurationMs: Date.now() - startMs
+    });
+    dbg(`session_start madge: ${result.circular.length} circular dependency chain(s) (${Date.now() - startMs}ms)`);
+  });
+  runHeavyweightTask("trivy", async () => {
+    if (!TrivyClient.shouldScan(analysisRoot)) {
+      dbg("session_start trivy: not enabled / no dependency manifest — skipped");
+      return;
+    }
+    if (!await trivyClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg("session_start trivy: not available (install failed?)");
+      return;
+    }
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const cached = cacheManager.readCache("trivy", analysisRoot);
+    if (cached) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start trivy: cache hit (${cached.data.findings.length} findings)`);
+      return;
+    }
+    const startMs = Date.now();
+    const result = await trivyClient.scan(analysisRoot);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    if (result.success) {
+      cacheManager.writeCache("trivy", result, analysisRoot, {
+        scanDurationMs: Date.now() - startMs
+      });
+    }
+    dbg(`session_start trivy: ${result.findings.length} CVE findings (${Date.now() - startMs}ms)`);
+  });
+  let callGraphIdentity;
+  const callGraphTask = runTask("call-graph", async () => {
+    const { FactStore } = await import("./dispatch/fact-store.js");
+    const { buildOrUpdateGraph, extractSymbolsAndRefsFromGraph, getReviewGraphCacheIdentity } = await import("./review-graph/builder.js");
+    const { buildCallGraph, saveCallGraph, loadCallGraph } = await import("./call-graph.js");
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const startMs = Date.now();
+    const sessionFacts = new FactStore("runtime-session-call-graph");
+    const graph = await buildOrUpdateGraph(analysisRoot, [], sessionFacts);
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    const identity = getReviewGraphCacheIdentity(analysisRoot, graph);
+    if (!identity) {
+      dbg("session_start call-graph: canonical review-graph identity unavailable");
+      return;
+    }
+    callGraphIdentity = {
+      reviewGraphVersion: identity.version,
+      reviewGraphSignature: identity.signature
+    };
+    const cached = loadCallGraph(snapshotRoot, {
+      reviewGraphVersion: identity.version,
+      reviewGraphSignature: identity.signature
+    });
+    if (cached) {
+      runtime.callGraph = cached.graph;
+      dbg(`session_start call-graph: loaded from cache (${cached.graph.edges.length} edges, ${cached.graph.callers.size} callee entries, ${Date.now() - startMs}ms)`);
+      return;
+    }
+    const { allSymbols, allRefs, coverage } = extractSymbolsAndRefsFromGraph(graph);
+    const callGraph = buildCallGraph(allSymbols, allRefs, coverage);
+    runtime.callGraph = callGraph;
+    saveCallGraph(snapshotRoot, callGraph, {
+      reviewGraphVersion: identity.version,
+      reviewGraphSignature: identity.signature
+    });
+    dbg(`session_start call-graph: built ${callGraph.edges.length} edges, ${callGraph.callers.size} callee entries (${Date.now() - startMs}ms)`);
+  });
+  runTask("codebase-model", async () => {
+    await callGraphTask;
+    if (!runtime.isCurrentSession(sessionGeneration))
+      return;
+    if (!runtime.callGraph)
+      return;
+    const { buildCodebaseModel, saveCodebaseModel, DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET } = await import("./codebase-model.js");
+    if (!callGraphIdentity)
+      return;
+    const model = buildCodebaseModel(runtime.callGraph, analysisRoot, DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET, callGraphIdentity);
+    saveCodebaseModel(snapshotRoot, model);
+    const top3 = model.entries.slice(0, 3).map((e) => e.name).join(", ");
+    dbg(`session_start codebase-model: ${model.entries.length} entries, ${model.totalTokens} tokens, top symbols: ${top3 || "(none)"}`);
+  });
+  runTask("ast-grep-exports", async () => {
+    if (await astGrepClient.ensureAvailable()) {
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      const exports = await astGrepClient.scanExports(analysisRoot, "typescript");
+      if (!runtime.isCurrentSession(sessionGeneration))
+        return;
+      dbg(`session_start exports scan: ${exports.size} functions found`);
+      for (const [name, file] of exports) {
+        runtime.cachedExports.set(name, file);
+      }
+      saveRuntimeProjectSnapshot({ cwd: snapshotRoot, runtime, dbg });
+    }
+  });
+  runTask("word-index", async () => {
+    await buildOrRefreshWordIndex({
+      runtime,
+      sessionGeneration,
+      analysisRoot,
+      snapshotRoot,
+      dbg
+    });
+  });
+}
+function scheduleDeferredToolProbes(deps, languageProfile, startupDefaults, startupScansWillRun, dbg) {
+  (async () => {
+    const resolved = await demandBootstrapDeps(deps, "session-start-tool-probes");
+    if (!resolved) {
+      dbg("session_start tools: analyzer bootstrap unavailable — no probes");
+      return;
+    }
+    scheduleDeferredToolProbesWithClients(resolved, languageProfile, startupDefaults, startupScansWillRun, dbg);
+  })();
+}
+function scheduleDeferredToolProbesWithClients(deps, languageProfile, startupDefaults, startupScansWillRun, dbg) {
+  const { biomeClient, ruffClient, depChecker } = deps;
+  const defaultTools = new Set(startupDefaults);
+  const probes = [];
+  if (languageProfile.present.jsts && !defaultTools.has("biome")) {
+    probes.push(["biome", () => biomeClient.ensureAvailable()]);
+  }
+  if (languageProfile.present.python && !defaultTools.has("ruff")) {
+    probes.push(["ruff", () => ruffClient.ensureAvailable()]);
+  }
+  if (startupScansWillRun) {
+    probes.push(["madge", () => depChecker.ensureAvailable()]);
+  }
+  if (probes.length === 0) {
+    dbg("session_start tools: no deferred availability probes needed");
+    return;
+  }
+  (async () => {
+    const warmStart = Date.now();
+    const results = await Promise.all(probes.map(async ([name, run]) => {
+      try {
+        return [name, await run()];
+      } catch (err) {
+        dbg(`session_start: ${name} availability check failed: ${err}`);
+        return [name, false];
+      }
+    }));
+    const summary = results.map(([name, ready]) => `${name}=${ready}`).join(" ");
+    dbg(`session_start tools (deferred probes complete, ${Date.now() - warmStart}ms): ${summary}`);
+  })();
+}
+function readSubstituteGuidance(isEnabled) {
+  const units = [];
+  if (isEnabled("symbol_search")) {
+    units.push({ name: "symbol_search", role: "ranked identifier search" });
+  }
+  if (isEnabled("module_report")) {
+    units.push({
+      name: "module_report",
+      role: "navigable outline/callback handles"
+    });
+  }
+  const readSymbol = isEnabled("read_symbol");
+  const readEnclosing = isEnabled("read_enclosing");
+  if (readSymbol && readEnclosing) {
+    units.push({
+      name: "read_symbol/read_enclosing",
+      role: "exact body reads"
+    });
+  } else if (readSymbol) {
+    units.push({ name: "read_symbol", role: "exact body reads" });
+  } else if (readEnclosing) {
+    units.push({ name: "read_enclosing", role: "exact body reads" });
+  }
+  if (units.length === 0)
+    return;
+  const roles = units.map((unit) => unit.role);
+  const roleTail = roles.length === 1 ? roles[0] : roles.length === 2 ? `${roles[0]}, then ${roles[1]}` : `${roles[0]}, then ${roles[1]} + ${roles[2]}`;
+  return `• ${units.map((unit) => unit.name).join(" → ")} — ${roleTail}; cheaper than reading a whole file before editing.`;
+}
+function situationalGuidance(isEnabled) {
+  const active = [];
+  for (const name of [
+    "lsp_navigation",
+    "ast_grep_search",
+    "ast_grep_replace"
+  ]) {
+    if (isEnabled(name))
+      active.push(name);
+  }
+  if (active.length === 0)
+    return;
+  let text = `• Situational (activate via dm_lens_activate_tools): ${active.join(", ")}.`;
+  if (isEnabled("ast_grep_search")) {
+    text += " Use ast_grep_search with dump=true to inspect AST nodes.";
+  }
+  return text;
+}
+export function renderSessionStartGuidance(options = {}) {
+  const disabled = new Set(options.disabledToolNames ?? []);
+  const isEnabled = (name) => !disabled.has(name);
+  const requirePreExistingFixes = options.requirePreExistingFixes !== false;
+  const header = "\uD83D\uDCCC dm-lens active — automated checks run on every edit/write; " + (requirePreExistingFixes ? "blocking errors (including pre-existing) show inline and must be fixed." : "blocking errors you introduce must be fixed; pre-existing ones are only reported.");
+  const bullets = [];
+  if (isEnabled("lens_diagnostics")) {
+    bullets.push("• lens_diagnostics — source=session reads cache; empty cache ≠ clean; use source=lsp scope=paths for changed files with absent or stale findings (aggregate hosts: lens(action=diagnostics)).");
+  }
+  const readSubstitute = readSubstituteGuidance(isEnabled);
+  if (readSubstitute)
+    bullets.push(readSubstitute);
+  const situational = situationalGuidance(isEnabled);
+  if (situational)
+    bullets.push(situational);
+  const lines = [header];
+  if (bullets.length > 0) {
+    lines.push("Key tools (see each tool's own description for args):");
+    lines.push(...bullets);
+  }
+  return [lines.join(`
+`)];
+}
+export const SESSION_START_GUIDANCE = renderSessionStartGuidance();
+export async function handleSessionStart(deps) {
+  resetDegradationLedger();
+  let sessionGenerationAtStart = deps.runtime.sessionGeneration;
+  resetAnalyzerBootstrapSessionState();
+  resetProjectDataDirSessionState();
+  resetTestRunnerDelivery();
+  resetLspMutationNoBridgeDbgLatch();
+  resetBoundedTelemetry();
+  rotateMessageEndAttribution();
+  const handlerEnteredAt = Date.now();
+  const sessionStartMs = deps.sessionStartFiredAt ?? handlerEnteredAt;
+  const cwdForTelemetry = deps.ctxCwd ?? process.cwd();
+  if (deps.sessionStartFiredAt !== undefined) {
+    logLatency({
+      type: "phase",
+      filePath: cwdForTelemetry,
+      phase: "session_start_prehandler",
+      startedAt: new Date(deps.sessionStartFiredAt).toISOString(),
+      durationMs: (deps.handlerEnteredAt ?? handlerEnteredAt) - deps.sessionStartFiredAt,
+      metadata: { reason: deps.sessionReason }
+    });
+  }
+  let startupMode = resolveStartupMode(deps.projectConfig, deps.globalConfig);
+  const processGlobals = globalThis;
+  const isFirstSessionOfProcess = !processGlobals.__piLensFirstSessionDone;
+  if (isFirstSessionOfProcess && process.env.DM_LENS_COLD_START_QUICK !== "0" && !process.env.DM_LENS_STARTUP_MODE && !deps.projectConfig?.startup?.mode && !deps.globalConfig?.startup?.mode) {
+    startupMode = deps.startupModeOverride ?? "quick";
+  }
+  processGlobals.__piLensFirstSessionDone = true;
+  let warmupOwnSnapshotRead;
+  if (startupMode === "quick" && !isPrintMode() && process.env.DM_LENS_COLD_START_QUICK !== "0" && !processGlobals.__piLensWarmupScheduled) {
+    processGlobals.__piLensWarmupScheduled = true;
+    const warmupDelayMs = Number(process.env.DM_LENS_WARMUP_DELAY_MS ?? 2000);
+    const warmupCwd = deps.ctxCwd ?? process.cwd();
+    const warmupDbg = deps.dbg;
+    const warmupTimer = setTimeout(() => {
+      const warmupStartedAt = Date.now();
+      (async () => {
+        try {
+          warmupDbg("warmup: starting background warmup");
+          const scanContextStartedAt = Date.now();
+          const startupScanModule = await import("./startup-scan.js");
+          const languageProfileModule = await import("./language-profile.js");
+          const warmupSnapshotRoot = resolveSnapshotRoot(warmupCwd);
+          const cachedSnapshot = loadProjectSnapshot(warmupSnapshotRoot);
+          warmupOwnSnapshotRead = cachedSnapshot ? {
+            version: cachedSnapshot.version,
+            seq: cachedSnapshot.seq,
+            cachedExports: cachedSnapshot.cachedExports,
+            projectRulesScan: cachedSnapshot.projectRulesScan
+          } : null;
+          const cachedVerdict = cachedSnapshot?.startupScan;
+          let scan;
+          if (cachedVerdict && startupScanModule.isStartupScanVerdictFresh(cachedVerdict)) {
+            scan = { ...cachedVerdict, cwd: path.resolve(warmupCwd) };
+            warmupDbg(`warmup: scan-context reused from cache (canWarm=${scan.canWarmCaches}${scan.reason ? `, reason=${scan.reason}` : ""})`);
+          } else {
+            scan = await startupScanModule.resolveStartupScanContextAsync(warmupCwd);
+            logLatency({
+              type: "phase",
+              phase: "session_start_scan_context_compute",
+              filePath: warmupCwd,
+              startedAt: new Date(scanContextStartedAt).toISOString(),
+              durationMs: Date.now() - scanContextStartedAt,
+              metadata: { mode: "quick-background" }
+            });
+            warmupDbg(`warmup: scan-context done in ${Date.now() - warmupStartedAt}ms (canWarm=${scan.canWarmCaches})`);
+            saveRuntimeProjectSnapshot({
+              cwd: warmupSnapshotRoot,
+              runtime: deps.runtime,
+              startupScan: scan,
+              dbg: warmupDbg
+            });
+          }
+          logLatency({
+            type: "phase",
+            phase: "warmup_scan_context",
+            filePath: warmupCwd,
+            startedAt: new Date(scanContextStartedAt).toISOString(),
+            durationMs: Date.now() - scanContextStartedAt
+          });
+          if (!scan.canWarmCaches) {
+            warmupDbg(`warmup: skipping language-profile (canWarm=false, reason=${scan.reason ?? "unknown"})`);
+            notifyStartupWarmSkip({
+              scan,
+              analysisRoot: scan.projectRoot ?? warmupCwd,
+              notify: deps.notify,
+              runtime: deps.runtime,
+              sessionGeneration: sessionGenerationAtStart
+            });
+            return;
+          }
+          const languageRoot = scan.projectRoot ?? warmupCwd;
+          const languageProfileStartedAt = Date.now();
+          await languageProfileModule.detectProjectLanguageProfileAsync(languageRoot);
+          warmupDbg(`warmup: language-profile done in ${Date.now() - languageProfileStartedAt}ms`);
+          logLatency({
+            type: "phase",
+            phase: "warmup_language_profile",
+            filePath: warmupCwd,
+            startedAt: new Date(languageProfileStartedAt).toISOString(),
+            durationMs: Date.now() - languageProfileStartedAt
+          });
+          const wordIndexStartedAt = Date.now();
+          const wordIndexResult = await buildOrRefreshWordIndex({
+            runtime: deps.runtime,
+            sessionGeneration: deps.runtime.sessionGeneration,
+            analysisRoot: languageRoot,
+            snapshotRoot: warmupSnapshotRoot,
+            dbg: warmupDbg
+          });
+          warmupDbg(`warmup: word-index done in ${Date.now() - wordIndexStartedAt}ms`);
+          logLatency({
+            type: "phase",
+            phase: "warmup_word_index",
+            filePath: warmupCwd,
+            startedAt: new Date(wordIndexStartedAt).toISOString(),
+            durationMs: Date.now() - wordIndexStartedAt,
+            metadata: wordIndexResult ? { ...wordIndexResult } : undefined
+          });
+          const lspPrewarmStartedAt = Date.now();
+          if (deps.getFlag("no-lsp")) {
+            warmupDbg("warmup: skipping LSP pre-warm (no-lsp)");
+          } else if (isSubagentSession()) {
+            warmupDbg("warmup: skipping LSP pre-warm (subagent session)");
+          } else if (isWarmAttached()) {
+            warmupDbg("warmup: skipping LSP pre-warm (attached to incumbent)");
+          } else {
+            const lspConfig = await loadLSPConfig(warmupCwd).catch(() => ({
+              warmFiles: []
+            }));
+            const warmFiles = lspConfig.warmFiles ?? [];
+            if (warmFiles.length > 0) {
+              await igniteWarmFiles(warmupCwd, warmFiles, deps.runtime, deps.runtime.sessionGeneration, warmupDbg);
+            } else {
+              await igniteDominantLanguageWarm(languageRoot, deps.runtime, deps.runtime.sessionGeneration, warmupDbg);
+            }
+            logLatency({
+              type: "phase",
+              phase: "warmup_lsp_prewarm",
+              filePath: warmupCwd,
+              startedAt: new Date(lspPrewarmStartedAt).toISOString(),
+              durationMs: Date.now() - lspPrewarmStartedAt
+            });
+            warmupDbg(`warmup: lsp-prewarm done in ${Date.now() - lspPrewarmStartedAt}ms`);
+          }
+          warmupDbg(`warmup: total ${Date.now() - warmupStartedAt}ms`);
+        } catch (err) {
+          warmupDbg(`warmup: error ${err}`);
+          processGlobals.__piLensWarmupScheduled = false;
+        } finally {
+          logLatency({
+            type: "phase",
+            phase: "warmup_total",
+            filePath: warmupCwd,
+            startedAt: new Date(warmupStartedAt).toISOString(),
+            durationMs: Date.now() - warmupStartedAt
+          });
+        }
+      })();
+    }, warmupDelayMs);
+    warmupTimer.unref?.();
+  }
+  const allowBootstrapTasks = startupMode === "full";
+  const quickMode = startupMode === "quick";
+  const { ctxCwd, getFlag, notify, dbg, log, runtime, cacheManager, ensureTool, cleanStaleTsBuildInfo, resetDispatchBaselines, resetLSPService } = deps;
+  let _phaseT = Date.now();
+  const phase = (name) => {
+    dbg(`session_start phase ${name}: ${Date.now() - _phaseT}ms`);
+    _phaseT = Date.now();
+  };
+  deps.bootstrap.peek()?.metricsClient.reset();
+  getDiagnosticTracker().reset();
+  clearFileTimeSessions();
+  runtime.complexityBaselines.clear();
+  resetDispatchBaselines(ctxCwd);
+  resetWorkspaceTopology();
+  resetOpaqueMutationState();
+  resetObservedMutationNet();
+  resetMutationAttribution();
+  primePersistedMutationAttribution(ctxCwd);
+  resetPendingAuxiliaryCoverage();
+  resetSafeSpawnWindowsCommandCache();
+  resetDispatchAvailabilityState();
+  resetObservedRunnerLatency();
+  resetPendingRunnerFindings();
+  resetSpawnTimeoutCooldowns();
+  clearFormatterCache();
+  resetZizmorTokenAvailability();
+  resetGoAvailability();
+  resetRustAvailability();
+  resetPsScriptAnalyzerAvailability();
+  resetInstallRetryLatches();
+  resetLazyInstallAttempts();
+  resetDirectLspCommandAvailability();
+  resetLSPCaseSensitivityState();
+  resetResolvedPathCache();
+  _resetPackageManagerCache();
+  resetManagedToolRefreshSession();
+  resetSmellsSessionState();
+  resetSituationalToolTelemetry();
+  resetWorkspaceDiagnosticsCacheSession(sessionStartMs);
+  deps.bootstrap.peek()?.knipClient.resetSessionState?.();
+  resetCascadeTierSessionState();
+  runtime.resetForSession(sessionStartMs);
+  sessionGenerationAtStart = runtime.sessionGeneration;
+  logLatency({
+    type: "phase",
+    phase: "session_start_runtime_reset",
+    filePath: ctxCwd ?? process.cwd(),
+    startedAt: new Date(handlerEnteredAt).toISOString(),
+    durationMs: Date.now() - handlerEnteredAt,
+    metadata: { mode: startupMode, reason: deps.sessionReason }
+  });
+  const cleanupCwd = ctxCwd ?? process.cwd();
+  setImmediate(() => {
+    const logCleanupStartedAt = Date.now();
+    try {
+      const logCleanup = runLogCleanup(dbg);
+      logLatency({
+        type: "phase",
+        phase: "session_start_log_cleanup",
+        filePath: cleanupCwd,
+        startedAt: new Date(logCleanupStartedAt).toISOString(),
+        durationMs: Date.now() - logCleanupStartedAt,
+        metadata: {
+          mode: startupMode,
+          reason: deps.sessionReason,
+          deferred: true
+        }
+      });
+      if (logCleanup.cleaned > 0 || logCleanup.rotated > 0) {
+        notify(`\uD83E\uDDF9 ${logCleanup.report}`, "info");
+      }
+    } catch (err) {
+      dbg(`session_start: deferred log cleanup failed: ${err}`);
+    }
+  });
+  dbg(`session_start startup mode: ${startupMode}`);
+  if (!getFlag("no-lsp")) {
+    resetLSPService({ fast: true, reason: "session_start" });
+    dbg("session_start: LSP service reset");
+    dbg("session_start: phase0 workspace diagnostics observation enabled (capability probe only)");
+  }
+  const hasWorkspaceCwd = typeof ctxCwd === "string" && ctxCwd.length > 0;
+  const cwd = ctxCwd ?? process.cwd();
+  const projectDataDir = getProjectDataDir(cwd);
+  for (const migration of drainProjectDataDirMigrations()) {
+    const targetName = path.basename(migration.to);
+    const hash = targetName.match(/([0-9a-f]{8})$/)?.[1] ?? "unknown";
+    if (migration.outcome === "ephemeral") {
+      recordDegradationOnce({
+        kind: "data-dir-ephemeral",
+        subject: hash,
+        reason: "temporary checkout: project data lives in a process-owned directory and is not kept after exit"
+      });
+      continue;
+    }
+    recordDegradationOnce({
+      kind: "data_dir_migrated",
+      subject: hash,
+      reason: migration.outcome === "renamed" ? "using hashed directory after renaming legacy directory" : migration.outcome === "coexisting" ? "using hashed directory because legacy and hashed directories both exist" : migration.outcome === "rename-failed" ? "using legacy directory after hashed-directory rename failure" : "using resolved directory after realpath fallback"
+    });
+  }
+  const globalDir = getGlobalDmLensDir();
+  sweepAtomicWriteStages([
+    projectDataDir,
+    path.join(projectDataDir, "cache"),
+    path.join(projectDataDir, "sessions"),
+    globalDir,
+    path.join(globalDir, "bin"),
+    path.join(globalDir, "tools")
+  ]).catch(() => {});
+  sweepDeadEphemeralDataDirs({ isPidAlive: realIsPidAlive }).catch(() => {});
+  if (quickMode) {
+    runtime.projectRoot = cwd;
+    const sequenceReadStartedAt = Date.now();
+    const snapshotRoot = resolveSnapshotRoot(cwd);
+    const { latestSeq, timedOut } = await readSequenceWithBudget({
+      snapshotRoot,
+      base: snapshotSequenceBase(snapshotRoot),
+      cwd,
+      runtime,
+      sessionGeneration: runtime.sessionGeneration,
+      dbg,
+      onDeferredSequenceResolved: retroactivelyHydrateAfterDeferredSequence({
+        getWarmupOwnSnapshotRead: () => warmupOwnSnapshotRead,
+        snapshotRoot,
+        runtime,
+        dbg
+      })
+    });
+    logLatency({
+      type: "phase",
+      phase: "session_start_sequence_read",
+      filePath: cwd,
+      startedAt: new Date(sequenceReadStartedAt).toISOString(),
+      durationMs: Date.now() - sequenceReadStartedAt,
+      metadata: { entries: latestSeq.fileSeqByPath.size, timedOut }
+    });
+    if (timedOut) {
+      recordSnapshotSequenceTimeout({
+        snapshotRoot,
+        snapshotPath: getProjectSnapshotPath(snapshotRoot)
+      });
+    }
+    runtime.seedProjectSequence?.(latestSeq.projectSeq, latestSeq.fileSeqByPath, latestSeq.logEntries);
+    const effectiveSeq = runtime.projectSeq ?? latestSeq.projectSeq;
+    dbg(`session_start sequence: projectSeq=${effectiveSeq} fileSeqEntries=${latestSeq.fileSeqByPath.size}`);
+    const freshnessSeq = timedOut ? UNKNOWN_PROJECT_SEQ : effectiveSeq;
+    const snapshotLoadStartedAt = Date.now();
+    const snapshotPath = getProjectSnapshotPath(snapshotRoot);
+    let snapshotBytes = 0;
+    try {
+      snapshotBytes = nodeFs.statSync(snapshotPath).size;
+    } catch {}
+    const snapshotBodyPresent = nodeFs.existsSync(snapshotPath) || nodeFs.existsSync(getProjectSnapshotLegacyPath(snapshotRoot));
+    const snapshotGate = loadSnapshotBodyUnlessStale({
+      root: snapshotRoot,
+      currentProjectSeq: freshnessSeq,
+      unlockedThrough: latestSeq.unlockedThrough ?? 0,
+      dbg
+    });
+    const snapshot = snapshotGate.snapshot;
+    const snapshotFresh = isProjectSnapshotFresh(snapshot, freshnessSeq, latestSeq.unlockedThrough);
+    const snapshotMissReason = describeSnapshotMiss(snapshot, freshnessSeq, {
+      skippedStale: snapshotGate.skippedStale,
+      bodyPresent: snapshotBodyPresent,
+      unlockedThrough: latestSeq.unlockedThrough ?? 0
+    });
+    logLatency({
+      type: "phase",
+      phase: "session_start_snapshot_load",
+      filePath: cwd,
+      startedAt: new Date(snapshotLoadStartedAt).toISOString(),
+      durationMs: Date.now() - snapshotLoadStartedAt,
+      metadata: {
+        bytes: snapshotBytes,
+        fresh: snapshotFresh,
+        seq: snapshot?.seq ?? null,
+        reason: snapshotFresh ? undefined : snapshotMissReason,
+        ...snapshotGate.skippedStale ? { skippedStale: true } : {},
+        ...timedOut ? { sequenceUnknown: true } : {}
+      }
+    });
+    logProjectSnapshotProbe({
+      dbg,
+      root: snapshotRoot,
+      currentProjectSeq: freshnessSeq,
+      unlockedThrough: latestSeq.unlockedThrough ?? 0,
+      snapshot,
+      missReason: snapshotMissReason
+    });
+    if (snapshotFresh) {
+      hydrateRuntimeFromProjectSnapshot(runtime, snapshot);
+    }
+    const quickTools = [];
+    if (!getFlag("no-lsp")) {
+      quickTools.push("LSP Service");
+    }
+    log(`Active tools: ${quickTools.join(", ")}`);
+    dbg(`session_start tools: ${quickTools.join(", ") || "deferred (quick mode)"}`);
+    dbg("session_start: quick mode active - skipping slow tool probes, language profiling, preinstall, scans, and error debt baseline");
+    logLatency({
+      type: "phase",
+      phase: "session_start_skipped_steps",
+      filePath: cwd,
+      durationMs: 0,
+      metadata: {
+        mode: startupMode,
+        reason: deps.sessionReason,
+        steps: [
+          "slow_tool_probes",
+          "language_profiling",
+          "tool_preinstall",
+          "startup_scans",
+          "error_debt_baseline"
+        ]
+      }
+    });
+    const totalDurationMs = Date.now() - sessionStartMs;
+    dbg(`session_start total: ${totalDurationMs}ms (interactive path)`);
+    logLatency({
+      type: "phase",
+      phase: "session_start_total",
+      filePath: cwd,
+      startedAt: new Date(sessionStartMs).toISOString(),
+      durationMs: totalDurationMs,
+      metadata: {
+        mode: startupMode,
+        reason: deps.sessionReason,
+        ...sessionStartDecisionMetadata(deps)
+      }
+    });
+    logHostReadyDelay(deps, cwd);
+    emitSmellsSessionStartLine(dbg, sessionStartMs);
+    return;
+  }
+  const tools = [];
+  if (!getFlag("no-lsp"))
+    tools.push("LSP Service");
+  if (allowBootstrapTasks && !getFlag("no-lsp")) {
+    const cleaned = cleanStaleTsBuildInfo(ctxCwd ?? process.cwd());
+    if (cleaned.length > 0) {
+      notify(`\uD83E\uDDF9 Deleted stale TypeScript build cache (${cleaned.map((f) => path.basename(f)).join(", ")}) — phantom errors suppressed.`, "warning");
+      dbg(`session_start: cleaned stale tsbuildinfo: ${cleaned.join(", ")}`);
+    }
+  }
+  const sessionGeneration = runtime.sessionGeneration;
+  const sequenceReadStartedAt = Date.now();
+  const snapshotRoot = resolveSnapshotRoot(cwd);
+  const { latestSeq, timedOut } = await readSequenceWithBudget({
+    snapshotRoot,
+    base: snapshotSequenceBase(snapshotRoot),
+    cwd,
+    runtime,
+    sessionGeneration,
+    dbg
+  });
+  logLatency({
+    type: "phase",
+    phase: "session_start_sequence_read",
+    filePath: cwd,
+    startedAt: new Date(sequenceReadStartedAt).toISOString(),
+    durationMs: Date.now() - sequenceReadStartedAt,
+    metadata: { entries: latestSeq.fileSeqByPath.size, timedOut }
+  });
+  if (timedOut) {
+    recordSnapshotSequenceTimeout({
+      snapshotRoot,
+      snapshotPath: getProjectSnapshotPath(snapshotRoot)
+    });
+  }
+  runtime.seedProjectSequence?.(latestSeq.projectSeq, latestSeq.fileSeqByPath, latestSeq.logEntries);
+  const effectiveSeq = runtime.projectSeq ?? latestSeq.projectSeq;
+  dbg(`session_start sequence: projectSeq=${effectiveSeq} fileSeqEntries=${latestSeq.fileSeqByPath.size}`);
+  const freshnessSeq = timedOut ? UNKNOWN_PROJECT_SEQ : effectiveSeq;
+  const snapshotLoadStartedAt = Date.now();
+  const snapshotPath = getProjectSnapshotPath(snapshotRoot);
+  let snapshotBytes = 0;
+  try {
+    snapshotBytes = nodeFs.statSync(snapshotPath).size;
+  } catch {}
+  const snapshotBodyPresent = nodeFs.existsSync(snapshotPath) || nodeFs.existsSync(getProjectSnapshotLegacyPath(snapshotRoot));
+  const snapshotGate = loadSnapshotBodyUnlessStale({
+    root: snapshotRoot,
+    currentProjectSeq: freshnessSeq,
+    unlockedThrough: latestSeq.unlockedThrough ?? 0,
+    dbg
+  });
+  const snapshot = snapshotGate.snapshot;
+  const snapshotFresh = isProjectSnapshotFresh(snapshot, freshnessSeq, latestSeq.unlockedThrough);
+  const snapshotMissReason = describeSnapshotMiss(snapshot, freshnessSeq, {
+    skippedStale: snapshotGate.skippedStale,
+    bodyPresent: snapshotBodyPresent,
+    unlockedThrough: latestSeq.unlockedThrough ?? 0
+  });
+  logLatency({
+    type: "phase",
+    phase: "session_start_snapshot_load",
+    filePath: cwd,
+    startedAt: new Date(snapshotLoadStartedAt).toISOString(),
+    durationMs: Date.now() - snapshotLoadStartedAt,
+    metadata: {
+      bytes: snapshotBytes,
+      fresh: snapshotFresh,
+      seq: snapshot?.seq ?? null,
+      reason: snapshotFresh ? undefined : snapshotMissReason,
+      ...snapshotGate.skippedStale ? { skippedStale: true } : {},
+      ...timedOut ? { sequenceUnknown: true } : {}
+    }
+  });
+  logProjectSnapshotProbe({
+    dbg,
+    root: snapshotRoot,
+    currentProjectSeq: freshnessSeq,
+    unlockedThrough: latestSeq.unlockedThrough ?? 0,
+    snapshot,
+    missReason: snapshotMissReason
+  });
+  const freshSnapshot = snapshotFresh ? snapshot : null;
+  if (freshSnapshot) {
+    hydrateRuntimeFromProjectSnapshot(runtime, freshSnapshot);
+  }
+  const cachedStartupScan = freshSnapshot?.startupScan && isStartupScanVerdictFresh(freshSnapshot.startupScan) ? freshSnapshot.startupScan : undefined;
+  const startupScanSource = cachedStartupScan ? "snapshot" : "computed";
+  let startupScan;
+  if (cachedStartupScan) {
+    startupScan = { ...cachedStartupScan, cwd: path.resolve(cwd) };
+  } else {
+    const scanContextStartedAt = Date.now();
+    startupScan = resolveStartupScanContext(cwd);
+    logLatency({
+      type: "phase",
+      phase: "session_start_scan_context_compute",
+      filePath: cwd,
+      startedAt: new Date(scanContextStartedAt).toISOString(),
+      durationMs: Date.now() - scanContextStartedAt,
+      metadata: { mode: startupMode }
+    });
+  }
+  phase("scan-context");
+  dbg(`session_start scan-context source=${startupScanSource}`);
+  const scanRoot = startupScan.projectRoot ?? cwd;
+  const useScanRootForSignals = startupScan.canWarmCaches || startupScan.reason === "too-many-source-files" || startupScan.reason === "too-many-entries";
+  const analysisRoot = useScanRootForSignals ? scanRoot : cwd;
+  runtime.projectRoot = cwd;
+  const languageProfileSource = freshSnapshot?.languageProfile ? "snapshot" : "computed";
+  const languageProfile = freshSnapshot?.languageProfile ? freshSnapshot.languageProfile : detectProjectLanguageProfile(analysisRoot, startupScan.canWarmCaches ? undefined : []);
+  phase("language-profile");
+  dbg(`session_start language-profile source=${languageProfileSource}`);
+  dbg(`session_start cwd: ${cwd}`);
+  dbg(`session_start scan root: ${scanRoot} (warmCaches=${startupScan.canWarmCaches}${startupScan.reason ? `, reason=${startupScan.reason}` : ""})`);
+  dbg(`session_start analysis root: ${analysisRoot}`);
+  dbg(`session_start workspace root: ${runtime.projectRoot}`);
+  dbg(`session_start language profile: ${languageProfile.detectedKinds.join(", ") || "none"}`);
+  dbg(`session_start language counts: ${JSON.stringify(languageProfile.counts)} configured=${JSON.stringify(languageProfile.configured)}`);
+  dbg(`session_start workspace cwd available: ${hasWorkspaceCwd}`);
+  if (useScanRootForSignals && analysisRoot !== cwd) {
+    dbg(`session_start: monorepo analysis root override -> ${analysisRoot}`);
+  }
+  const slowFsVerdict = getSlowFsVerdict(analysisRoot);
+  logLatency({
+    type: "phase",
+    phase: "slow_fs_probe",
+    filePath: analysisRoot,
+    durationMs: 0,
+    metadata: {
+      slow: slowFsVerdict.slow,
+      medianStatMicros: slowFsVerdict.medianStatMicros,
+      samples: slowFsVerdict.samples
+    }
+  });
+  dbg(`session_start slow-fs probe: slow=${slowFsVerdict.slow} medianStatMicros=${slowFsVerdict.medianStatMicros.toFixed(1)} samples=${slowFsVerdict.samples}`);
+  if (slowFsVerdict.slow) {
+    notify(`\uD83D\uDC22 Slow filesystem detected (median ${slowFsVerdict.medianStatMicros.toFixed(0)}µs/stat) — reduced-scan mode engaged (set DM_LENS_ALLOW_SLOW_FS_SCAN=1 to override).`, "warning");
+  }
+  const subagentSession = isSubagentSession();
+  if (isWarmAttached()) {
+    dbg("session_start lsp-warm: skipping pre-warm (attached to incumbent)");
+  } else if (subagentSession) {
+    const identity = getSubagentIdentity();
+    logLatency({
+      type: "phase",
+      phase: "subagent_light_mode",
+      filePath: analysisRoot,
+      durationMs: 0,
+      metadata: {
+        runId: identity?.runId,
+        agentName: identity?.agentName,
+        marker: identity?.marker
+      }
+    });
+    dbg(`session_start subagent light mode: engaged (marker=${identity?.marker ?? "unknown"} runId=${identity?.runId ?? "unknown"} agentName=${identity?.agentName ?? "unknown"})`);
+  }
+  const lensLspEnabled = !getFlag("no-lsp");
+  const startupDefaults = getDefaultStartupTools(languageProfile).filter((tool) => {
+    if ((tool === "typescript-language-server" || tool === "pyright") && !lensLspEnabled) {
+      return false;
+    }
+    return true;
+  });
+  if (!allowBootstrapTasks) {
+    dbg("session_start: skipping tool preinstall (startup mode)");
+  } else if (startupDefaults.length > 0) {
+    dbg(`session_start: pre-install defaults -> ${startupDefaults.join(", ")}`);
+    firePreinstallDefaults(ensureTool, dbg, startupDefaults);
+  } else {
+    dbg("session_start: no language defaults selected for pre-install");
+  }
+  const startupScansEnabled = deps.projectConfig?.startup?.scans?.enabled ?? deps.globalConfig?.startup?.scans?.enabled ?? true;
+  const startupScansWillRun = allowBootstrapTasks && startupScan.canWarmCaches && startupScansEnabled;
+  const jstsHeavyScansWillRun = startupScansWillRun && canRunStartupHeavyScans(languageProfile, "jsts");
+  if (allowBootstrapTasks) {
+    scheduleDeferredToolProbes(deps, languageProfile, startupDefaults, jstsHeavyScansWillRun, dbg);
+    scheduleManagedToolRefresh(dbg);
+  }
+  if (allowBootstrapTasks) {
+    probePrettierInstall(ensureTool, dbg, analysisRoot);
+  } else {
+    dbg("session_start: skipping prettier preinstall probe (startup mode)");
+  }
+  const summaryClients = await deps.bootstrap.request("session-start-tools");
+  const detectedRunner = summaryClients?.testRunnerClient.detectRunner(analysisRoot);
+  phase("test-runner-detect");
+  if (detectedRunner)
+    tools.push(`Test runner (${detectedRunner.runner})`);
+  if (await summaryClients?.goClient.isGoAvailableAsync())
+    tools.push("Go (go vet)");
+  if (await summaryClients?.rustClient.isAvailableAsync())
+    tools.push("Rust (cargo)");
+  log(`Active tools: ${tools.join(", ")}`);
+  dbg(`session_start tools: ${tools.join(", ")}`);
+  const agentStartupGuidance = renderSessionStartGuidance({
+    disabledToolNames: deps.disabledToolNames,
+    requirePreExistingFixes: deps.globalConfig?.contextInjection?.requirePreExistingFixes
+  });
+  runtime.projectRulesScan = scanProjectRules(analysisRoot);
+  saveRuntimeProjectSnapshot({
+    cwd: snapshotRoot,
+    runtime,
+    startupScan,
+    languageProfile,
+    dbg
+  });
+  phase("project-rules");
+  if (runtime.projectRulesScan.hasCustomRules) {
+    const ruleCount = runtime.projectRulesScan.rules.length;
+    const sources = [
+      ...new Set(runtime.projectRulesScan.rules.map((r) => r.source))
+    ];
+    dbg(`session_start: found ${ruleCount} project rule(s) from ${sources.join(", ")}`);
+  } else {
+    dbg("session_start: no project rules found");
+  }
+  cacheManager.writeCache("session-start-guidance", { content: agentStartupGuidance.join(`
+`) }, analysisRoot);
+  if (!allowBootstrapTasks) {
+    dbg("session_start: skipping startup background scans (startup mode)");
+  } else if (!startupScansEnabled) {
+    dbg("session_start: skipping startup background scans (disabled by config)");
+    recordDegradationOnce({
+      kind: "startup-analyzer-disabled",
+      subject: "startup-scans",
+      reason: "skipped (disabled by config)"
+    });
+  } else if (!startupScan.canWarmCaches) {
+    dbg(`session_start: skipping heavy scans (${startupScan.reason ?? "unknown"})`);
+    dbg(`session_start: skipping TODO scan (${startupScan.reason ?? "unknown"})`);
+    notifyStartupWarmSkip({
+      scan: startupScan,
+      analysisRoot,
+      notify,
+      runtime,
+      sessionGeneration
+    });
+  } else {
+    scheduleStartupScans(deps, runtime, sessionGeneration, analysisRoot, snapshotRoot, languageProfile, dbg);
+  }
+  if (subagentSession) {
+    dbg("session_start lsp-warm: skipping pre-warm (subagent session)");
+  } else if (!getFlag("no-lsp") && allowBootstrapTasks) {
+    setImmediate(() => {
+      loadLSPConfig(cwd).then((lspConfig) => {
+        const warmFiles = lspConfig.warmFiles ?? [];
+        dbg(`session_start lsp-config: loaded (${warmFiles.length} warm file(s) configured)`);
+        if (warmFiles.length > 0) {
+          igniteWarmFiles(cwd, warmFiles, runtime, sessionGeneration, dbg).catch((err) => dbg(`session_start lsp-warm: unhandled error: ${err}`));
+        } else if (startupScan.canWarmCaches) {
+          igniteDominantLanguageWarm(analysisRoot, runtime, sessionGeneration, dbg).catch((err) => dbg(`session_start lsp-warm: unhandled dominant error: ${err}`));
+        } else {
+          dbg(`session_start lsp-warm: skipping dominant-language auto-warm (${startupScan.reason ?? "unknown"})`);
+        }
+      });
+    });
+    phase("lsp-config");
+  }
+  setSessionLanguages(languageProfile.detectedKinds);
+  const totalDurationMs = Date.now() - sessionStartMs;
+  dbg(`session_start total: ${totalDurationMs}ms (interactive path; background tasks may continue)`);
+  logLatency({
+    type: "phase",
+    phase: "session_start_total",
+    filePath: cwd,
+    startedAt: new Date(sessionStartMs).toISOString(),
+    durationMs: totalDurationMs,
+    metadata: {
+      mode: startupMode,
+      reason: deps.sessionReason,
+      ...sessionStartDecisionMetadata(deps)
+    }
+  });
+  logHostReadyDelay(deps, cwd);
+  emitSmellsSessionStartLine(dbg, sessionStartMs);
+}
+function sessionStartDecisionMetadata(deps) {
+  return {
+    classification: deps.sessionStartClassification,
+    sameRoot: deps.sessionStartSameRoot ?? "unknown",
+    basis: deps.sessionStartBasis,
+    gapMs: deps.sessionStartGapMs,
+    lineageMatch: deps.sessionStartLineageMatch
+  };
+}
+function emitSmellsSessionStartLine(dbg, sessionStartMs) {
+  try {
+    const line = formatSmellsSessionStartLine(countRecentSmells(undefined, sessionStartMs));
+    if (line)
+      dbg(line);
+  } catch {}
+}