@tyroneross/navgator 0.2.2 → 0.10.0

package/dist/scanner.js

@@ -2,47 +2,921 @@
  * NavGator Main Scanner
  * Orchestrates all component and connection scanners
  */
-import { glob } from 'glob';
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'node:child_process';
+import { glob, globSync } from 'glob';
+const DEFAULT_IGNORE_PATTERNS = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/build-*/**',
+    '**/.next/**',
+    '**/__pycache__/**',
+    '**/venv/**',
+    '**/.venv/**',
+    '**/.git/**',
+    '**/.navgator/**',
+    '**/.rally/**',
+    '**/.build-loop/**',
+    '**/.claude/**',
+    '**/.codex/**',
+    '**/.ibr/**',
+    '**/.build/**',
+    '**/target/**',
+    '**/DerivedData/**',
+    '**/SourcePackages/**',
+    '**/.swiftpm/**',
+    '**/Pods/**',
+    '**/vendor/**',
+    '**/coverage/**',
+    // Saved-webpage asset directories (Mediasite/Confluence/MHTML exports etc.)
+    // contain inert JS that has no runtime role in the project.
+    '**/*_files/**',
+];
+function getIgnorePatterns(root) {
+    const userFile = path.join(root, '.navgatorignore');
+    if (!fs.existsSync(userFile))
+        return DEFAULT_IGNORE_PATTERNS;
+    try {
+        const userPatterns = fs.readFileSync(userFile, 'utf-8')
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith('#'));
+        return [...DEFAULT_IGNORE_PATTERNS, ...userPatterns];
+    }
+    catch {
+        return DEFAULT_IGNORE_PATTERNS;
+    }
+}
+/**
+ * Remove files ignored by the owning Git repository. `.gitignore` is the
+ * broadest source-grounded signal that a generated tree is not project source
+ * (for example the packaged `web/runtime/` dashboard). Tracked files are never
+ * removed by `git check-ignore`, even when a later pattern would match them.
+ * Non-Git directories and unavailable Git binaries fail open to the explicit
+ * NavGator ignore list above.
+ */
+export function excludeGitIgnoredFiles(root, files) {
+    if (files.length === 0 || process.env.NAVGATOR_NO_GIT_IGNORE === '1')
+        return files;
+    const input = `${files.join('\0')}\0`;
+    const result = spawnSync('git', ['check-ignore', '--stdin', '-z'], {
+        cwd: root,
+        input,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    if (result.status !== 0 && result.status !== 1)
+        return files;
+    const ignored = new Set((result.stdout || '').split('\0').filter(Boolean).map(file => file.replace(/\\/g, '/')));
+    // An explicitly selected scan root can itself live under a parent repo's
+    // ignored tree. In that case Git labels every path ignored; treating that as
+    // a source boundary would silently produce an empty architecture.
+    if (ignored.size === files.length)
+        return files;
+    return files.filter(file => !ignored.has(file.replace(/\\/g, '/')));
+}
+import { generateComponentId, } from './types.js';
+import { getGitInfo } from './git.js';
+import { enrichFromCache } from './enrich/external-resolver.js';
+import { loadCache, makeLookup } from './enrich/cache.js';
 import { scanNpmPackages, detectNpm } from './scanners/packages/npm.js';
 import { scanPipPackages, detectPip } from './scanners/packages/pip.js';
 import { scanSpmPackages, detectSpm } from './scanners/packages/swift.js';
+import { scanCargoPackages, detectCargo } from './scanners/packages/cargo.js';
 import { scanInfrastructure } from './scanners/infrastructure/index.js';
+import { scanPrismaSchema, detectPrisma } from './scanners/infrastructure/prisma-scanner.js';
+import { scanEnvVars, detectEnvFiles } from './scanners/infrastructure/env-scanner.js';
+import { scanQueues, detectQueues } from './scanners/infrastructure/queue-scanner.js';
+import { scanCronJobs, detectCrons } from './scanners/infrastructure/cron-scanner.js';
+import { scanDeployConfig } from './scanners/infrastructure/deploy-scanner.js';
+import { scanPrismaCalls } from './scanners/connections/prisma-calls.js';
+import { scanFieldUsage, canAnalyzeFieldUsage } from './scanners/infrastructure/field-usage-analyzer.js';
+import { scanTypeSpecValidation, canValidateTypeSpec } from './scanners/infrastructure/typespec-validator.js';
 import { scanServiceCalls } from './scanners/connections/service-calls.js';
 import { scanWithAST, scanDatabaseOperations } from './scanners/connections/ast-scanner.js';
 import { scanPrompts, convertToArchitecture, formatPromptsOutput } from './scanners/prompts/index.js';
 import { traceLLMCalls } from './scanners/connections/llm-call-tracer.js';
 import { scanSwiftCode } from './scanners/swift/code-scanner.js';
-import { storeComponents, storeConnections, buildIndex, buildGraph, buildFileMap, buildSummary, savePromptScan, clearStorage, createSnapshot, computeFileHashes, saveHashes, detectFileChanges, formatFileChangeSummary, } from './storage.js';
-import { getConfig, ensureStorageDirectories } from './config.js';
+import { scanRustCode } from './scanners/rust/code-scanner.js';
+import { scanImports } from './scanners/connections/import-scanner.js';
+import { scanMarkdownContent } from './scanners/content/markdown-scanner.js';
+import { languageOf } from './architecture-index.js';
+import { storeComponents, storeConnections, migratePerEntityFiles, buildIndex, buildGraph, buildFileMap, buildSummary, savePromptScan, clearStorage, clearForFiles, loadIndex, loadAllComponents, loadAllConnections, loadReverseDeps, runIntegrityCheck, mergeByStableId, normalizeTrackedPath, partitionPriorStateForFiles, atomicWriteJSON, ensureStableIdPublic, buildReverseDepsIndex, buildDerivedManifest, createSnapshot, computeFileHashes, saveHashes, detectFileChanges, formatFileChangeSummary, } from './storage.js';
+import { getConfig, ensureStorageDirectories, getIndexPath, SCHEMA_VERSION, STABLE_ID_SCHEME_VERSION, getComponentsPath, getConnectionsPath } from './config.js';
+import { acquireScanLease } from './scan-lock.js';
+import { scanLockPath } from './freshness/paths.js';
+import { computeArchitectureDiff, classifySignificance, loadLatestSnapshot, buildSnapshotFromRecords, saveTimelineEntry, generateTimelineId, } from './diff.js';
+import { registerProject } from './projects.js';
+import { runAudit, updateEwmaForAudit } from './audit/index.js';
+/**
+ * Strip internal scratch fields (prefixed with `__`) before persisting
+ * an AuditReport on a TimelineEntry.
+ */
+/**
+ * Name a synthesized file-node the same way the import-scanner names its
+ * internal-module components (`buildFileComponent` /`componentNameFromFile`),
+ * so a Swift/Rust file-node and a TypeScript module component read alike in
+ * the graph. Kept local to scanner.ts rather than exported from the import
+ * scanner because the two callers must stay independently changeable.
+ */
+function endpointNodeName(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const withoutExtension = normalized.replace(/\.[^.]+$/, '');
+    const segments = withoutExtension.split('/').filter(Boolean);
+    if (segments[0] === 'src' || segments[0] === 'app' || segments[0] === 'lib')
+        segments.shift();
+    if (segments[segments.length - 1] === 'index' && segments.length > 1)
+        segments.pop();
+    return segments.join('/') || path.basename(withoutExtension);
+}
+function endpointNodeLayer(file) {
+    const normalized = file.replace(/\\/g, '/').toLowerCase();
+    if (/(^|\/)(ui|components|views|pages|frontend|web)(\/|$)/.test(normalized))
+        return 'frontend';
+    if (/(^|\/)(db|database|prisma|drizzle|migrations)(\/|$)/.test(normalized))
+        return 'database';
+    if (/(^|\/)(queue|queues|jobs|workers)(\/|$)/.test(normalized))
+        return 'queue';
+    if (/(^|\/)(infra|infrastructure|terraform|k8s|docker)(\/|$)/.test(normalized))
+        return 'infra';
+    return 'backend';
+}
+/**
+ * Canonical form for a repo-relative file path used as a `FILE:` endpoint or
+ * a component's config_files entry (Run 4 fix2 #4): forward slashes, no
+ * leading `./`, no duplicated separators. `FILE:./src/a.ts`, `FILE:src//a.ts`
+ * and a component claiming `src/a.ts` must all meet on the same key.
+ */
+export function normalizeEndpointPath(p) {
+    let s = p.replace(/\\/g, '/');
+    s = s.replace(/\/{2,}/g, '/');
+    while (s.startsWith('./'))
+        s = s.slice(2);
+    s = s.replace(/\/\.\//g, '/');
+    return s;
+}
+/**
+ * (C) Resolve FILE: prefixed connection endpoints to real component IDs so
+ * trace can follow imports from route files instead of dead-ending.
+ *
+ * (C2) Synthesize a file-node for every FILE: endpoint that survived (C).
+ * A surviving FILE: ref names a real source file that no scanner claimed as
+ * a component — Swift and Rust files, and TypeScript files the import
+ * scanner never walked (scripts/, _archive/, tests/). Storing such an edge
+ * leaves it dangling: `runIntegrityCheck` (storage.ts) exempts FILE: ids
+ * unconditionally, so the graph reports "ok" while trace dead-ends and the
+ * audit counts the edge as hallucinated. One file-node per file, created
+ * once, reused by every endpoint naming that file; only for paths that exist
+ * on disk (a component built on a phantom path would fail integrity check
+ * rule (2) and promote every later incremental scan to full).
+ *
+ * Mutates `components` (pushes file-nodes) and the endpoint ids in
+ * `connections`. Paths are normalized on both sides (fix2 #4).
+ */
+export function resolveFileEndpoints(components, connections, root) {
+    const compByFile = new Map(); // normalized file path → component_id
+    for (const comp of components) {
+        for (const f of comp.source?.config_files || []) {
+            const key = normalizeEndpointPath(f);
+            if (!compByFile.has(key))
+                compByFile.set(key, comp.component_id);
+        }
+    }
+    const fileNodeByPath = new Map();
+    const resolve = (ref) => {
+        const id = ref?.component_id;
+        if (!ref || !id?.startsWith('FILE:'))
+            return;
+        const filePath = normalizeEndpointPath(id.slice(5));
+        const claimed = compByFile.get(filePath);
+        if (claimed) {
+            ref.component_id = claimed;
+            return;
+        }
+        let nodeId = fileNodeByPath.get(filePath);
+        if (!nodeId) {
+            if (!fs.existsSync(path.join(root, filePath)))
+                return;
+            const node = buildEndpointFileComponent(filePath, Date.now());
+            components.push(node);
+            compByFile.set(filePath, node.component_id);
+            fileNodeByPath.set(filePath, node.component_id);
+            nodeId = node.component_id;
+        }
+        ref.component_id = nodeId;
+    };
+    for (const conn of connections) {
+        resolve(conn.from);
+        resolve(conn.to);
+    }
+}
+/**
+ * Build the file-node that backs a `FILE:` connection endpoint no scanner
+ * claimed. Structurally identical to the import-scanner's internal-module
+ * component (same type/shape/config_files contract) so downstream consumers —
+ * dedup, stable_id, integrity check, trace — treat it as an ordinary component.
+ */
+function buildEndpointFileComponent(file, timestamp) {
+    return {
+        component_id: generateComponentId('component', endpointNodeName(file)),
+        name: endpointNodeName(file),
+        type: 'component',
+        role: {
+            purpose: `Source file at ${file}`,
+            layer: endpointNodeLayer(file),
+            critical: false,
+        },
+        source: { detection_method: 'auto', config_files: [file], confidence: 0.6 },
+        connects_to: [],
+        connected_from: [],
+        status: 'active',
+        tags: ['file-node'],
+        metadata: { file, kind: 'source-file', detected_from: 'endpoint-resolver' },
+        timestamp,
+        last_updated: timestamp,
+    };
+}
+function stripInternals(report) {
+    const { ...clean } = report;
+    for (const k of Object.keys(clean)) {
+        if (k.startsWith('__')) {
+            delete clean[k];
+        }
+    }
+    return clean;
+}
+import { classifyAllConnections } from './classify.js';
+import { detectSandbox } from './sandbox.js';
+import { ensureSafeGitignore } from './gitignore-safety.js';
+// =============================================================================
+// MULTI-STACK ROOT DISCOVERY
+// =============================================================================
+/**
+ * Manifest filenames that mark a directory as the root of a discrete stack.
+ * Keep language-canonical manifests together so root detection and nested
+ * discovery use the same contract.
+ */
+const STACK_MANIFESTS = [
+    'package.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'Package.swift',
+    'Podfile',
+    'Cartfile',
+    'go.mod',
+    'pom.xml',
+    'Gemfile',
+    // Catch-all for .NET — we glob the subdir for `*.csproj` separately
+    // because there's no fixed filename. Handled via discoverStackRoots.
+];
+/**
+ * Search nested wrapper directories under `root`, return roots to scan. Behavior:
+ *
+ *  - If `root` has a stack manifest, include it as `{ origin: '.' }`.
+ *  - Discover manifests up to five directory levels below the scan root. Any
+ *    matching directory is included and nested stack descendants are pruned.
+ *  - When more than one nested stack is found, all of them are scanned and
+ *    components get an `origin_root` metadata tag so consumers can group.
+ *
+ * Uses the same `.navgatorignore` and Git-ignore boundary as source discovery.
+ */
+export function discoverStackRoots(root, verbose) {
+    // Use the same repo-root ignore contract as source discovery. `globSync`
+    // handles arbitrary `.navgatorignore` patterns; the prior hand-written
+    // directory list could not. maxDepth=5 keeps discovery bounded while
+    // supporting deeply wrapped monorepo stacks.
+    const fixedManifestPatterns = STACK_MANIFESTS.map(manifest => `**/${manifest}`);
+    const variableManifestPatterns = ['**/*.csproj', '**/*.xcodeproj', '**/*.xcworkspace'];
+    const matches = globSync([...fixedManifestPatterns, ...variableManifestPatterns], {
+        cwd: root,
+        ignore: getIgnorePatterns(root),
+        dot: false,
+        follow: false,
+        maxDepth: 5,
+    });
+    const ignoredFiltered = excludeGitIgnoredFiles(root, matches);
+    const origins = new Set();
+    for (const match of ignoredFiltered) {
+        const normalized = match.replace(/\\/g, '/');
+        const origin = path.posix.dirname(normalized);
+        origins.add(origin === '.' ? '.' : origin);
+    }
+    // Preserve the established rule: the project root is allowed to have child
+    // stack roots, but a nested stack root prunes descendants below itself.
+    const sortedOrigins = [...origins].sort((a, b) => {
+        const depth = (value) => value === '.' ? 0 : value.split('/').length;
+        return depth(a) - depth(b) || a.localeCompare(b);
+    });
+    const retained = [];
+    for (const origin of sortedOrigins) {
+        if (origin !== '.' && retained.some(parent => parent !== '.' && (origin === parent || origin.startsWith(`${parent}/`))))
+            continue;
+        retained.push(origin);
+    }
+    const found = retained.map(origin => ({
+        path: origin === '.' ? root : path.join(root, ...origin.split('/')),
+        origin,
+    }));
+    if (found.length === 0) {
+        // Nothing in the bounded nested search either — keep legacy behavior so older
+        // projects don't silently turn into no-ops.
+        if (verbose) {
+            console.log('  - No stack manifest at root or in nested wrappers; scanning root anyway');
+        }
+        return [{ path: root, origin: '.' }];
+    }
+    if (verbose && (found.length > 1 || found[0]?.origin !== '.')) {
+        console.log(`  - Multi-stack project: ${found.length} nested root(s): ` +
+            found.map(f => f.origin).join(', '));
+    }
+    return found;
+}
+// =============================================================================
+// MODE SELECTION (Run 1 — D2)
+// =============================================================================
+/**
+ * Files whose presence in fileChanges forces a full scan because they alter
+ * the package/dependency graph in ways that ripple through every component.
+ */
+const FULL_SCAN_TRIGGER_FILES = new Set([
+    // Lockfiles / manifests — change the package graph
+    'package.json',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'pyproject.toml',
+    'requirements.txt',
+    'requirements-dev.txt',
+    'requirements-test.txt',
+    'prisma/schema.prisma',
+    'Package.swift',
+    'Package.resolved',
+    'Podfile',
+    'Podfile.lock',
+    'Cartfile',
+    'Cartfile.resolved',
+    'Cargo.toml',
+    'Cargo.lock',
+    // Build / runtime config — change resolution, deploy targets, ignore rules
+    'tsconfig.json',
+    'jsconfig.json',
+    'vercel.json',
+    'fly.toml',
+    'railway.json',
+    '.gitignore',
+]);
+/** Days × ms in one day — used by stale-full check. */
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cap on consecutive incremental scans before forcing a full scan. */
+const INCREMENTAL_CAP = 20;
+/**
+ * Convert hook/ledger paths to the same project-relative POSIX identity used
+ * by glob, hashes, walk sets, and connection code references. Paths outside
+ * the project are ignored so a malformed hook payload cannot partition or
+ * clear unrelated canonical state.
+ */
+function normalizeForcedChangedFiles(files, root) {
+    const normalized = new Set();
+    for (const raw of files) {
+        const value = raw.trim();
+        if (!value || value.includes('\0'))
+            continue;
+        const tracked = normalizeTrackedPath(value, root);
+        if (!tracked || tracked === '..' || tracked.startsWith('../') || path.posix.isAbsolute(tracked)) {
+            continue;
+        }
+        normalized.add(tracked);
+    }
+    return [...normalized].sort();
+}
+/**
+ * Decide whether to run a full or incremental scan based on the requested
+ * mode, the prior index state, and the file changes since last scan.
+ *
+ * Pure function — no I/O. All inputs precomputed by the caller.
+ *
+ * Policy (for mode='auto'):
+ * 1. No prior index → full / no-prior-state
+ * 2. schema_version mismatch (and not 1.0.0 → 1.1.0 soft-upgrade) → full / schema-mismatch
+ * 3. Any FULL_SCAN_TRIGGER_FILES in changedFiles → full / manifest-changed
+ * 4. now − last_full_scan > 7 days → full / stale-full
+ * 5. incrementals_since_full ≥ 20 → full / incremental-cap
+ * 6. No file changes at all → noop case (caller handles); we still return
+ *    'incremental' here for the no-op flow.
+ * 7. Else → incremental / fast-path
+ */
+export function selectScanMode(fileChanges, index, options, now = Date.now()) {
+    const mode = options.mode ?? (options.clearFirst ? 'full' : options.incremental ? 'incremental' : 'auto');
+    if (mode === 'full') {
+        return { mode: 'full', reason: 'flag-full' };
+    }
+    // Stable-id generations cannot be mixed in one incremental store. Force a
+    // rebuild even when the caller explicitly requested incremental; otherwise
+    // old survivors and fresh records coexist under incompatible join keys.
+    if (index && index.stable_id_scheme !== STABLE_ID_SCHEME_VERSION) {
+        return { mode: 'full', reason: 'stable-id-scheme-mismatch' };
+    }
+    if (mode === 'incremental') {
+        if (!index) {
+            return { mode: 'full', reason: 'no-prior-state' };
+        }
+        return { mode: 'incremental', reason: 'flag-incremental' };
+    }
+    // mode === 'auto'
+    if (!index) {
+        return { mode: 'full', reason: 'no-prior-state' };
+    }
+    // 1.0.0 → 1.1.0 is a soft upgrade (loadIndex injected defaults).
+    // Any other mismatch demands a full rebuild.
+    const sv = index.schema_version ?? '1.0.0';
+    if (sv !== '1.0.0' && sv !== SCHEMA_VERSION) {
+        return { mode: 'full', reason: 'schema-mismatch' };
+    }
+    // Run 2 — D5: prior scan's audit detected EWMA drift breach.
+    // Force a full + Cochran audit pass on this run.
+    if (index.pending_drift_breach) {
+        return { mode: 'full', reason: 'audit-drift-breach' };
+    }
+    const changed = new Set();
+    if (fileChanges) {
+        for (const f of fileChanges.added)
+            changed.add(f);
+        for (const f of fileChanges.modified)
+            changed.add(f);
+        for (const f of fileChanges.removed)
+            changed.add(f);
+    }
+    const changedMatchesTrigger = (file, trigger) => file === trigger || file.endsWith(`/${trigger}`);
+    for (const trigger of FULL_SCAN_TRIGGER_FILES) {
+        if (Array.from(changed).some((file) => changedMatchesTrigger(file, trigger))) {
+            return { mode: 'full', reason: 'manifest-changed' };
+        }
+    }
+    // New files have no recorded reverse-dep edges yet, so an incremental walk-set
+    // can't find their importers. Cleaner to force a full scan than gymnastics
+    // (Run 1.6 — item #5).
+    if (fileChanges && fileChanges.added.length > 0) {
+        return { mode: 'full', reason: 'new-files' };
+    }
+    const lastFull = index.last_full_scan ?? 0;
+    if (lastFull > 0 && now - lastFull > SEVEN_DAYS_MS) {
+        return { mode: 'full', reason: 'stale-full' };
+    }
+    const incCount = index.incrementals_since_full ?? 0;
+    if (incCount >= INCREMENTAL_CAP) {
+        return { mode: 'full', reason: 'incremental-cap' };
+    }
+    if (changed.size === 0) {
+        return { mode: 'incremental', reason: 'no-changes' };
+    }
+    return { mode: 'incremental', reason: 'fast-path' };
+}
+// =============================================================================
+// SCAN COVERAGE (honesty contract — ARCHITECTURE.md § Coverage and blind spots)
+// =============================================================================
+//
+// `src/architecture-index.ts` (lines ~71-104, ~383-431) already computes this
+// exact idea for the committed, deterministic index projection. This section
+// intentionally mirrors its wording and shape rather than inventing a second
+// vocabulary for the same concept, so `scan` and `arch-index` never disagree
+// about what "analyzed" means for a given language.
+//
+// The extension→language map is imported from `architecture-index.ts`
+// (`LANGUAGE_BY_EXTENSION` / `languageOf`) rather than duplicated — a former
+// version of this file kept its own `SCAN_COVERAGE_LANGUAGE_BY_EXTENSION`
+// copy, and the two had already drifted (missing `.sh`/`.bash`/`.sql` here,
+// missing `.scala` there) before this dedup. Only the extension map is
+// shared; `SCAN_COVERAGE_ANALYZED_LANGUAGES` below stays local and
+// deliberately different from `architecture-index.ts`'s `ANALYZED_LANGUAGES`
+// — see the comment on it for why the two sets must never be merged.
+/**
+ * Languages a registered scanner actually consumes, keyed to the same
+ * strings `LANGUAGE_BY_EXTENSION` (imported from `architecture-index.ts`)
+ * produces. A language absent from this set is still counted (files,
+ * components-that-happen-to-resolve) for coverage purposes, but its
+ * `internal_edges` is always reported as 0 — no scanner ever looked at it, so
+ * "zero" there means "not measured", never "not coupled".
+ *
+ * Deliberately WIDER than `architecture-index.ts`'s `ANALYZED_LANGUAGES`:
+ * the full `scan` command additionally runs the Swift and Rust code
+ * scanners (`scanSwiftCode` / `scanRustCode`, see imports above), which
+ * `arch-index` never invokes — it builds its graph from `scanImports` alone.
+ * Do not merge the two sets; doing so would make one of the two commands
+ * claim coverage it does not have.
+ *
+ * Adding a new language scanner means adding its language string here too.
+ * Nothing else in this file infers the analyzed set from scanner presence —
+ * a future scanner author must add the entry explicitly or their new
+ * language will silently keep reading as an unanalyzed blind spot.
+ */
+export const SCAN_COVERAGE_ANALYZED_LANGUAGES = new Set([
+    'TypeScript',
+    'JavaScript',
+    'Python',
+    'Swift',
+    'Rust',
+]);
+/**
+ * Computes the scan's coverage table plus the `ScanWarning`s it implies.
+ *
+ * Returns `{ coverage: undefined, warnings: [] }` when every language
+ * present in `scannableFiles` was analyzed and produced at least one
+ * internal edge (`status: 'full'`) — the caller must not attach `coverage`
+ * in that case, so a fully-covered scan stays byte-identical to a scan that
+ * predates this change.
+ */
+function computeScanCoverage(scannableFiles, components, connections) {
+    const filesByLanguage = new Map();
+    for (const file of scannableFiles) {
+        const lang = languageOf(file);
+        if (!lang)
+            continue;
+        if (!filesByLanguage.has(lang))
+            filesByLanguage.set(lang, []);
+        filesByLanguage.get(lang).push(file);
+    }
+    if (filesByLanguage.size === 0) {
+        return { coverage: undefined, warnings: [] };
+    }
+    // Component -> file, via the same fields every scanner in this repo uses
+    // for a source-file component: `source.config_files[0]` (import-scanner's
+    // `buildFileComponent`) or `metadata.file` (Swift/Rust scanners).
+    const componentFile = (c) => {
+        const cfgFile = c.source?.config_files?.[0];
+        if (typeof cfgFile === 'string' && cfgFile.length > 0)
+            return cfgFile;
+        const metaFile = c.metadata?.['file'];
+        return typeof metaFile === 'string' ? metaFile : undefined;
+    };
+    const componentsByLanguage = new Map();
+    for (const c of components) {
+        const file = componentFile(c);
+        if (!file)
+            continue;
+        const lang = languageOf(file);
+        if (!lang)
+            continue;
+        componentsByLanguage.set(lang, (componentsByLanguage.get(lang) ?? 0) + 1);
+    }
+    // Deduplicated internal `imports` edges by the origin file's language — two
+    // import statements for the same target are one edge, matching
+    // `architecture-index.ts`'s dedup so the two counts never disagree.
+    const edgesByLanguage = new Map();
+    for (const conn of connections) {
+        if (conn.connection_type !== 'imports')
+            continue;
+        const from = conn.from.location?.file ?? conn.code_reference?.file;
+        const to = conn.to.location?.file;
+        if (!from || !to || from === to)
+            continue;
+        const lang = languageOf(from);
+        if (!lang)
+            continue;
+        if (!edgesByLanguage.has(lang))
+            edgesByLanguage.set(lang, new Set());
+        edgesByLanguage.get(lang).add(`${from} ${to}`);
+    }
+    const languages = [...filesByLanguage.entries()]
+        .map(([language, files]) => {
+        const analyzed = SCAN_COVERAGE_ANALYZED_LANGUAGES.has(language);
+        return {
+            language,
+            files: files.length,
+            analyzed,
+            components: componentsByLanguage.get(language) ?? 0,
+            // Not analyzed => always 0, even if a stray edge matched by
+            // coincidence — an unanalyzed language cannot have produced a real
+            // edge, so reporting one would contradict `analyzed: false`.
+            internal_edges: analyzed ? edgesByLanguage.get(language)?.size ?? 0 : 0,
+        };
+    })
+        .sort((a, b) => a.language.localeCompare(b.language));
+    const analyzedLanguageNames = [...SCAN_COVERAGE_ANALYZED_LANGUAGES].sort().join('/');
+    const blindSpots = [];
+    let hasGap = false;
+    for (const lang of languages) {
+        if (!lang.analyzed) {
+            hasGap = true;
+            blindSpots.push(`${lang.files} ${lang.language} file(s) are present but NOT analyzed. NavGator's ` +
+                `scanners cover ${analyzedLanguageNames} only, so zero ${lang.language} edges here ` +
+                `means "not measured", never "not coupled".`);
+        }
+        else if (lang.files > 0 && lang.internal_edges === 0) {
+            hasGap = true;
+            blindSpots.push(`${lang.files} ${lang.language} file(s) were analyzed but produced zero internal ` +
+                `edges. Either those files genuinely import nothing local, or the scanner missed ` +
+                `them — this scan cannot tell the two apart, so do not read the absence as low coupling.`);
+        }
+    }
+    blindSpots.sort();
+    const totalAnalyzedEdges = languages
+        .filter((l) => l.analyzed)
+        .reduce((sum, l) => sum + l.internal_edges, 0);
+    const status = totalAnalyzedEdges === 0 ? 'none' : hasGap ? 'partial' : 'full';
+    if (status === 'full') {
+        return { coverage: undefined, warnings: [] };
+    }
+    // Each blind spot is also a `ScanWarning`, so `warnings_count` stops
+    // reading 0 on a repo NavGator did not look at — a not-looked-at repo and
+    // a genuinely clean one must never print the same numbers.
+    const warnings = blindSpots.map((message) => ({
+        type: 'low_confidence',
+        message,
+    }));
+    return { coverage: { status, languages, blind_spots: blindSpots }, warnings };
+}
 // =============================================================================
 // MAIN SCANNER
 // =============================================================================
 /**
  * Run a full architecture scan
  */
+/**
+ * Does a timeline diff agree with the component count the scan actually
+ * persisted?
+ *
+ * A diff whose `components_after` disagrees with what was just written is
+ * describing a different scan than the one that happened. See the call site in
+ * `scan()` for the two real entries in this repo's own timeline that exhibit
+ * it, and why the resulting event is suppressed rather than repaired here (the
+ * root cause is upstream in the Phase 5 snapshot build; this boundary only
+ * refuses to make it durable).
+ *
+ * Returns false when there is no diff at all, so the caller's ternary handles
+ * both "nothing to report" and "cannot be trusted" the same way.
+ */
+export function isDiffConsistentWithScan(entry, finalComponentCount) {
+    if (!entry?.diff)
+        return false;
+    return entry.diff.stats.components_after === finalComponentCount;
+}
 export async function scan(projectRoot, options = {}) {
     const startTime = Date.now();
     const root = projectRoot || process.cwd();
-    const config = getConfig();
+    // Each scan owns its configuration snapshot. Call-level overrides must never
+    // mutate the cached process-wide config because a busy contender can overlap
+    // a winning scan in the same process.
+    const config = { ...getConfig() };
+    // R6 footprint fix: CLI/programmatic option overrides config flag.
+    if (options.perEntityFiles !== undefined) {
+        config.perEntityFiles = options.perEntityFiles;
+    }
+    // Degrade scan behavior per-capability, only for the restriction that
+    // capability actually needs. A permissive-but-detected environment like CI
+    // (`CI=true` sets sandbox.enabled but leaves every restriction false) is
+    // fully capable and MUST run a complete scan — otherwise AST-derived source
+    // components and child-process indexers silently vanish, which is exactly
+    // the code CI needs to exercise.
+    //
+    // Per-capability rule (do not force `quick`, `prompts: false`, or
+    // `useAST: false` from sandbox detection — that was the prior bug). Scope:
+    // the four bullets below describe the Phase-3 ANALYSIS capabilities only
+    // (src/scanners/, src/parsers/). scan() also does pre-analysis lease
+    // acquisition and post-analysis housekeeping that are NOT restriction-aware
+    // — see the paragraph after the bullets for those two exceptions.
+    // - SCIP (`options.scip` / NAVGATOR_SCIP=1) is the only genuine
+    //   child-process dependency among the analysis capabilities: scip-runner.ts
+    //   shells out via spawnSync. Disable it under `noChildProcess`.
+    // - `useAST` (ts-morph) and `prompts` (traceLLMCalls) both run in-process
+    //   and write nothing during analysis (verified: no spawn*/exec* and no
+    //   write call anywhere under src/scanners/ or src/parsers/ except
+    //   scip-runner.ts). Neither needs a child process nor write access, so no
+    //   restriction here disables them.
+    // - `quick` skips ALL of Phase 3 connection detection — a much bigger
+    //   hammer than any single restriction justifies. Never force it here.
+    // - `readOnlyFs` is recorded in `restrictions` for visibility. It disables
+    //   no analysis capability, since analysis itself performs no filesystem
+    //   writes (persistence happens in the separate storage.ts write path
+    //   after scan() returns).
+    //
+    // Two spots outside Phase-3 analysis do reach a child process or a real
+    // write, and neither is gated on these restrictions — both are safe under
+    // `noChildProcess` because the spawn call is try/caught with a fallback;
+    // `readOnlyFs` has one known gap, documented rather than fixed here:
+    // - `acquireScanLease` (below, ~line 637) runs BEFORE analysis starts.
+    //   `execFileSync('sysctl'/'ps'/'powershell.exe')` for owner-fingerprinting
+    //   (src/scan-lock.ts:88,112,124) is wrapped in try/catch per call, so the
+    //   spawn cannot crash the scan. It does NOT fall back to a best-effort
+    //   fingerprint: `defaultProcessFingerprint` returns `null` from its catch
+    //   and from its tail, and `acquireScanLease` then publishes a record with
+    //   no `owner_fingerprint`. That is not graceful degradation — under the
+    //   post-SEC-011 reclaim policy a fingerprintless record is fenced on
+    //   heartbeat age, so a live owner that is merely slow (suspend, SIGSTOP,
+    //   blocked event loop) can be reclaimed and admit a second writer. Only
+    //   `bootFingerprint()` has an uptime fallback. Tracked as a backlog item;
+    //   this comment previously claimed the opposite and reassured readers
+    //   about precisely the path that breaks. `fs.mkdirSync` + the lease-file
+    //   publish (src/scan-lock.ts:445,475) are real writes: the publish itself
+    //   is caught and returned as a structured `ScanLeaseResult` failure, but
+    //   the leading `mkdirSync` is not caught — on a filesystem that is
+    //   actually read-only it throws uncaught, and scan()'s
+    //   `!acquisition.retryable` branch a few lines below also throws rather
+    //   than returning a `degraded` result. This is a real, currently-unfixed
+    //   gap in `readOnlyFs` coverage (NavGator's own `readOnlyFs` flag is
+    //   advisory — nothing in this codebase gates a write on it, so nothing
+    //   here actually enforces a read-only mount, and the gap does not
+    //   reproduce against a normal filesystem). Behavior is unchanged from
+    //   before this comment was corrected; not addressed here to avoid turning
+    //   this change into a lease-subsystem refactor.
+    // - `ensureSafeGitignore` (below, ~line 2268) runs AFTER analysis
+    //   completes. `execFileSync('git', ...)` (src/gitignore-safety.ts:87) is
+    //   try/caught internally and falls back to treating the project as
+    //   outside a git worktree. The `.gitignore` rewrite is a real write, but
+    //   the call site wraps the whole `ensureSafeGitignore` call in a
+    //   non-fatal try/catch — a failure there never fails the scan. The
+    //   orphan-file purge after analysis (scanner.ts ~1852) is a real write
+    //   too, but each unlink is individually swallowed (`.catch(() => {})`).
+    const sandbox = detectSandbox();
+    let degraded;
+    {
+        const restrictions = [];
+        const disabledCapabilities = [];
+        if (sandbox.enabled && sandbox.restrictions.noChildProcess) {
+            restrictions.push('noChildProcess');
+            options.scip = false;
+            disabledCapabilities.push('scip');
+        }
+        if (sandbox.enabled && sandbox.restrictions.readOnlyFs) {
+            restrictions.push('readOnlyFs');
+        }
+        if (disabledCapabilities.length > 0) {
+            const messageParts = [
+                'Scan ran without the SCIP overlay because the environment restricts child processes (noChildProcess).',
+            ];
+            if (restrictions.includes('readOnlyFs')) {
+                messageParts.push('The environment also reports a read-only filesystem (readOnlyFs); no additional capability was disabled for it because Phase-3 analysis performs no filesystem writes.');
+            }
+            degraded = {
+                restrictions,
+                disabled_capabilities: disabledCapabilities,
+                message: messageParts.join(' '),
+            };
+        }
+    }
+    // Opt-in branch tracking
+    let gitInfo;
+    if (options.trackBranch) {
+        const info = await getGitInfo(root);
+        if (info) {
+            gitInfo = info;
+            if (options.verbose) {
+                console.log(`Branch tracking: ${info.branch} @ ${info.commit}`);
+            }
+        }
+    }
     if (options.verbose) {
         console.log(`Scanning project: ${root}`);
     }
-    // Clear existing data if requested
-    if (options.clearFirst) {
-        await clearStorage(config, root);
-    }
-    // Ensure storage directories exist
-    ensureStorageDirectories(config, root);
     // ==========================================================================
-    // Phase 0: File Discovery & Change Detection
+    // Phase 0.0: Concurrency lock (Run 1.6 — item #4)
     // ==========================================================================
-    const sourceFiles = await glob('**/*.{ts,tsx,js,jsx,py,swift,h,m}', {
-        cwd: root,
-        ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**', '__pycache__/**', 'venv/**', '.git/**', '.build/**', 'DerivedData/**', '.swiftpm/**', 'Pods/**'],
-    });
-    let fileChanges;
-    if (!options.clearFirst) {
-        fileChanges = await detectFileChanges(sourceFiles, root, config);
+    // Prevent two `navgator scan` processes corrupting each other's
+    // .navgator/architecture/ output. A heartbeat reports liveness; dead owners
+    // and stale unreadable records recover safely. Live contention returns `busy`.
+    const requestedScanType = options.mode ?? (options.clearFirst ? 'full' : options.incremental ? 'incremental' : 'auto');
+    const ownsLease = options._scanLease === undefined;
+    const acquisition = options._scanLease
+        ? { ok: true, lease: options._scanLease }
+        : acquireScanLease(scanLockPath(root), requestedScanType);
+    if (!acquisition.ok) {
+        if (!acquisition.retryable) {
+            throw new Error(acquisition.message);
+        }
+        if (options.verbose)
+            console.log(acquisition.message);
+        const duration = Date.now() - startTime;
+        return {
+            status: 'busy',
+            retryable: true,
+            message: acquisition.message,
+            components: [],
+            connections: [],
+            warnings: [],
+            stats: {
+                scan_duration_ms: duration,
+                components_found: 0,
+                connections_found: 0,
+                warnings_count: 0,
+                files_scanned: 0,
+                files_changed: 0,
+            },
+        };
+    }
+    const lease = acquisition.lease;
+    try {
+        await options._onLeaseAcquired?.();
+        // Storage initialization includes legacy-path migration and therefore must
+        // happen only while this scan owns the canonical writer lease. Lease
+        // acquisition itself creates only the lock parent directory.
+        ensureStorageDirectories(config, root);
+        // ==========================================================================
+        // Phase 0: File Discovery & Change Detection
+        // ==========================================================================
+        // Widened (coverage reporting, Chunk 2) beyond the languages any scanner
+        // consumes: go/rb/java/kt/cs/php/scala/c/cpp/cc/hpp files must be globbed
+        // and hashed too, or `computeScanCoverage` below can never count them and
+        // the "present but not analyzed" warning silently never fires for them —
+        // the same false-negative this change exists to close. None of these
+        // extensions feed a scanner; they exist in `scannableFiles` for coverage
+        // counting and change-detection hashing only.
+        const discoveredSourceFiles = await glob('**/*.{ts,tsx,js,jsx,mjs,cjs,py,swift,rs,h,m,go,rb,java,kt,cs,php,scala,c,cpp,cc,hpp}', {
+            cwd: root,
+            ignore: getIgnorePatterns(root),
+        });
+        const sourceFiles = excludeGitIgnoredFiles(root, discoveredSourceFiles);
+        const contentEnabled = options.content === true || process.env['NAVGATOR_CONTENT'] === '1';
+        const discoveredMarkdownFiles = contentEnabled
+            ? await glob('**/*.md', { cwd: root, ignore: getIgnorePatterns(root) })
+            : [];
+        const markdownFiles = excludeGitIgnoredFiles(root, discoveredMarkdownFiles);
+        const scannableFiles = [...sourceFiles, ...markdownFiles];
+        // For change detection, also include manifest files at the project root
+        // (and a few well-known nested ones). selectScanMode consults these to
+        // decide whether to force a full scan. Manifests are NOT scanned by the
+        // per-language scanners — they're tracked here only for change detection.
+        const manifestPatterns = [
+            'package.json',
+            'package-lock.json',
+            'pnpm-lock.yaml',
+            'yarn.lock',
+            'pyproject.toml',
+            'requirements.txt',
+            'requirements-dev.txt',
+            'requirements-test.txt',
+            'prisma/schema.prisma',
+            'Package.swift',
+            'Package.resolved',
+            'Podfile',
+            'Podfile.lock',
+            'Cartfile',
+            'Cartfile.resolved',
+            'Cargo.toml',
+            'Cargo.lock',
+            // Build / runtime config — track so changes trigger full scan
+            'tsconfig.json',
+            'jsconfig.json',
+            'vercel.json',
+            'fly.toml',
+            'railway.json',
+            '.gitignore',
+        ];
+        const manifestFiles = [];
+        for (const m of manifestPatterns) {
+            try {
+                const fs = await import('node:fs');
+                if (fs.existsSync(path.join(root, m)))
+                    manifestFiles.push(m);
+            }
+            catch {
+                // ignore
+            }
+        }
+        const rustManifestFiles = excludeGitIgnoredFiles(root, await glob('**/{Cargo.toml,Cargo.lock}', {
+            cwd: root,
+            ignore: getIgnorePatterns(root),
+        }));
+        for (const file of rustManifestFiles) {
+            if (!manifestFiles.includes(file))
+                manifestFiles.push(file);
+        }
+        const swiftManifestFiles = await glob('**/{Package.swift,Package.resolved,Podfile,Podfile.lock,Cartfile,Cartfile.resolved}', {
+            cwd: root,
+            ignore: getIgnorePatterns(root),
+        });
+        for (const file of swiftManifestFiles) {
+            if (!manifestFiles.includes(file))
+                manifestFiles.push(file);
+        }
+        const nestedModuleConfigFiles = await glob('**/{tsconfig.json,jsconfig.json}', {
+            cwd: root,
+            ignore: getIgnorePatterns(root),
+        });
+        for (const file of nestedModuleConfigFiles) {
+            if (!manifestFiles.includes(file))
+                manifestFiles.push(file);
+        }
+        const filesForChangeDetection = [...scannableFiles, ...manifestFiles];
+        // Detect file changes using prior hashes BEFORE any clearing.
+        // (Used by mode selection AND timeline summary even on full scans.)
+        let fileChanges;
+        fileChanges = await detectFileChanges(filesForChangeDetection, root, config);
+        // Freshness drains carry an immutable pre-scan ledger snapshot. Force those
+        // paths into the incremental walk even when hashes already match, because a
+        // prior scan may have persisted a late edit's hash without consuming it.
+        const forcedChangedFiles = normalizeForcedChangedFiles(options._forcedChangedFiles ?? [], root);
+        for (const forced of forcedChangedFiles) {
+            if (!fileChanges.added.includes(forced) &&
+                !fileChanges.modified.includes(forced) &&
+                !fileChanges.removed.includes(forced)) {
+                if (fs.existsSync(path.join(root, forced)))
+                    fileChanges.modified.push(forced);
+                else
+                    fileChanges.removed.push(forced);
+                fileChanges.unchanged = fileChanges.unchanged.filter((file) => file !== forced);
+            }
+        }
         if (options.verbose) {
             console.log(`File changes: ${formatFileChangeSummary(fileChanges)}`);
             if (fileChanges.added.length > 0 && fileChanges.added.length <= 5) {
@@ -52,283 +926,1571 @@ export async function scan(projectRoot, options = {}) {
                 console.log(`  Modified: ${fileChanges.modified.join(', ')}`);
             }
         }
-    }
-    const allComponents = [];
-    const allConnections = [];
-    const allWarnings = [];
-    let promptScanResultHolder;
-    let projectMetadata;
-    // ==========================================================================
-    // Phase 1: Package Detection
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 1: Scanning packages...');
-    }
-    // NPM packages
-    if (detectNpm(root)) {
-        if (options.verbose)
-            console.log('  - Detected npm/yarn/pnpm project');
-        const result = await scanNpmPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // Python packages
-    if (detectPip(root)) {
-        if (options.verbose)
-            console.log('  - Detected Python project');
-        const result = await scanPipPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // Swift/iOS/Mac packages (SPM, CocoaPods)
-    if (detectSpm(root)) {
-        if (options.verbose)
-            console.log('  - Detected Swift/Xcode project');
-        const result = await scanSpmPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // ==========================================================================
-    // Phase 2: Infrastructure Detection
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 2: Scanning infrastructure...');
-    }
-    const infraResult = await scanInfrastructure(root);
-    allComponents.push(...infraResult.components);
-    allWarnings.push(...infraResult.warnings);
-    // ==========================================================================
-    // Phase 3: Connection Detection (unless quick mode)
-    // ==========================================================================
-    if (!options.quick || options.connections) {
+        // ==========================================================================
+        // Phase 0.5: Scan-mode selection (Run 1 — D2)
+        // ==========================================================================
+        const priorIndex = await loadIndex(config, root);
+        const decision = selectScanMode(fileChanges, priorIndex, options);
+        // scanType captures the mode the scan ACTUALLY ran in (after potential
+        // integrity-check promotion). Initialized to the decision; may be promoted
+        // to 'incremental→full' below.
+        //
+        // Run 1.7 — Problem A: when this scan is the recursive re-entry from a
+        // failed integrity check (`_promotedFromIncremental === true`), `decision.mode`
+        // is 'full' (clearFirst forces it), but the user-visible scan_type should
+        // remain 'incremental→full' so timeline + stats consumers see the promotion
+        // evidence (Run 1.6 #3 contract). The actual scan body still runs as full.
+        let scanType = options._promotedFromIncremental ? 'incremental→full' : decision.mode;
+        if (options.verbose) {
+            console.log(`Scan mode: ${decision.mode} (${decision.reason})`);
+        }
+        // Compute walk-set for incremental: changedFiles ∪ reverseDeps
+        const changedSet = new Set();
+        if (fileChanges) {
+            for (const f of fileChanges.added)
+                changedSet.add(f);
+            for (const f of fileChanges.modified)
+                changedSet.add(f);
+            for (const f of fileChanges.removed)
+                changedSet.add(f);
+        }
+        let walkSet = new Set(changedSet);
+        if (decision.mode === 'incremental' && changedSet.size > 0) {
+            const reverseDeps = await loadReverseDeps(changedSet, config, root);
+            for (const f of reverseDeps)
+                walkSet.add(f);
+            if (options.verbose) {
+                console.log(`  Walk-set: ${changedSet.size} changed + ${reverseDeps.size} reverse-deps = ${walkSet.size} files`);
+            }
+        }
+        // Pass walkSet to scanners only on incremental. Full scans pass undefined to
+        // preserve bit-identical output (regression-locked by characterization snapshot).
+        const incWalkSet = decision.mode === 'incremental' ? walkSet : undefined;
+        // ==========================================================================
+        // Phase 0.6: Noop short-circuit (incremental + zero changes)
+        // ==========================================================================
+        if (decision.mode === 'incremental' && decision.reason === 'no-changes') {
+            // Nothing changed since last scan. Bump last_scan, update incrementals_since_full
+            // to 0 (no incremental work was done — but keep it as-is to honor the cap).
+            // Save fresh hashes (idempotent), update index timestamp, record noop timeline entry.
+            if (priorIndex) {
+                priorIndex.last_scan = Date.now();
+                // Note: incrementals_since_full and last_full_scan unchanged on noop.
+                await atomicWriteJSON(getIndexPath(config, root), priorIndex);
+            }
+            const fileHashes = await computeFileHashes(filesForChangeDetection, root);
+            await saveHashes(fileHashes, config, root);
+            const noopTimelineEntry = {
+                id: generateTimelineId(),
+                timestamp: Date.now(),
+                significance: 'patch',
+                triggers: [],
+                diff: {
+                    components: { added: [], removed: [], modified: [] },
+                    connections: { added: [], removed: [] },
+                    stats: {
+                        total_changes: 0,
+                        components_before: priorIndex?.stats.total_components ?? 0,
+                        components_after: priorIndex?.stats.total_components ?? 0,
+                        connections_before: priorIndex?.stats.total_connections ?? 0,
+                        connections_after: priorIndex?.stats.total_connections ?? 0,
+                    },
+                },
+                git: gitInfo,
+                scan_type: 'noop',
+                files_scanned: 0,
+            };
+            await saveTimelineEntry(noopTimelineEntry, config, root);
+            // Load existing components/connections so callers see the unchanged graph.
+            const existingComponents = await loadAllComponents(config, root);
+            const existingConnections = await loadAllConnections(config, root);
+            const duration = Date.now() - startTime;
+            if (options.verbose) {
+                console.log(`Scan complete (noop) in ${duration}ms`);
+            }
+            // A noop still re-globs `scannableFiles` (Phase 0 runs before this
+            // short-circuit), so the coverage table can be computed from the
+            // existing graph without a fresh Phase-3 pass — a repo whose blind spot
+            // was already disclosed on the prior scan must not go quiet on a noop.
+            const noopCoverage = computeScanCoverage(scannableFiles, existingComponents, existingConnections);
+            await options._beforeLeaseRelease?.();
+            return {
+                status: 'noop',
+                retryable: false,
+                components: existingComponents,
+                connections: existingConnections,
+                warnings: noopCoverage.warnings,
+                fileChanges,
+                timelineEntry: noopTimelineEntry,
+                gitInfo,
+                stats: {
+                    scan_duration_ms: duration,
+                    components_found: existingComponents.length,
+                    connections_found: existingConnections.length,
+                    warnings_count: noopCoverage.warnings.length,
+                    files_scanned: 0,
+                    files_changed: 0,
+                },
+                ...(degraded ? { degraded } : {}),
+                ...(noopCoverage.coverage ? { coverage: noopCoverage.coverage } : {}),
+            };
+        }
+        // For full scans: clear ALL prior data up front (legacy clearFirst semantics).
+        // For incremental: defer to Phase 4 (clearForFiles + merge).
+        if (decision.mode === 'full' || options.clearFirst) {
+            await clearStorage(config, root);
+            ensureStorageDirectories(config, root);
+        }
+        const allComponents = [];
+        const allConnections = [];
+        const allWarnings = [];
+        let promptScanResultHolder;
+        let projectMetadata;
+        // ==========================================================================
+        // Phase 1: Package Detection
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 1: Scanning packages...');
+        }
+        // Package scanners run in parallel (independent of each other).
+        //
+        // Multi-stack auto-discovery: if the project root has no stack manifest
+        // of its own, search nested wrapper directories and scan each subdir that does. This
+        // catches the common monorepo-lite shape — a top-level `frontend/` with
+        // package.json + a top-level `backend/` with pyproject.toml — that the
+        // legacy single-root behavior silently missed (it would only scan
+        // whichever side was at the root).
+        //
+        // Pass `singleStack: true` (CLI: --single-stack) to force the legacy
+        // behavior. Each component scanned from a subroot gets its origin tagged
+        // via `metadata.origin_root` so downstream layers can group by stack.
+        const stackRoots = options.singleStack
+            ? [{ path: root, origin: '.' }]
+            : discoverStackRoots(root, options.verbose === true);
+        {
+            const packageTasks = [];
+            for (const sr of stackRoots) {
+                const tagOrigin = (result) => {
+                    // Skip when origin is the root — keeps single-stack output identical.
+                    if (sr.origin === '.')
+                        return;
+                    for (const c of result.components) {
+                        const md = c.metadata ?? {};
+                        c.metadata = { ...md, origin_root: sr.origin };
+                        c.source.config_files = c.source.config_files.map(file => path.isAbsolute(file)
+                            ? file
+                            : path.posix.join(sr.origin, file.replace(/\\/g, '/')));
+                    }
+                    for (const warning of result.warnings) {
+                        if (warning.file && !path.isAbsolute(warning.file)) {
+                            warning.file = path.posix.join(sr.origin, warning.file.replace(/\\/g, '/'));
+                        }
+                    }
+                };
+                if (detectNpm(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected npm/yarn/pnpm project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanNpmPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+                if (detectPip(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected Python project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanPipPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+                if (detectSpm(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected Swift/Xcode project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanSpmPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+                if (detectCargo(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected Rust/Cargo project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanCargoPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+            }
+            await Promise.all(packageTasks);
+        }
+        // ==========================================================================
+        // Phase 1.5: Markdown content graph (opt-in)
+        // ==========================================================================
+        if (contentEnabled) {
+            if (options.verbose)
+                console.log('Phase 1.5: Scanning Markdown content links...');
+            const contentResult = await scanMarkdownContent(root, markdownFiles, incWalkSet);
+            allComponents.push(...contentResult.components);
+            allConnections.push(...contentResult.connections);
+            allWarnings.push(...contentResult.warnings);
+            if (options.verbose) {
+                console.log(`    Documents: ${contentResult.components.length}, links: ${contentResult.connections.length}, unresolved: ${contentResult.warnings.filter(w => w.type === 'unresolved_link').length}`);
+            }
+        }
+        // ==========================================================================
+        // Phase 2: Infrastructure Detection
+        // ==========================================================================
         if (options.verbose) {
-            console.log('Phase 3: Scanning connections...');
+            console.log('Phase 2: Scanning infrastructure...');
         }
-        if (options.useAST) {
-            // AST-based scanning (more accurate)
+        const infraResult = await scanInfrastructure(root);
+        allComponents.push(...infraResult.components);
+        allWarnings.push(...infraResult.warnings);
+        // Prisma schema → database models + relations
+        if (detectPrisma(root)) {
             if (options.verbose)
-                console.log('  - Running AST analysis (ts-morph)...');
+                console.log('  - Detected Prisma schema');
             try {
-                const astResult = await scanWithAST(root);
-                allComponents.push(...astResult.components);
-                allConnections.push(...astResult.connections);
-                allWarnings.push(...astResult.warnings);
-                // Also scan for database operations
-                if (options.verbose)
-                    console.log('  - Scanning database operations...');
-                const dbResult = await scanDatabaseOperations(root);
-                allComponents.push(...dbResult.components);
-                allConnections.push(...dbResult.connections);
-                allWarnings.push(...dbResult.warnings);
+                const prismaResult = await scanPrismaSchema(root);
+                allComponents.push(...prismaResult.components);
+                allConnections.push(...prismaResult.connections);
+                allWarnings.push(...prismaResult.warnings);
+                if (options.verbose) {
+                    console.log(`    Models: ${prismaResult.components.length}, Relations: ${prismaResult.connections.length}`);
+                }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `AST scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Prisma scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
-                // Fall back to regex scanning
-                if (options.verbose)
-                    console.log('  - Falling back to regex scanning...');
-                const serviceResult = await scanServiceCalls(root);
-                allComponents.push(...serviceResult.components);
-                allConnections.push(...serviceResult.connections);
-                allWarnings.push(...serviceResult.warnings);
             }
         }
-        else {
-            // Regex-based scanning (faster but less accurate)
+        // DB field usage analyzer (opt-in via FEATURE FLAG: fieldUsage)
+        let fieldUsageReportResult;
+        if (options.fieldUsage && canAnalyzeFieldUsage(root)) {
             if (options.verbose)
-                console.log('  - Scanning service calls (regex)...');
-            const serviceResult = await scanServiceCalls(root);
-            allComponents.push(...serviceResult.components);
-            allConnections.push(...serviceResult.connections);
-            allWarnings.push(...serviceResult.warnings);
-        }
-        // Swift code analysis (runtime deps, protocols, state, LLM calls)
-        if (detectSpm(root)) {
+                console.log('  - Analyzing DB field usage...');
+            try {
+                const fieldResult = await scanFieldUsage(root, incWalkSet);
+                allComponents.push(...fieldResult.components);
+                allConnections.push(...fieldResult.connections);
+                allWarnings.push(...fieldResult.warnings);
+                fieldUsageReportResult = fieldResult.report;
+                if (options.verbose && fieldResult.report) {
+                    const r = fieldResult.report;
+                    console.log(`    Fields: ${r.totalFields} total, ${r.unusedFields} unused, ${r.writeOnlyFields} write-only`);
+                }
+            }
+            catch (error) {
+                allWarnings.push({
+                    type: 'parse_error',
+                    message: `Field usage analysis failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                });
+            }
+        }
+        // TypeSpec validator (opt-in via FEATURE FLAG: typeSpec)
+        let typeSpecReportResult;
+        if (options.typeSpec && canValidateTypeSpec(root)) {
             if (options.verbose)
-                console.log('  - Scanning Swift code connections...');
+                console.log('  - Validating TypeSpec (Prisma vs TS interfaces)...');
             try {
-                const swiftResult = await scanSwiftCode(root);
-                allComponents.push(...swiftResult.components);
-                allConnections.push(...swiftResult.connections);
-                allWarnings.push(...swiftResult.warnings);
-                projectMetadata = swiftResult.projectMeta;
-                if (options.verbose) {
-                    console.log(`    Swift: ${swiftResult.components.length} components, ${swiftResult.connections.length} connections`);
-                    if (swiftResult.projectMeta.platforms) {
-                        console.log(`    Platforms: ${swiftResult.projectMeta.platforms.join(', ')}`);
+                const tsResult = await scanTypeSpecValidation(root);
+                allWarnings.push(...tsResult.warnings);
+                typeSpecReportResult = tsResult.report;
+                if (options.verbose && tsResult.report) {
+                    const r = tsResult.report;
+                    console.log(`    Interfaces: ${r.modelsWithInterfaces}/${r.modelsChecked} matched, ${r.totalMismatches} mismatches`);
+                }
+            }
+            catch (error) {
+                allWarnings.push({
+                    type: 'parse_error',
+                    message: `TypeSpec validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                });
+            }
+        }
+        // Env, queues, and crons are independent — run in parallel
+        {
+            const infraTasks = [];
+            if (detectEnvFiles(root)) {
+                if (options.verbose)
+                    console.log('  - Detected environment files');
+                infraTasks.push(scanEnvVars(root, incWalkSet).then(envResult => {
+                    allComponents.push(...envResult.components);
+                    allConnections.push(...envResult.connections);
+                    allWarnings.push(...envResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Env vars: ${envResult.components.length}, References: ${envResult.connections.length}`);
+                    }
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Env scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            if (detectQueues(root)) {
+                if (options.verbose)
+                    console.log('  - Detected queue system');
+                infraTasks.push(scanQueues(root, incWalkSet).then(queueResult => {
+                    allComponents.push(...queueResult.components);
+                    allConnections.push(...queueResult.connections);
+                    allWarnings.push(...queueResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Queues: ${queueResult.components.length}, Connections: ${queueResult.connections.length}`);
                     }
-                    if (swiftResult.projectMeta.architecture_pattern) {
-                        console.log(`    Architecture: ${swiftResult.projectMeta.architecture_pattern}`);
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Queue scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            if (detectCrons(root)) {
+                if (options.verbose)
+                    console.log('  - Detected cron jobs');
+                infraTasks.push(scanCronJobs(root, incWalkSet).then(cronResult => {
+                    allComponents.push(...cronResult.components);
+                    allConnections.push(...cronResult.connections);
+                    allWarnings.push(...cronResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Cron jobs: ${cronResult.components.length}, Route connections: ${cronResult.connections.length}`);
                     }
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Cron scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            await Promise.all(infraTasks);
+        }
+        // Deployment config → detailed infra metadata
+        if (options.verbose)
+            console.log('  - Scanning deployment config...');
+        try {
+            const deployResult = await scanDeployConfig(root);
+            allComponents.push(...deployResult.components);
+            allConnections.push(...deployResult.connections);
+            allWarnings.push(...deployResult.warnings);
+            if (options.verbose && deployResult.components.length > 0) {
+                console.log(`    Deploy configs: ${deployResult.components.length}, Entry points: ${deployResult.connections.length}`);
+            }
+        }
+        catch (error) {
+            allWarnings.push({
+                type: 'parse_error',
+                message: `Deploy config scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            });
+        }
+        // Prisma call detection: map source files to database models they query
+        const prismaModelComps = allComponents.filter(c => c.type === 'database' && c.tags?.includes('prisma'));
+        if (prismaModelComps.length > 0) {
+            if (options.verbose)
+                console.log('  - Scanning Prisma client calls...');
+            try {
+                const prismaCallResult = await scanPrismaCalls(root, prismaModelComps, incWalkSet);
+                allConnections.push(...prismaCallResult.connections);
+                if (options.verbose && prismaCallResult.connections.length > 0) {
+                    const uniqueModels = new Set(prismaCallResult.connections.map(c => c.description?.split(' queries ')[1]?.split(' ')[0]));
+                    console.log(`    DB queries: ${prismaCallResult.connections.length} file→model connections across ${uniqueModels.size} models`);
                 }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `Swift code scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Prisma call scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
             }
         }
-        // AI prompts & LLM call tracing
-        if (options.prompts) {
-            // Step 1: Run anchor-based LLM call tracer (primary detection)
+        // ==========================================================================
+        // Phase 3: Connection Detection (unless quick mode)
+        // ==========================================================================
+        if (!options.quick || options.connections) {
+            if (options.verbose) {
+                console.log('Phase 3: Scanning connections...');
+            }
+            if (options.useAST) {
+                // AST-based scanning (more accurate)
+                if (options.verbose)
+                    console.log('  - Running AST analysis (ts-morph)...');
+                try {
+                    const astResult = await scanWithAST(root, incWalkSet);
+                    allComponents.push(...astResult.components);
+                    allConnections.push(...astResult.connections);
+                    allWarnings.push(...astResult.warnings);
+                    // Also scan for database operations
+                    if (options.verbose)
+                        console.log('  - Scanning database operations...');
+                    const dbResult = await scanDatabaseOperations(root, incWalkSet);
+                    allComponents.push(...dbResult.components);
+                    allConnections.push(...dbResult.connections);
+                    allWarnings.push(...dbResult.warnings);
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `AST scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                    // Fall back to regex scanning
+                    if (options.verbose)
+                        console.log('  - Falling back to regex scanning...');
+                    const serviceResult = await scanServiceCalls(root, incWalkSet);
+                    allComponents.push(...serviceResult.components);
+                    allConnections.push(...serviceResult.connections);
+                    allWarnings.push(...serviceResult.warnings);
+                }
+            }
+            else {
+                // Regex-based scanning (faster but less accurate)
+                if (options.verbose)
+                    console.log('  - Scanning service calls (regex)...');
+                const serviceResult = await scanServiceCalls(root, incWalkSet);
+                allComponents.push(...serviceResult.components);
+                allConnections.push(...serviceResult.connections);
+                allWarnings.push(...serviceResult.warnings);
+            }
+            // File-level import graph (TS/JS + Python local imports)
             if (options.verbose)
-                console.log('  - Running LLM call tracer (anchor-based)...');
-            let traceResult;
+                console.log('  - Scanning file imports...');
             try {
-                traceResult = await traceLLMCalls(root);
-                allComponents.push(...traceResult.scanResult.components);
-                allConnections.push(...traceResult.scanResult.connections);
+                // Collect npm package components so bare imports (`import X from "react"`)
+                // can be resolved to the package component and emitted as `uses-package`
+                // edges. Use config_files filter instead of type filter: packages can be
+                // classified as 'npm' | 'framework' | 'database' | 'service' depending
+                // on FRAMEWORK_SIGNATURES, but all originate from a package.json. Pip
+                // packages get the same config_files-based treatment just below, keyed
+                // on requirements.txt / pyproject.toml instead — see `scanPipPackages`
+                // in `src/scanners/packages/pip.ts` for what actually produces them.
+                const npmKnownPackages = allComponents
+                    .filter(c => c.source.config_files?.some(f => f === 'package.json' || f.endsWith('/package.json')))
+                    .map(c => ({ name: c.name, component_id: c.component_id }));
+                // Pip components: match the manifests `scanPipPackages` (pip.ts)
+                // actually parses into components today (requirements.txt,
+                // pyproject.toml), plus requirements-*.txt / setup.py / Pipfile for
+                // forward compatibility if that scanner grows to parse them later.
+                // `scanPipPackages` never emits a setup.cfg-sourced component (it's
+                // not referenced anywhere in pip.ts), so that manifest is deliberately
+                // left out here rather than guessed at.
+                const PIP_MANIFEST_RE = /(^|\/)(requirements(-[\w.]+)?\.txt|pyproject\.toml|setup\.py|Pipfile)$/;
+                const pipComponents = allComponents.filter(c => c.source.config_files?.some(f => PIP_MANIFEST_RE.test(f.replace(/\\/g, '/'))));
+                // A pip distribution name and the name Python code actually imports
+                // can differ (`beautifulsoup4` -> `bs4`, `Pillow` -> `PIL`, ...).
+                // Deliberately partial — only the well-known mismatches that show up
+                // constantly in real requirements.txt files. An import head that
+                // isn't a known distribution name and isn't in this map resolves to
+                // nothing, matching the TS/JS bare-import contract: no match, no
+                // ghost node.
+                const PIP_IMPORT_ALIASES = {
+                    beautifulsoup4: 'bs4',
+                    pillow: 'PIL',
+                    pyyaml: 'yaml',
+                    'python-dateutil': 'dateutil',
+                    'scikit-learn': 'sklearn',
+                    'opencv-python': 'cv2',
+                    attrs: 'attr',
+                    'msgpack-python': 'msgpack',
+                    protobuf: 'google',
+                };
+                // PyPI distribution names treat '-', '_', and '.' as equivalent
+                // (PEP 503); canonicalize before consulting the alias map so
+                // `scikit_learn`/`scikit.learn`/`scikit-learn` all match the same key.
+                const canonicalPipName = (name) => name.toLowerCase().replace(/[._]+/g, '-');
+                const pipKnownPackages = [];
+                for (const c of pipComponents) {
+                    pipKnownPackages.push({ name: c.name, component_id: c.component_id });
+                    const alias = PIP_IMPORT_ALIASES[canonicalPipName(c.name)];
+                    if (alias)
+                        pipKnownPackages.push({ name: alias, component_id: c.component_id });
+                }
+                // `scanImports`'s `knownPackages` map is one flat namespace shared by
+                // both its TS/JS and Python bare-import passes (`KnownPackage` in
+                // `src/scanners/connections/import-scanner.ts` carries no ecosystem
+                // tag). Passing one merged npm+pip list would let a pip package
+                // cross-link to a same-named npm package or vice versa (e.g. a pip
+                // `requests` resolving to an npm `requests`). Instead, call
+                // `scanImports` once per ecosystem's own file set with only that
+                // ecosystem's package list — the TS/JS call never sees a .py file and
+                // the pip call never sees a TS/JS file, so neither list's names can
+                // leak into the other's resolution. The TS/JS call's inputs
+                // (non-Python files, npm-only package list) are unchanged from
+                // before this split, so its output is unchanged too.
+                const pythonSourceFiles = sourceFiles.filter(f => f.replace(/\\/g, '/').endsWith('.py'));
+                const nonPythonSourceFiles = sourceFiles.filter(f => !f.replace(/\\/g, '/').endsWith('.py'));
+                // Import resolution needs the complete source-file universe even when
+                // only a subset of origins is dirty. Otherwise an unchanged local target
+                // is absent from knownFiles and a valid edge silently disappears. Scan
+                // against the complete universe, then retain only dirty-origin edges for
+                // the incremental delta.
+                const tsJsImportResult = await scanImports(root, nonPythonSourceFiles, npmKnownPackages);
+                const pythonImportResult = pythonSourceFiles.length > 0
+                    ? await scanImports(root, pythonSourceFiles, pipKnownPackages)
+                    : { components: [], connections: [], warnings: [] };
+                const importResult = {
+                    components: [...tsJsImportResult.components, ...pythonImportResult.components],
+                    connections: [...tsJsImportResult.connections, ...pythonImportResult.connections],
+                    warnings: [...tsJsImportResult.warnings, ...pythonImportResult.warnings],
+                };
+                const importConnections = incWalkSet
+                    ? importResult.connections.filter(connection => {
+                        const origin = connection.code_reference?.file?.replace(/\\/g, '/');
+                        return origin !== undefined && incWalkSet.has(origin);
+                    })
+                    : importResult.connections;
+                allComponents.push(...importResult.components);
+                allConnections.push(...importConnections);
                 if (options.verbose) {
-                    console.log(`    Traced ${traceResult.calls.length} LLM call sites`);
-                    console.log(`    Wrappers: ${traceResult.wrappers.length}`);
-                    const providers = new Map();
-                    for (const call of traceResult.calls) {
-                        const p = call.provider.name;
-                        providers.set(p, (providers.get(p) || 0) + 1);
+                    const usesPkgCount = importConnections.filter(c => c.connection_type === 'uses-package').length;
+                    console.log(`    Found ${importResult.components.length} internal modules, ${importConnections.length} file-level imports (${usesPkgCount} uses-package)`);
+                }
+                // SCIP overlay (T11): when --scip / NAVGATOR_SCIP=1, run the
+                // compiler-accurate indexer and ADD any cross-file edges the regex
+                // import-scanner missed (re-exports, dynamic imports, type-only refs,
+                // etc.). Existing edges from the regex pass are preserved as-is so
+                // the characterization snapshots stay stable for non-SCIP runs.
+                // An explicit `scip: false` overrides the ambient NAVGATOR_SCIP=1 opt-in.
+                // The sandbox degradation block sets exactly that when `noChildProcess`
+                // is active, and SCIP is the one pass that shells out (spawnSync in
+                // scip-runner.ts). Reading the env var alone would spawn a child process
+                // in an environment that forbids one. The prior code masked this by
+                // forcing `quick`, which skipped all of Phase 3 including this block.
+                const scipRequested = process.env['NAVGATOR_SCIP'] === '1' || options.scip === true;
+                const scipEnabled = scipRequested && options.scip !== false;
+                if (scipEnabled) {
+                    try {
+                        const { runScip, crossFileEdges, hasTsConfig } = await import('./parsers/scip-runner.js');
+                        if (!hasTsConfig(root)) {
+                            if (options.verbose)
+                                console.log('    SCIP requested but no tsconfig.json — skipping');
+                        }
+                        else {
+                            if (options.verbose)
+                                console.log('  - Running SCIP indexer (compiler-accurate)...');
+                            const scipResult = await runScip(root, { timeoutMs: 60_000 });
+                            if (!scipResult.ok) {
+                                allWarnings.push({
+                                    type: 'parse_error',
+                                    message: `SCIP indexer failed: ${scipResult.error}`,
+                                });
+                            }
+                            else {
+                                const cross = crossFileEdges(scipResult.edges);
+                                const fileToComponentId = new Map();
+                                for (const c of importResult.components) {
+                                    const f = c.source?.config_files?.[0];
+                                    if (f)
+                                        fileToComponentId.set(f, c.component_id);
+                                }
+                                const existing = new Set(importResult.connections
+                                    .filter((c) => c.connection_type === 'imports')
+                                    .map((c) => `${c.from?.location?.file ?? ''}→${c.code_reference?.file ?? ''}`));
+                                let added = 0;
+                                const now = Date.now();
+                                for (const e of cross) {
+                                    const fromId = fileToComponentId.get(e.from_file);
+                                    const toId = fileToComponentId.get(e.to_file ?? '');
+                                    if (!fromId || !toId)
+                                        continue;
+                                    const key = `${e.from_file}→${e.to_file}`;
+                                    if (existing.has(key))
+                                        continue;
+                                    existing.add(key);
+                                    allConnections.push({
+                                        connection_id: `CONN_imports_scip_${Math.random().toString(36).slice(2, 10)}`,
+                                        from: {
+                                            component_id: fromId,
+                                            location: { file: e.from_file, line: e.from_line + 1 },
+                                        },
+                                        to: { component_id: toId },
+                                        connection_type: 'imports',
+                                        code_reference: {
+                                            file: e.from_file,
+                                            symbol: e.display_name || e.symbol.split('/').pop()?.slice(0, 40) || 'scip-ref',
+                                            symbol_type: e.is_definition ? 'export' : 'import',
+                                            line_start: e.from_line + 1,
+                                        },
+                                        description: 'SCIP-resolved cross-file reference',
+                                        detected_from: 'scip-typescript',
+                                        confidence: 0.99,
+                                        timestamp: now,
+                                        last_verified: now,
+                                    });
+                                    added++;
+                                }
+                                if (options.verbose) {
+                                    console.log(`    SCIP added ${added} cross-file edges (${scipResult.duration_ms}ms, ${scipResult.documents_indexed} docs)`);
+                                }
+                            }
+                        }
                     }
-                    for (const [provider, count] of providers) {
-                        console.log(`      ${provider}: ${count} call sites`);
+                    catch (err) {
+                        allWarnings.push({
+                            type: 'parse_error',
+                            message: `SCIP overlay failed: ${err.message}`,
+                        });
                     }
                 }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `LLM call tracer failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Import scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
+            }
+            // Swift code analysis (runtime deps, protocols, state, LLM calls)
+            const swiftStackRoots = stackRoots.filter(sr => detectSpm(sr.path));
+            if (swiftStackRoots.length > 0) {
                 if (options.verbose)
-                    console.log(`    LLM tracer error: ${error instanceof Error ? error.message : 'Unknown'}`);
+                    console.log('  - Scanning Swift code connections...');
+                try {
+                    const swiftResult = await scanSwiftCode(root, incWalkSet);
+                    allComponents.push(...swiftResult.components);
+                    allConnections.push(...swiftResult.connections);
+                    allWarnings.push(...swiftResult.warnings);
+                    projectMetadata = swiftResult.projectMeta;
+                    if (options.verbose) {
+                        console.log(`    Swift: ${swiftResult.components.length} components, ${swiftResult.connections.length} connections`);
+                        if (swiftResult.projectMeta.platforms) {
+                            console.log(`    Platforms: ${swiftResult.projectMeta.platforms.join(', ')}`);
+                        }
+                        if (swiftResult.projectMeta.architecture_pattern) {
+                            console.log(`    Architecture: ${swiftResult.projectMeta.architecture_pattern}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Swift code scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }
+                // Xcode project analysis (.pbxproj + storyboards)
+                try {
+                    const { findXcodeProject } = await import('./scanners/packages/swift.js');
+                    for (const swiftRoot of swiftStackRoots) {
+                        const pbxprojPath = findXcodeProject(swiftRoot.path);
+                        if (!pbxprojPath)
+                            continue;
+                        if (options.verbose)
+                            console.log('  - Scanning Xcode project...');
+                        const { parseXcodeProject, mapTargetToComponent, mapSourceMembership } = await import('./scanners/xcode/pbxproj-parser.js');
+                        const xcodeData = parseXcodeProject(pbxprojPath);
+                        const timestamp = Date.now();
+                        for (const target of xcodeData.targets) {
+                            const comp = mapTargetToComponent(target, timestamp);
+                            if (swiftRoot.origin !== '.') {
+                                comp.metadata = { ...comp.metadata, origin_root: swiftRoot.origin };
+                                comp.source.config_files = comp.source.config_files.map(file => path.posix.join(swiftRoot.origin, path.basename(path.dirname(pbxprojPath)), file));
+                            }
+                            allComponents.push(comp);
+                            const targetForMapping = swiftRoot.origin === '.'
+                                ? target
+                                : {
+                                    ...target,
+                                    sourceFiles: target.sourceFiles.map(file => path.posix.join(swiftRoot.origin, file)),
+                                };
+                            const memberConns = mapSourceMembership(targetForMapping, comp.component_id, timestamp);
+                            if (swiftRoot.origin !== '.') {
+                                const pbxprojRelative = path.posix.join(swiftRoot.origin, path.basename(path.dirname(pbxprojPath)), 'project.pbxproj');
+                                for (const connection of memberConns) {
+                                    if (connection.from.location?.file === 'project.pbxproj') {
+                                        connection.from.location.file = pbxprojRelative;
+                                    }
+                                    if (connection.code_reference?.file === 'project.pbxproj') {
+                                        connection.code_reference.file = pbxprojRelative;
+                                    }
+                                }
+                            }
+                            allConnections.push(...memberConns);
+                        }
+                        // Enrich project metadata with Xcode target info
+                        if (projectMetadata) {
+                            projectMetadata.targets = xcodeData.targets.map(t => ({
+                                name: t.name,
+                                type: t.type,
+                                dependencies: t.frameworks,
+                            }));
+                            projectMetadata.xcodeProject = {
+                                path: swiftRoot.origin === '.'
+                                    ? pbxprojPath
+                                    : path.relative(root, pbxprojPath).replace(/\\/g, '/'),
+                                targets: xcodeData.targets.map(t => ({
+                                    name: t.name,
+                                    type: t.type,
+                                    bundleId: t.bundleId,
+                                })),
+                            };
+                        }
+                        if (options.verbose) {
+                            console.log(`    Xcode: ${xcodeData.targets.length} targets`);
+                        }
+                    }
+                    // Storyboard/XIB scanning
+                    const { scanStoryboards } = await import('./scanners/xcode/storyboard-scanner.js');
+                    const storyboardResult = await scanStoryboards(root);
+                    allComponents.push(...storyboardResult.components);
+                    allConnections.push(...storyboardResult.connections);
+                    if (options.verbose && storyboardResult.components.length > 0) {
+                        console.log(`    Storyboards: ${storyboardResult.components.length} VCs, ${storyboardResult.connections.length} segues`);
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Xcode project scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }
             }
-            // Step 2: Run regex prompt detector with corroboration (secondary — catches prompt definitions)
-            if (options.verbose)
-                console.log('  - Running prompt detector (corroboration-filtered)...');
-            promptScanResultHolder = await scanPrompts(root, {
-                includeRawContent: true,
-                detectVariables: true,
-                requireAPICallAnchor: true,
-                minCorroborationSignals: 2,
+            // Rust code analysis (modules, types, trait impls, use graph, LLM calls)
+            if (detectCargo(root)) {
+                if (options.verbose)
+                    console.log('  - Scanning Rust code connections...');
+                try {
+                    const rustResult = await scanRustCode(root, incWalkSet);
+                    allComponents.push(...rustResult.components);
+                    allConnections.push(...rustResult.connections);
+                    allWarnings.push(...rustResult.warnings);
+                    if (!projectMetadata || Object.keys(projectMetadata).length === 0) {
+                        projectMetadata = rustResult.projectMeta;
+                    }
+                    if (options.verbose) {
+                        console.log(`    Rust: ${rustResult.components.length} components, ${rustResult.connections.length} connections`);
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Rust code scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }
+            }
+            // AI prompts & LLM call tracing
+            if (options.prompts) {
+                // Step 1: Run anchor-based LLM call tracer (primary detection)
+                if (options.verbose)
+                    console.log('  - Running LLM call tracer (anchor-based)...');
+                let traceResult;
+                try {
+                    traceResult = await traceLLMCalls(root, incWalkSet);
+                    allComponents.push(...traceResult.scanResult.components);
+                    allConnections.push(...traceResult.scanResult.connections);
+                    if (options.verbose) {
+                        console.log(`    Traced ${traceResult.calls.length} LLM call sites`);
+                        console.log(`    Wrappers: ${traceResult.wrappers.length}`);
+                        const providers = new Map();
+                        for (const call of traceResult.calls) {
+                            const p = call.provider.name;
+                            providers.set(p, (providers.get(p) || 0) + 1);
+                        }
+                        for (const [provider, count] of providers) {
+                            console.log(`      ${provider}: ${count} call sites`);
+                        }
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `LLM call tracer failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                    if (options.verbose)
+                        console.log(`    LLM tracer error: ${error instanceof Error ? error.message : 'Unknown'}`);
+                }
+                // Step 2: Run regex prompt detector with corroboration (secondary — catches prompt definitions)
+                if (options.verbose)
+                    console.log('  - Running prompt detector (corroboration-filtered)...');
+                promptScanResultHolder = await scanPrompts(root, {
+                    includeRawContent: true,
+                    detectVariables: true,
+                    aggressive: true,
+                }, incWalkSet);
+                // Attach tracer results to prompt scan data (for web UI)
+                if (traceResult) {
+                    promptScanResultHolder.tracedCalls = traceResult.calls;
+                    promptScanResultHolder.summary.tracedCallSites = traceResult.calls.length;
+                }
+                // Convert prompt definitions to architecture format
+                const promptArchitecture = convertToArchitecture(promptScanResultHolder.prompts);
+                allComponents.push(...promptArchitecture.components);
+                allConnections.push(...promptArchitecture.connections);
+                allWarnings.push(...promptArchitecture.warnings);
+                if (options.verbose) {
+                    console.log(`    Found ${promptScanResultHolder.prompts.length} prompt definitions`);
+                    if (promptScanResultHolder.summary.byProvider) {
+                        for (const [provider, count] of Object.entries(promptScanResultHolder.summary.byProvider)) {
+                            console.log(`      ${provider}: ${count}`);
+                        }
+                    }
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 3.5: Semantic Classification
+        // ==========================================================================
+        if (allConnections.length > 0 && allComponents.length > 0) {
+            if (options.verbose) {
+                console.log('Phase 3.5: Classifying connections...');
+            }
+            const semantics = classifyAllConnections(allConnections, allComponents);
+            for (const conn of allConnections) {
+                const info = semantics.get(conn.connection_id);
+                if (info) {
+                    conn.semantic = info;
+                }
+            }
+            if (options.verbose) {
+                const byClass = new Map();
+                for (const [, info] of semantics) {
+                    byClass.set(info.classification, (byClass.get(info.classification) || 0) + 1);
+                }
+                for (const [cls, count] of byClass) {
+                    console.log(`  ${cls}: ${count}`);
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 4: Deduplicate & Store
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 4: Storing results...');
+        }
+        // Normalize in-repo ownership paths before they participate in identity.
+        // Absolute paths make stable ids machine-specific and break integrity checks
+        // that expect project-relative source files.
+        for (const component of allComponents) {
+            if (!component.source)
+                continue;
+            component.source.config_files = (component.source.config_files ?? []).map(file => {
+                if (!path.isAbsolute(file))
+                    return file.replace(/\\/g, '/');
+                const relative = path.relative(root, file);
+                if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                    return file.replace(/\\/g, '/');
+                }
+                return relative.replace(/\\/g, '/');
             });
-            // Attach tracer results to prompt scan data (for web UI)
-            if (traceResult) {
-                promptScanResultHolder.tracedCalls = traceResult.calls;
-                promptScanResultHolder.summary.tracedCallSites = traceResult.calls.length;
-            }
-            // Convert prompt definitions to architecture format
-            const promptArchitecture = convertToArchitecture(promptScanResultHolder.prompts);
-            allComponents.push(...promptArchitecture.components);
-            allConnections.push(...promptArchitecture.connections);
-            allWarnings.push(...promptArchitecture.warnings);
+        }
+        // Deduplicate components by (type, name, primary-source-file) within current scan.
+        //
+        // Run 1.7 — Problem B: the prior key was `component.name` alone. That
+        // collided cross-type — e.g., the file-level component for `lib/prisma.ts`
+        // (type='component', name='prisma') vs the Prisma DB component
+        // (type='database', name='prisma'). The DB component won on confidence;
+        // the file component was silently dropped. But the import-scanner had
+        // already emitted edges referencing the dropped file component_id —
+        // 410 orphan edges on the benchmark repo, which fired the integrity-promote and
+        // truncated the graph (Problem A's loud symptom).
+        //
+        // The fix keys by `${type}|${name}|${first-config-file}`:
+        //   • Different types coexist (was: collided).
+        //   • Same-type same-name from different paths coexist (was: collided —
+        //     `app/proxy.ts` and `proxy.ts` both produce a file-level component
+        //     named `proxy`; both are real, both must be kept). Path
+        //     disambiguation matches Run 1.6 verify #6's stable_id contract for
+        //     the 6 component types where `name` alone isn't unique.
+        //   • Same-type same-name same-file STILL dedupes (the genuine duplicate
+        //     case — AST + regex both detecting the same service call), with
+        //     highest confidence winning. For components with no config_files
+        //     (rare) the key falls back to `${type}|${name}|` and behaves like
+        //     the legacy by-name dedup within that type.
+        const componentMap = new Map();
+        for (const component of allComponents) {
+            const primaryFile = component.source?.config_files?.[0] ?? '';
+            const key = `${component.type}|${component.name}|${primaryFile}`;
+            const existing = componentMap.get(key);
+            if (!existing || component.source.confidence > existing.source.confidence) {
+                componentMap.set(key, component);
+            }
+        }
+        const uniqueComponents = Array.from(componentMap.values());
+        // Dedup drops the losing component, but scanners have already put its
+        // component_id on edges — that is exactly the orphan class described above,
+        // and it is still live: the Swift code scanner and the SwiftUI scanner both
+        // emit a `component` named e.g. `ChatView` with no config_files, so they
+        // share a dedup key and one is discarded along with every edge pointing at
+        // it. Remap those endpoints onto the survivor rather than leaving them
+        // dangling; the two components describe the same Swift type.
+        const droppedToSurvivor = new Map();
+        for (const component of allComponents) {
+            const primaryFile = component.source?.config_files?.[0] ?? '';
+            const survivor = componentMap.get(`${component.type}|${component.name}|${primaryFile}`);
+            if (survivor && survivor.component_id !== component.component_id) {
+                droppedToSurvivor.set(component.component_id, survivor.component_id);
+            }
+        }
+        if (droppedToSurvivor.size > 0) {
+            for (const conn of allConnections) {
+                const from = droppedToSurvivor.get(conn.from?.component_id ?? '');
+                if (from)
+                    conn.from.component_id = from;
+                const to = droppedToSurvivor.get(conn.to?.component_id ?? '');
+                if (to)
+                    conn.to.component_id = to;
+            }
+        }
+        // Deduplicate connections by composite key (within current scan)
+        // Keeps highest confidence when duplicates found (e.g., regex + AST detect same call)
+        const connectionMap = new Map();
+        for (const conn of allConnections) {
+            const key = `${conn.from.component_id}|${conn.to.component_id}|${conn.connection_type}|${conn.code_reference?.file || ''}:${conn.code_reference?.line_start || ''}`;
+            const existing = connectionMap.get(key);
+            if (!existing || conn.confidence > existing.confidence) {
+                connectionMap.set(key, conn);
+            }
+        }
+        const uniqueConnections = Array.from(connectionMap.values());
+        // (C) + (C2): resolve FILE: endpoints to claimed components, then synthesize
+        // one file-node per surviving on-disk path. Extracted to
+        // `resolveFileEndpoints` (Run 4 fix2 #4) so path aliases are normalized in
+        // one place and the behaviour is unit-testable without a full scan.
+        resolveFileEndpoints(uniqueComponents, uniqueConnections, root);
+        // Snapshot previous state before overwriting (for change tracking)
+        // Also load the pre-scan snapshot for diff computation
+        let preScanSnapshot = null;
+        if (!options.clearFirst && decision.mode !== 'full') {
+            try {
+                await createSnapshot('pre-scan', config, root);
+                preScanSnapshot = await loadLatestSnapshot(config, root);
+            }
+            catch {
+                // No previous data to snapshot — first scan
+            }
+        }
+        else if (decision.mode === 'full') {
+            // For full scans, still create a snapshot for diff (if prior data exists)
+            try {
+                preScanSnapshot = await loadLatestSnapshot(config, root);
+            }
+            catch {
+                // First-ever scan, no prior snapshot.
+            }
+        }
+        // ==========================================================================
+        // Phase 4 storage decision (Run 1 — D1 + D2):
+        //   - 'full': clearStorage was already done up front; now store everything fresh.
+        //   - 'incremental': clear ONLY components/connections that originate in the
+        //     walk-set, then merge the freshly-scanned uniqueComponents/Connections
+        //     with the survivors. Run integrity check; on failure, promote to full.
+        // ==========================================================================
+        let finalComponents = uniqueComponents;
+        let finalConnections = uniqueConnections;
+        if (decision.mode === 'incremental' && !options.clearFirst) {
+            // Snapshot the FULL prior on-disk component set BEFORE clearForFiles —
+            // we need it to remap surviving connections from old random component_ids
+            // to the new ones (since stable_id is the join key but connections
+            // reference component_id, which gets a fresh random suffix per scan).
+            const preClearComponents = await loadAllComponents(config, root);
+            const preClearConnections = await loadAllConnections(config, root);
+            // Partition the prior canonical generation in memory. This is required for
+            // the default consolidated layout: clearForFiles has no per-entity files
+            // to delete there, and reloading would resurrect stale JSONL records.
+            const partition = partitionPriorStateForFiles(preClearComponents, preClearConnections, walkSet, root);
+            // Clear only the touched subset.
+            await clearForFiles(config, root, walkSet);
+            const survivingComponents = partition.survivingComponents;
+            const survivingConnections = partition.survivingConnections;
+            // Populate stable_ids on the in-memory uniqueComponents BEFORE merging.
+            // Disk-loaded survivors get stable_ids from loadAllComponents, but
+            // freshly-scanned components don't have them set until storeComponents
+            // runs — and we merge BEFORE store. Without this, every fresh component
+            // looks like a new entry to mergeByStableId (because its key falls back
+            // to its random component_id), breaking dedup.
+            for (const c of uniqueComponents)
+                ensureStableIdPublic(c);
+            // Merge: incoming wins on stable_id collision (component) or composite key (connection).
+            // Components keyed by stable_id (or component_id fallback).
+            finalComponents = mergeByStableId(survivingComponents, uniqueComponents, (c) => c.stable_id ?? c.component_id);
+            // Build a remap: prior_component_id → new_component_id (via stable_id).
+            // Connections from disk reference OLD random component_ids; the freshly
+            // scanned components have NEW random component_ids. Same stable_id ties
+            // them together. Rewrite surviving connection from/to ids so the merged
+            // graph stays consistent.
+            const stableToNewId = new Map();
+            for (const c of finalComponents) {
+                if (c.stable_id)
+                    stableToNewId.set(c.stable_id, c.component_id);
+            }
+            // oldIdToStable: maps every PRIOR-scan component_id (including ones we
+            // just deleted via clearForFiles) to its stable_id. Built from the
+            // pre-clear snapshot so we can resolve connection refs to their new IDs.
+            const oldIdToStable = new Map();
+            for (const c of preClearComponents) {
+                if (c.stable_id)
+                    oldIdToStable.set(c.component_id, c.stable_id);
+            }
+            // Also map fresh components' ids → stable (no remap needed but keeps the
+            // rewrite loop a no-op for these instead of leaving them undefined).
+            for (const c of uniqueComponents) {
+                if (c.stable_id)
+                    oldIdToStable.set(c.component_id, c.stable_id);
+            }
+            function remapId(id) {
+                if (!id)
+                    return id;
+                if (id.startsWith('FILE:'))
+                    return id;
+                const stable = oldIdToStable.get(id);
+                if (stable) {
+                    const newId = stableToNewId.get(stable);
+                    if (newId)
+                        return newId;
+                }
+                return id; // No remap available — leave alone, integrity check may catch
+            }
+            // Rewrite surviving connections to use the latest component_ids.
+            for (const conn of survivingConnections) {
+                if (conn.from?.component_id) {
+                    conn.from.component_id = remapId(conn.from.component_id) ?? conn.from.component_id;
+                }
+                if (conn.to?.component_id) {
+                    conn.to.component_id = remapId(conn.to.component_id) ?? conn.to.component_id;
+                }
+            }
+            // Connections keyed by from|to|type|file:line composite (matches dedup key).
+            const connKey = (c) => `${c.from?.component_id ?? ''}|${c.to?.component_id ?? ''}|${c.connection_type}|${c.code_reference?.file ?? ''}:${c.code_reference?.line_start ?? ''}`;
+            finalConnections = mergeByStableId(survivingConnections, uniqueConnections, connKey);
+            // Integrity check: every connection endpoint must exist; every walk-set
+            // component must reference real source files. On failure → promote to full.
+            const integrity = await runIntegrityCheck(finalComponents, finalConnections, root, walkSet);
+            if (!integrity.ok) {
+                if (options.verbose) {
+                    console.log(`  Integrity check failed (${integrity.issues.length} issues) — promoting to full scan`);
+                    for (const issue of integrity.issues.slice(0, 3)) {
+                        console.log(`    ${issue}`);
+                    }
+                }
+                // ============================================================
+                // Run 1.7 — Problem A (recursive re-entry promote)
+                // ============================================================
+                // The pre-Run-1.7 promote reused the in-memory uniqueComponents/
+                // uniqueConnections that were just computed under the walk-set
+                // restriction. After Run 1.5's walk-set plumbing, those are NOT
+                // the full source tree — only the walk-set's slice of it. Reusing
+                // them on promote truncated the graph (the benchmark repo: 6,445 → 58
+                // connections, 2,452 → 58 components).
+                //
+                // Fix: recursively re-enter scan() with `mode: 'full', clearFirst: true`
+                // while reusing this owner-safe lease. The inner scan walks the full
+                // source tree without opening a second writer window, and its result
+                // is returned verbatim. The internal `_promotedFromIncremental`
+                // flag tells the inner scan to label its timeline entry and stats
+                // `scan_type: 'incremental→full'` — preserving the Run 1.6 #3
+                // evidence-preservation contract.
+                //
+                // We `return` early so the rest of the outer scan's phases
+                // (storage, timeline, manifest, hashes) don't double-run.
+                return await scan(root, {
+                    ...options,
+                    mode: 'full',
+                    clearFirst: true,
+                    incremental: false,
+                    _promotedFromIncremental: true,
+                    _scanLease: lease,
+                });
+            }
+            // ============================================================
+            // Run 1.7 — orphan-disk-file cleanup on successful incremental merge.
+            // ============================================================
+            // `clearForFiles` only deletes disk files whose `source.config_files`
+            // overlap the walk-set. Components produced by always-full scanners
+            // (npm/pip/swift packages, infra, prisma) don't list user source
+            // files in `config_files` (they list manifests / abs paths), so
+            // their disk files survive `clearForFiles`. After the merge, the
+            // freshly-scanned versions get NEW random `component_id`s and are
+            // written to NEW filenames. The OLD survivor files are now orphans:
+            // unreachable from `finalComponents` but still on disk.
+            //
+            // Pre-Run-1.7 this was masked by the always-failing integrity check
+            // on real projects (`clearStorage` on promote wiped the orphans).
+            // Now that integrity passes (Problem B fix), and the promote is
+            // recursive (Problem A fix), this latent bug surfaces as a doubling
+            // of `npm`/`database`/`config`/`infra` components per incremental.
+            //
+            // Fix: after the merge, walk the components/connections directories
+            // and unlink any file whose ID isn't in `finalComponents` /
+            // `finalConnections`. Idempotent and atomic per-file (unlink errors
+            // are silently swallowed — best-effort, matches the integrity-promote
+            // pattern). Connections also need this since their random IDs aren't
+            // stable across scans either.
+            {
+                const finalComponentIds = new Set(finalComponents.map((c) => c.component_id));
+                const finalConnectionIds = new Set(finalConnections.map((c) => c.connection_id));
+                const fsPromises = (await import('node:fs')).promises;
+                const purgeOrphans = async (dir, keepIds) => {
+                    try {
+                        const files = await fsPromises.readdir(dir);
+                        await Promise.all(files
+                            .filter((f) => f.endsWith('.json'))
+                            .map(async (f) => {
+                            const id = f.slice(0, -'.json'.length);
+                            if (!keepIds.has(id)) {
+                                await fsPromises.unlink(path.join(dir, f)).catch(() => { });
+                            }
+                        }));
+                    }
+                    catch {
+                        // Dir missing or unreadable — non-fatal.
+                    }
+                };
+                await purgeOrphans(getComponentsPath(config, root), finalComponentIds);
+                await purgeOrphans(getConnectionsPath(config, root), finalConnectionIds);
+            }
+        }
+        // External enrichment (structural axis): stamp boundary nodes (npm/service/
+        // llm/infra/spm/...) with cached canonical identity, latest version, docs, and
+        // a freshness verdict. Offline + sync — reads NavGator's own JSON cache, never
+        // the network, so it cannot slow or fail the scan. The freshness axis (network
+        // re-checks) runs separately via refreshExternal / the external-resolver agent.
+        try {
+            const cache = loadCache();
+            enrichFromCache(finalComponents, makeLookup(cache), Date.now());
+        }
+        catch {
+            /* enrichment is best-effort — never block persistence on it */
+        }
+        // Store final state (atomic per-file writes — see storage.ts).
+        await storeComponents(finalComponents, config, root);
+        await storeConnections(finalConnections, config, root);
+        // R6 footprint fix: clean up legacy per-entity files when the feature is
+        // disabled (default). Idempotent and best-effort — never blocks the scan.
+        // Surfaces a one-line notice when something actually got cleaned.
+        try {
+            const migrated = await migratePerEntityFiles(config, root);
+            if (options.verbose &&
+                (migrated.componentsRemoved > 0 ||
+                    migrated.connectionsRemoved > 0 ||
+                    migrated.dirsRemoved > 0)) {
+                console.log(`  R6 migration: removed ${migrated.componentsRemoved} legacy component file(s), ${migrated.connectionsRemoved} legacy connection file(s), ${migrated.dirsRemoved} now-empty dir(s)`);
+            }
+        }
+        catch {
+            // Best-effort.
+        }
+        // ==========================================================================
+        // Phase 4.5: SQC Audit (Run 2 — D4)
+        //
+        // Sample the just-stored output, run deterministic verifiers (+ structured
+        // LLM-judge payload in MCP mode), and update per-stratum EWMA state.
+        // Audit failure NEVER fails the scan — only updates the index's EWMA so the
+        // NEXT scan can auto-promote on detected drift.
+        // ==========================================================================
+        let auditReport;
+        if (!options.noAudit) {
+            try {
+                const planOpt = options.auditPlan
+                    ? (options.auditPlan.toUpperCase() === 'AQL'
+                        ? 'AQL'
+                        : options.auditPlan.toUpperCase() === 'SPRT'
+                            ? 'SPRT'
+                            : 'Cochran')
+                    : undefined;
+                const auditOpts = {
+                    plan: planOpt,
+                    isMcpMode: !!options.isMcpMode,
+                    priorEwma: priorIndex?.ewma,
+                    priorAuditCount: priorIndex?.audit_history_count ?? 0,
+                    forceCochran: !!priorIndex?.pending_drift_breach,
+                    // Run 4 fix2 #1: `navgator scan --scip` must reach the imports oracle;
+                    // this line was lost in a concurrent edit of the (C) block.
+                    scip: options.scip === true,
+                };
+                const r = await runAudit({ components: finalComponents, connections: finalConnections }, config, root, auditOpts);
+                if (r) {
+                    // Update EWMA snapshot from prior index. We do not write the index here —
+                    // the post-Phase-5 index annotation already runs (line ~1430) and we
+                    // hijack `priorIndex` via the loadIndex/atomicWriteJSON cycle there.
+                    const { ewma, anyBreach } = updateEwmaForAudit(priorIndex?.ewma ?? undefined, r);
+                    if (anyBreach)
+                        r.drift_breach = true;
+                    auditReport = r;
+                    // Stash on a local for the index-annotation block below to consume.
+                    // (We re-read priorIndex after the freshIndex write to merge ewma.)
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    auditReport.__ewma = ewma;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    auditReport.__anyBreach = anyBreach;
+                }
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[audit] skipped due to error:', err.message);
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 5: Architecture Diff
+        // ==========================================================================
+        let timelineEntry;
+        if (options.verbose) {
+            console.log('Phase 5: Computing architecture diff...');
+        }
+        try {
+            // Build the "current" side from the scan's own in-memory records rather
+            // than re-reading storage. On the full-scan path `clearStorage()` has
+            // already deleted `components.full.jsonl`/`connections.full.jsonl`, and
+            // they aren't rewritten until after this phase (Phase 5.6, below) — a
+            // storage read here would see 0 components even though `finalComponents`
+            // is about to be persisted with the real count. See
+            // `.build-loop/issues/scanner-full-scan-diff-reports-zero-after.md`.
+            const currentSnapshot = buildSnapshotFromRecords(finalComponents, finalConnections);
+            const diff = computeArchitectureDiff(preScanSnapshot, currentSnapshot);
+            const { significance, triggers } = classifySignificance(diff);
+            timelineEntry = {
+                id: generateTimelineId(),
+                timestamp: Date.now(),
+                significance,
+                triggers,
+                diff,
+                snapshot_id: currentSnapshot.snapshot_id,
+                git: gitInfo,
+                scan_type: scanType,
+                // Run 1.6 — item #3: report walk-set size for 'incremental' AND for the
+                // legacy in-place 'incremental→full' promote (which kept walkSet
+                // populated), so a silent integrity-promote didn't erase evidence
+                // that an incremental walk-set was attempted.
+                //
+                // Run 1.7 — Problem A: the recursive-re-entry promote runs as a true
+                // full scan (walkSet empty). Reporting `walkSet.size = 0` would be
+                // dishonest — the inner scan really did walk every source file.
+                // Report `scannableFiles.length` in that case. Run 1.6 #3 still holds:
+                // any future in-place promote path (walkSet populated under
+                // 'incremental→full') reports walk-set size.
+                // Use decision.mode (the EFFECTIVE scan mode) instead of scanType
+                // (the user-visible label). On the recursive-re-entry promote (Run 1.7
+                // Problem A), decision.mode='full' even though scanType='incremental→full',
+                // and walkSet may be populated by the still-modified file — but the inner
+                // scan walked the full source tree, so files_scanned must be scannableFiles.length.
+                files_scanned: decision.mode === 'incremental' && walkSet.size > 0
+                    ? walkSet.size
+                    : scannableFiles.length,
+                // Run 2 — D4: audit report (when produced).
+                ...(auditReport ? { audit: stripInternals(auditReport) } : {}),
+            };
+            // Only save timeline entry if there are changes (or first scan)
+            if (diff.stats.total_changes > 0 || !preScanSnapshot) {
+                await saveTimelineEntry(timelineEntry, config, root);
+            }
+            if (options.verbose) {
+                console.log(`  Significance: ${significance}`);
+                console.log(`  Changes: ${diff.stats.total_changes}`);
+                if (triggers.length > 0) {
+                    console.log(`  Triggers: ${triggers.join(', ')}`);
+                }
+            }
+        }
+        catch {
+            // Diff computation is non-critical
             if (options.verbose) {
-                console.log(`    Found ${promptScanResultHolder.prompts.length} prompt definitions`);
-                if (promptScanResultHolder.summary.byProvider) {
-                    for (const [provider, count] of Object.entries(promptScanResultHolder.summary.byProvider)) {
-                        console.log(`      ${provider}: ${count}`);
+                console.log('  Diff computation skipped (non-critical error)');
+            }
+        }
+        // Build index, graph, file map, and summary.
+        // R6: pass the in-memory final state so derived files don't depend on
+        // per-entity disk reads (which are now opt-in and empty by default).
+        const derivedData = { components: finalComponents, connections: finalConnections };
+        await buildIndex(config, root, projectMetadata, derivedData);
+        await buildGraph(config, root, derivedData);
+        await buildFileMap(config, root, derivedData);
+        // ==========================================================================
+        // Phase 5.4: Derived reverse-deps index + manifest (Run 1.6 — items #8 + #9)
+        // ==========================================================================
+        // The reverse-deps index lets the next incremental scan compute walk-set
+        // expansion from a single file open instead of walking every per-edge JSON.
+        // The manifest lists all derived artifacts with their generated_at stamps.
+        let reverseDepsEdgeCount;
+        try {
+            const result = await buildReverseDepsIndex(finalComponents, finalConnections, config, root);
+            reverseDepsEdgeCount = result.edge_count;
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[reverse-deps] index build skipped:', err.message);
+            }
+        }
+        try {
+            await buildDerivedManifest(config, root, { reverseDepsEdgeCount });
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[manifest] write skipped:', err.message);
+            }
+        }
+        // ==========================================================================
+        // Phase 5.5: Annotate index with mode-tracking fields (Run 1 — D2)
+        //   Run AFTER buildIndex so we can annotate the freshly-written index
+        //   without buildIndex needing to know about modes.
+        // ==========================================================================
+        try {
+            const freshIndex = await loadIndex(config, root);
+            if (freshIndex) {
+                if (scanType === 'full' || scanType === 'incremental→full') {
+                    freshIndex.last_full_scan = Date.now();
+                    freshIndex.incrementals_since_full = 0;
+                }
+                else if (scanType === 'incremental') {
+                    // Preserve last_full_scan from prior index; bump counter.
+                    if (priorIndex) {
+                        freshIndex.last_full_scan = priorIndex.last_full_scan ?? priorIndex.last_scan ?? 0;
                     }
+                    freshIndex.incrementals_since_full = (priorIndex?.incrementals_since_full ?? 0) + 1;
                 }
+                // Always set schema_version to current build's version.
+                freshIndex.schema_version = SCHEMA_VERSION;
+                freshIndex.stable_id_scheme = STABLE_ID_SCHEME_VERSION;
+                freshIndex.setup_phase = options._setupPhase ?? priorIndex?.setup_phase;
+                // Run 2 — D5: persist EWMA + audit history bookkeeping.
+                if (auditReport) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const stash = auditReport;
+                    if (stash.__ewma) {
+                        freshIndex.ewma = stash.__ewma;
+                    }
+                    freshIndex.audit_history_count = (priorIndex?.audit_history_count ?? 0) + 1;
+                    freshIndex.pending_drift_breach = !!stash.__anyBreach;
+                }
+                else if (priorIndex) {
+                    // No audit this run — preserve prior values.
+                    if (priorIndex.ewma)
+                        freshIndex.ewma = priorIndex.ewma;
+                    if (priorIndex.audit_history_count !== undefined) {
+                        freshIndex.audit_history_count = priorIndex.audit_history_count;
+                    }
+                    // Clear pending breach if we just promoted on it.
+                    if (priorIndex.pending_drift_breach && scanType !== 'incremental') {
+                        freshIndex.pending_drift_breach = false;
+                    }
+                    else if (priorIndex.pending_drift_breach !== undefined) {
+                        freshIndex.pending_drift_breach = priorIndex.pending_drift_breach;
+                    }
+                }
+                await atomicWriteJSON(getIndexPath(config, root), freshIndex);
             }
         }
-    }
-    // ==========================================================================
-    // Phase 4: Deduplicate & Store
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 4: Storing results...');
-    }
-    // Deduplicate components by name (within current scan)
-    const componentMap = new Map();
-    for (const component of allComponents) {
-        const existing = componentMap.get(component.name);
-        if (!existing || component.source.confidence > existing.source.confidence) {
-            componentMap.set(component.name, component);
-        }
-    }
-    const uniqueComponents = Array.from(componentMap.values());
-    // Deduplicate connections by composite key (within current scan)
-    // Keeps highest confidence when duplicates found (e.g., regex + AST detect same call)
-    const connectionMap = new Map();
-    for (const conn of allConnections) {
-        const key = `${conn.from.component_id}|${conn.to.component_id}|${conn.connection_type}|${conn.code_reference?.file || ''}:${conn.code_reference?.line_start || ''}`;
-        const existing = connectionMap.get(key);
-        if (!existing || conn.confidence > existing.confidence) {
-            connectionMap.set(key, conn);
-        }
-    }
-    const uniqueConnections = Array.from(connectionMap.values());
-    // Snapshot previous state before overwriting (for change tracking)
-    if (!options.clearFirst) {
+        catch {
+            // Non-fatal: mode-tracking annotation is best-effort.
+        }
+        // Compute graph-wide metrics (PageRank + Louvain communities) → metrics.json,
+        // and back-write per-component scores into component metadata so any consumer
+        // that loads a component sees them. Suppressed for graphs <20 nodes.
+        try {
+            const { computeAndStoreMetrics } = await import('./metrics/pagerank-louvain.js');
+            await computeAndStoreMetrics(config, root, {
+                components: finalComponents,
+                connections: finalConnections,
+            });
+        }
+        catch (err) {
+            // Non-fatal — scan still produces all other artifacts.
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[metrics] PageRank/Louvain skipped:', err.message);
+            }
+        }
+        await buildSummary(config, root, promptScanResultHolder, projectMetadata, timelineEntry, gitInfo, derivedData);
+        // R6: full-shape JSONL writers — the consolidated source of truth when
+        // per-entity files are disabled (the default). These carry the complete
+        // ArchitectureComponent / ArchitectureConnection objects so downstream
+        // loaders never need per-entity files. Always written; cheap (~2MB for
+        // benchmark-scale projects vs the 70MB per-entity sprawl).
+        try {
+            const { writeFullComponentsJsonl, writeFullConnectionsJsonl, } = await import('./storage/markdown-view.js');
+            const { getStoragePath: getStoragePathFn } = await import('./config.js');
+            const storeDir = getStoragePathFn(config, root);
+            await writeFullComponentsJsonl(storeDir, finalComponents);
+            await writeFullConnectionsJsonl(storeDir, finalConnections);
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[full-jsonl] skipped:', err.message);
+            }
+        }
+        // Markdown views + connections.jsonl (T3, trimmed scope).
+        // Derived from in-memory components/connections — JSON remains canonical.
+        // Emits .navgator/architecture/components-md/<type>/<slug>.md (Obsidian-readable,
+        // git-diff-friendly, ripgrep-targetable) and connections.jsonl.
+        // Disable via NAVGATOR_NO_MARKDOWN=1 if downstream tooling chokes.
+        if (process.env['NAVGATOR_NO_MARKDOWN'] !== '1') {
+            try {
+                const { writeComponentMarkdownViews, writeConnectionsJsonl } = await import('./storage/markdown-view.js');
+                const { getStoragePath: getStoragePathFn } = await import('./config.js');
+                const storeDir = getStoragePathFn(config, root);
+                await writeComponentMarkdownViews(storeDir, finalComponents, finalConnections);
+                await writeConnectionsJsonl(storeDir, finalComponents, finalConnections);
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[markdown-view] skipped:', err.message);
+                }
+            }
+        }
+        // Git-backed temporal snapshot (T5). Commits the .navgator/ directory to a
+        // NESTED git store at .navgator/.git — invisible to the parent repo
+        // (gitignored). OPT-IN: enable via NAVGATOR_COMMIT=1 or `--commit` scan
+        // flag. Per-scan git subprocess overhead is ~180ms; default is OFF to
+        // preserve the speed criterion.
+        if (process.env['NAVGATOR_COMMIT'] === '1' || options.commit === true) {
+            try {
+                const { commitScan } = await import('./temporal/git-store.js');
+                const { getStoragePath } = await import('./config.js');
+                const storeDir = getStoragePath(config, root);
+                const sha7 = (gitInfo?.commit ?? '').slice(0, 7);
+                const msg = `scan ${new Date().toISOString()}${sha7 ? ` @ ${sha7}` : ''}`;
+                const result = commitScan(storeDir, msg);
+                if (!result.ok && process.env['NAVGATOR_DEBUG']) {
+                    console.error('[temporal] commit failed:', result.error);
+                }
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[temporal] skipped:', err.message);
+                }
+            }
+        }
+        // Persist prompt scan results if available
+        if (promptScanResultHolder) {
+            await savePromptScan(promptScanResultHolder, config, root);
+        }
+        // Register project in global registry
+        try {
+            await registerProject(root, {
+                components: finalComponents.length,
+                connections: finalConnections.length,
+                prompts: promptScanResultHolder?.prompts.length ?? 0,
+            }, timelineEntry?.significance, gitInfo, 
+            // Already computed above (Phase 5); previously discarded at this
+            // boundary. Feeds gator-memory's 'architecture.changed' event.
+            //
+            // Gated on the diff agreeing with what this scan actually wrote. On the
+            // full-scan path `buildCurrentSnapshot` can read empty storage and
+            // produce a diff that says everything was removed: this repo's own
+            // timeline carries two such entries (TL_20260530080058 and
+            // TL_20260602062857, both `components_after: 0` with `total_changes:
+            // 636`) immediately before an entry reporting 265 components. Nothing
+            // was removed; the diff is simply wrong.
+            //
+            // That upstream defect predates gator-memory, but forwarding it here is
+            // what would make it DURABLE — written into a project's permanent
+            // milestone list and mirrored into build-loop-memory as an
+            // authoritative-looking narrative. Recording nothing is strictly better
+            // than recording a confident falsehood, so the event is suppressed
+            // rather than guessed at. The check is not a heuristic: the diff's own
+            // `components_after` must match the component count this scan just
+            // persisted, or the two disagree and the diff loses.
+            isDiffConsistentWithScan(timelineEntry, finalComponents.length)
+                ? {
+                    componentsAdded: timelineEntry.diff.components.added.length,
+                    componentsRemoved: timelineEntry.diff.components.removed.length,
+                    connectionsAdded: timelineEntry.diff.connections.added.length,
+                    connectionsRemoved: timelineEntry.diff.connections.removed.length,
+                }
+                : undefined);
+        }
+        catch {
+            // Non-critical
+        }
+        // ==========================================================================
+        // Phase 6: Save File Hashes
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 6: Saving file hashes...');
+        }
+        // Phase 6: hash both source files AND manifests so manifest edits are
+        // detectable on the next scan (selectScanMode uses this to fire 'manifest-changed').
+        await options._beforeHashSave?.();
+        const fileHashes = await computeFileHashes(filesForChangeDetection, root);
+        await saveHashes(fileHashes, config, root);
+        const duration = Date.now() - startTime;
+        const filesChanged = fileChanges
+            ? fileChanges.added.length + fileChanges.modified.length + fileChanges.removed.length
+            : scannableFiles.length;
+        // Coverage runs against `finalComponents`/`finalConnections` — the full
+        // merged state (incremental scans merge onto prior state; see
+        // `mergeByStableId` above), not just this scan's walk-set — so the report
+        // always describes the whole known graph, not only what just changed. Its
+        // warnings are pushed into `allWarnings` BEFORE `warnings_count` is read
+        // below, so a coverage gap is never silently absent from that count.
+        const scanCoverage = computeScanCoverage(scannableFiles, finalComponents, finalConnections);
+        allWarnings.push(...scanCoverage.warnings);
+        if (options.verbose) {
+            console.log(`\nScan complete in ${duration}ms`);
+            console.log(`  Components: ${finalComponents.length}`);
+            console.log(`  Connections: ${finalConnections.length}`);
+            console.log(`  Files scanned: ${scannableFiles.length}`);
+            console.log(`  Files changed: ${filesChanged}`);
+            console.log(`  Warnings: ${allWarnings.length}`);
+        }
+        // Gitignore safety guard: NavGator's per-config-var component files and
+        // NAVSUMMARY docs include parsed hostnames from .env files. They're
+        // regenerated on every scan, so there's no loss from keeping them local.
+        // Auto-add gitignore entries on first scan so hostnames don't drift into
+        // git history. Silent unless it makes a change.
         try {
-            await createSnapshot('pre-scan', config, root);
+            const guardResult = await ensureSafeGitignore(root);
+            if (guardResult.action === 'added' && options.verbose) {
+                console.log(`  NavGator safety guard: added gitignore block for architecture/components/COMP_config_*.json + NAVSUMMARY*.md`);
+            }
         }
         catch {
-            // No previous data to snapshot — first scan
-        }
-    }
-    // Clear old components/connections before storing new ones
-    // This ensures no duplicate accumulation across scans
-    await clearStorage(config, root);
-    ensureStorageDirectories(config, root);
-    // Store components and connections
-    await storeComponents(uniqueComponents, config, root);
-    await storeConnections(uniqueConnections, config, root);
-    // Build index, graph, file map, and summary
-    await buildIndex(config, root, projectMetadata);
-    await buildGraph(config, root);
-    await buildFileMap(config, root);
-    await buildSummary(config, root, promptScanResultHolder, projectMetadata);
-    // Persist prompt scan results if available
-    if (promptScanResultHolder) {
-        await savePromptScan(promptScanResultHolder, config, root);
+            // Non-fatal: scan already completed, gitignore guard is best-effort
+        }
+        await options._beforeLeaseRelease?.();
+        return {
+            status: 'completed',
+            retryable: false,
+            components: finalComponents,
+            connections: finalConnections,
+            warnings: allWarnings,
+            fileChanges,
+            promptScan: promptScanResultHolder,
+            fieldUsageReport: fieldUsageReportResult,
+            typeSpecReport: typeSpecReportResult,
+            timelineEntry,
+            gitInfo,
+            stats: {
+                scan_duration_ms: duration,
+                components_found: finalComponents.length,
+                connections_found: finalConnections.length,
+                warnings_count: allWarnings.length,
+                // Run 1.6 — item #3 / Run 1.7 — Problem A: walk-set size for incremental
+                // and for an in-place promote (walkSet populated). Recursive-re-entry
+                // promote (walkSet empty) reports actual scannable-file count.
+                // Use decision.mode (the EFFECTIVE scan mode) instead of scanType
+                // (the user-visible label). On the recursive-re-entry promote (Run 1.7
+                // Problem A), decision.mode='full' even though scanType='incremental→full',
+                // and walkSet may be populated by the still-modified file — but the inner
+                // scan walked the full source tree, so files_scanned must be scannableFiles.length.
+                files_scanned: decision.mode === 'incremental' && walkSet.size > 0
+                    ? walkSet.size
+                    : scannableFiles.length,
+                files_changed: filesChanged,
+                prompts_found: promptScanResultHolder?.prompts.length,
+            },
+            ...(degraded ? { degraded } : {}),
+            ...(scanCoverage.coverage ? { coverage: scanCoverage.coverage } : {}),
+        };
     }
-    // ==========================================================================
-    // Phase 5: Save File Hashes
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 5: Saving file hashes...');
-    }
-    const fileHashes = await computeFileHashes(sourceFiles, root);
-    await saveHashes(fileHashes, config, root);
-    const duration = Date.now() - startTime;
-    const filesChanged = fileChanges
-        ? fileChanges.added.length + fileChanges.modified.length + fileChanges.removed.length
-        : sourceFiles.length;
-    if (options.verbose) {
-        console.log(`\nScan complete in ${duration}ms`);
-        console.log(`  Components: ${uniqueComponents.length}`);
-        console.log(`  Connections: ${uniqueConnections.length}`);
-        console.log(`  Files scanned: ${sourceFiles.length}`);
-        console.log(`  Files changed: ${filesChanged}`);
-        console.log(`  Warnings: ${allWarnings.length}`);
+    catch (error) {
+        await options._onLeaseFailureBeforeRelease?.();
+        throw error;
+    }
+    finally {
+        // Run 1.6 — item #4: release the scan lock on every exit path
+        // (success, early-return, throw). Idempotent.
+        if (ownsLease)
+            lease.release();
     }
-    return {
-        components: uniqueComponents,
-        connections: uniqueConnections,
-        warnings: allWarnings,
-        fileChanges,
-        promptScan: promptScanResultHolder,
-        stats: {
-            scan_duration_ms: duration,
-            components_found: uniqueComponents.length,
-            connections_found: allConnections.length,
-            warnings_count: allWarnings.length,
-            files_scanned: sourceFiles.length,
-            files_changed: filesChanged,
-            prompts_found: promptScanResultHolder?.prompts.length,
-        },
-    };
 }
 /**
  * Quick scan - only packages, no code analysis
  */
 export async function quickScan(projectRoot) {
-    const result = await scan(projectRoot, { quick: true });
-    return {
-        components: result.components,
-        connections: result.connections,
-        warnings: result.warnings,
-    };
+    return scan(projectRoot, { quick: true });
 }
 /**
  * Scan only for AI prompts (detailed)
@@ -355,8 +2517,7 @@ export async function scanPromptsOnly(projectRoot, options = {}) {
     const result = await scanPrompts(root, {
         includeRawContent: true,
         detectVariables: true,
-        requireAPICallAnchor: true,
-        minCorroborationSignals: 2,
+        aggressive: true,
     });
     // Attach tracer data
     if (traceResult) {
@@ -372,6 +2533,94 @@ export async function scanPromptsOnly(projectRoot, options = {}) {
 export { formatPromptsOutput, formatPromptDetail } from './scanners/prompts/index.js';
 // Re-export tracer types
 export { traceLLMCalls } from './scanners/connections/llm-call-tracer.js';
+/**
+ * In-process debounce: tracks the timestamp of the last refresh ATTEMPT
+ * per resolved project root. If a second call arrives while a first is still
+ * in-flight (or was attempted within staleAfterMs), the second call returns
+ * {refreshed:false, reason:'fresh'} without dispatching a second scan.
+ *
+ * This prevents a polling loop on MCP `status` from fanning out N concurrent
+ * incremental scans. The map is module-scoped so it persists across calls
+ * within the same Node.js process lifetime.
+ */
+const _lastRefreshAttemptMs = new Map();
+export async function autoRefreshIfStale(projectRoot, options = {}) {
+    // Resolve opt-in / opt-out. Programmatic > env > default(true).
+    const envOptOut = process.env['NAVGATOR_AUTO_REFRESH'] === 'false';
+    const enabled = options.enabled ?? !envOptOut;
+    if (!enabled) {
+        return { refreshed: false, reason: 'disabled', message: 'auto-refresh disabled' };
+    }
+    const staleAfterMs = (options.staleAfterMinutes ?? 5) * 60 * 1000;
+    const root = projectRoot || process.cwd();
+    // Debounce: if a refresh was attempted for this root within staleAfterMs,
+    // return 'fresh' immediately rather than piling on a second scan.
+    // Stamp BEFORE any async work to close the race window — concurrent callers
+    // see the guard the moment the first call passes it.
+    const lastAttempt = _lastRefreshAttemptMs.get(root) ?? 0;
+    if (Date.now() - lastAttempt < staleAfterMs) {
+        return { refreshed: false, reason: 'fresh', message: 'refresh already in-flight or recently attempted' };
+    }
+    _lastRefreshAttemptMs.set(root, Date.now());
+    try {
+        const { loadIndex } = await import('./storage.js');
+        const config = getConfig();
+        const index = await loadIndex(config, root);
+        if (!index || !index.last_scan) {
+            return {
+                refreshed: false,
+                reason: 'no-index',
+                message: 'no prior scan — run `navgator scan` first',
+            };
+        }
+        const ageMs = Date.now() - index.last_scan;
+        if (ageMs < staleAfterMs) {
+            return {
+                refreshed: false,
+                reason: 'fresh',
+                message: `graph fresh (${Math.round(ageMs / 1000)}s old)`,
+            };
+        }
+        // Stale → let selectScanMode choose. Auto preserves mandatory full-scan
+        // triggers for manifests/config while ordinary source edits stay fast.
+        const scanFn = options.scanImpl ?? scan;
+        const { captureDirtySnapshot, reconcileClean } = await import('./freshness/drainer.js');
+        const dirtySnapshot = captureDirtySnapshot(root);
+        const result = await scanFn(root, {
+            mode: 'auto',
+            _forcedChangedFiles: dirtySnapshot.paths,
+            _beforeLeaseRelease: async () => reconcileClean(root, dirtySnapshot),
+        });
+        if (result.status === 'busy') {
+            // Contention is retryable. Do not reconcile (the graph was not updated),
+            // and remove the in-process debounce so the next read can retry.
+            _lastRefreshAttemptMs.delete(root);
+            return {
+                refreshed: false,
+                reason: 'busy',
+                message: result.message,
+            };
+        }
+        const changed = (result.fileChanges?.added.length ?? 0) +
+            (result.fileChanges?.modified.length ?? 0) +
+            (result.fileChanges?.removed.length ?? 0);
+        return {
+            refreshed: true,
+            reason: 'stale',
+            filesChanged: changed,
+            message: changed > 0
+                ? `↻ refreshed ${changed} changed file(s)`
+                : '↻ refreshed (no file changes)',
+        };
+    }
+    catch (err) {
+        return {
+            refreshed: false,
+            reason: 'error',
+            message: `auto-refresh failed: ${err instanceof Error ? err.message : 'unknown'}`,
+        };
+    }
+}
 /**
  * Get scan status/summary without running a full scan
  */