@cleocode/core 2026.10.21 → 2026.10.22-rc.ci.693

package/dist/nexus/freshness.js

@@ -13,25 +13,33 @@
  * @task T12316
  * @module nexus/freshness
  */
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import { getHeapStatistics } from 'node:v8';
 import { PARSER_WORKER_HEAP_MAX_MB } from '@cleocode/contracts/code-symbol.js';
+import { sql } from 'drizzle-orm';
 import { getConfigValue } from '../config/registry.js';
 import { readEnvOverride } from '../config.js';
 import { pushWarning } from '../output.js';
+import { getCleoDirAbsolute } from '../paths.js';
 import { getNexusDb } from '../store/nexus-sqlite.js';
 import { runNexusAnalysis } from './analyze-orchestrator.js';
-import { readFileManifest, readRunCost } from './graph-manifest.js';
+import { readActiveRefreshCooldown, readFileManifest, readRunCost, refreshCooldownApplies, writeRefreshCooldown, } from './graph-manifest.js';
+import { envSwitch, measureAgainstBase, missingIndexedPaths, NEXUS_ALLOW_STALE_ENV, } from './index-health.js';
+import { releasePidLock, takePidLock } from './pid-lock.js';
+export { DEFAULT_MAX_COMMITS_BEHIND, measureAgainstBase, NEXUS_ALLOW_STALE_ENV, probeNexusIndexHealth, readNexusStalePolicy, } from './index-health.js';
 /** Command that refreshes the index; incremental by default since T12315. */
 export const NEXUS_REFRESH_COMMAND = 'cleo nexus analyze';
-/** Default number of stale files an index query may refresh inline. */
+/**
+ * Retired file-count cap for an inline refresh (T14014): the size-scaled cost
+ * estimate against the budget decides. Kept as the reported default of the
+ * ignored `nexus.autoRefresh.maxFiles`.
+ */
 export const DEFAULT_AUTO_REFRESH_MAX_FILES = 25;
 /** Default wall-clock budget for an inline refresh. */
 export const DEFAULT_AUTO_REFRESH_BUDGET_MS = 60_000;
-/** Share of changed files above which analysis rebuilds fully (mirrors the pipeline). */
-const FULL_REBUILD_RATIO = 0.3;
 /**
  * Judge the queried symbol's own files against an assessment.
  * @param assessment - Assessment taken before the query ran.
@@ -49,25 +57,74 @@ export function judgeSymbolFiles(assessment, files) {
         symbolFile: stale ?? unique[0],
     };
 }
-/** Estimate a refresh from the last recorded run, or `null` when nothing is recorded. */
-function estimateRefreshMs(cost, staleFiles, fileCount) {
+/** Largest factor a recorded run's whole-graph cost is scaled up by (T14014). */
+const MAX_COST_SCALE = 4;
+/**
+ * Estimate a refresh from the last recorded run, or `null` when nothing is
+ * recorded (T14014).
+ *
+ * Every refresh re-resolves, re-clusters and republishes the whole graph, so
+ * that cost is scaled from the last run's per-file rate to today's file count
+ * (at most {@link MAX_COST_SCALE} times, so one small sample cannot vouch for
+ * a far larger repository). Files without an exact cache entry for this build
+ * are parsed at the last run's parse rate, whatever their staleness: a wiped
+ * cache or an extractor upgrade means a full parse. Decoding reused
+ * extractions is recorded apart (`reuseDecode`) and never inflates that rate.
+ */
+function estimateRefreshMs(cost, toParse, reusable, fileCount) {
     if (!cost)
         return null;
     const parseMs = cost.summary.phaseMs['parse'] ?? 0;
+    const decodeMs = cost.summary.phaseMs['reuseDecode'] ?? 0;
     const parsed = cost.summary.parsedFiles;
-    const fixedMs = Math.max(0, cost.durationMs - parseMs);
+    const resolved = Math.max(1, cost.summary.resolvedFiles);
+    const wholeGraphMs = Math.max(0, cost.durationMs - parseMs - decodeMs);
+    const scale = Math.max(1, fileCount / resolved);
+    if (scale > MAX_COST_SCALE)
+        return null;
     const perFileMs = parsed > 0 ? parseMs / parsed : 0;
-    const full = fileCount > 0 && staleFiles / fileCount > FULL_REBUILD_RATIO;
-    const reparsed = full ? Math.max(parsed, cost.summary.resolvedFiles) : staleFiles;
-    return Math.round(fixedMs + reparsed * perFileMs);
+    const perReusedMs = cost.summary.reusedFiles > 0 ? decodeMs / cost.summary.reusedFiles : 0;
+    return Math.round(wholeGraphMs * scale + toParse * perFileMs + reusable * perReusedMs);
+}
+/**
+ * Split the parseable files of the manifest (T14014) into those a refresh must
+ * parse (stale, or without an exact cache entry for this build) and those it
+ * can reuse (unchanged, same content hash, this build's extractor fingerprint).
+ * Files no extractor parses are neither.
+ */
+async function planParse(db, manifestFiles, stale) {
+    const { computeExtractorFingerprint, isParseablePath, parseCacheFingerprint } = await import('@cleocode/nexus/pipeline');
+    // The inline refresh parses under the default limits (T14016).
+    const fingerprint = parseCacheFingerprint(computeExtractorFingerprint());
+    const cached = new Map();
+    for (const [path, contentHash, entryFingerprint] of db.values(sql `SELECT path, content_hash, fingerprint FROM main._nexus_parse_cache`)) {
+        if (entryFingerprint === fingerprint &&
+            typeof path === 'string' &&
+            typeof contentHash === 'string')
+            cached.set(path, contentHash);
+    }
+    let reusable = 0;
+    let toParse = 0;
+    for (const [path, , , contentHash] of manifestFiles) {
+        if (!isParseablePath(path))
+            continue;
+        if (!stale.has(path) && cached.get(path) === contentHash)
+            reusable++;
+        else
+            toParse++;
+    }
+    // A new parseable file is stale but not yet in the manifest.
+    const known = new Set(manifestFiles.map(([path]) => path));
+    for (const path of stale)
+        if (isParseablePath(path) && !known.has(path))
+            toParse++;
+    return { toParse, reusable };
 }
 /** Render an estimate for humans and agents alike. */
-function describeEstimate(ms, staleFiles, fileCount) {
+function describeEstimate(ms, staleFiles, toParse) {
     if (staleFiles === 0)
         return 'none needed';
-    const kind = fileCount > 0 && staleFiles / fileCount > FULL_REBUILD_RATIO
-        ? 'full rebuild'
-        : `incremental, re-parses ~${staleFiles} file(s)`;
+    const kind = `re-parses ~${toParse} file(s), re-resolves the whole graph`;
     if (ms === null)
         return `unknown duration (${kind}; no previous analysis cost recorded)`;
     return `~${Math.max(1, Math.round(ms / 1000))}s (${kind})`;
@@ -146,6 +203,7 @@ async function assessWithStaleSet(projectRoot, sampleLimit = 10) {
         // T12474: an unreachable source root is an unassessable index, never a crash.
         const freshness = {
             ...base,
+            ...(await measureAgainstBase(db, manifest.sourceRoot, manifest.assessedAt)),
             indexed: true,
             status: 'unknown',
             lastIndexedAt: manifest.assessedAt,
@@ -165,23 +223,97 @@ async function assessWithStaleSet(projectRoot, sampleLimit = 10) {
         if (known.get(file.path)?.contentHash !== file.contentHash)
             stale.add(file.path);
     }
-    for (const path of known.keys())
-        if (!seen.has(path))
-            stale.add(path);
+    const unseen = [...known.keys()].filter((path) => !seen.has(path));
+    for (const path of unseen)
+        stale.add(path);
+    // T14021: unseen paths can be excluded files still on disk; only absent ones are missing.
+    const missing = missingIndexedPaths(manifest.sourceRoot, unseen);
     const fileCount = manifest.files.length;
-    const estimate = estimateRefreshMs(readRunCost(db), stale.size, fileCount);
+    const { toParse, reusable } = stale.size > 0 ? await planParse(db, manifest.files, stale) : { toParse: 0, reusable: 0 };
+    const cost = readRunCost(db);
+    const estimate = estimateRefreshMs(cost, toParse, reusable, fileCount);
     const freshness = {
         ...base,
+        ...(await measureAgainstBase(db, manifest.sourceRoot, manifest.assessedAt)),
         indexed: true,
         status: stale.size === 0 ? 'fresh' : 'stale',
         lastIndexedAt: manifest.assessedAt,
         fileCount,
         staleFileCount: stale.size,
         stalePaths: [...stale].sort().slice(0, sampleLimit),
-        refreshEstimate: describeEstimate(estimate, stale.size, fileCount),
+        missingFileCount: missing.length,
+        missingPaths: missing.slice(0, sampleLimit),
+        ...(cost?.summary.communitiesSkipped
+            ? { communitiesSkipped: cost.summary.communitiesSkipped }
+            : {}),
+        refreshEstimate: describeEstimate(estimate, stale.size, toParse),
         checkMs: Math.round(performance.now() - started),
     };
-    return { freshness, staleFiles: stale };
+    return { freshness, staleFiles: stale, refreshPlan: { toParse, reusable, estimateMs: estimate } };
+}
+/**
+ * The freshness block every index-sensitive answer carries as `data.freshness`.
+ *
+ * @param freshness - The assessment behind the answer.
+ * @returns Revision, base, commits behind, age and verdict.
+ */
+export function answerFreshness(freshness) {
+    return {
+        status: freshness.status,
+        indexedRevision: freshness.indexedRevision ?? null,
+        baseRef: freshness.baseRef ?? null,
+        commitsBehind: freshness.commitsBehind ?? null,
+        commitsBehindHead: freshness.commitsBehindHead ?? null,
+        changedFilesSinceIndex: freshness.changedFilesSinceIndex ?? null,
+        refreshCooldownUntil: freshness.refreshCooldownUntil ?? null,
+        ageDays: freshness.ageDays ?? null,
+        lastIndexedAt: freshness.lastIndexedAt,
+        missingFileCount: freshness.missingFileCount ?? null,
+        missingPaths: freshness.missingPaths ?? [],
+        communitiesSkipped: freshness.communitiesSkipped ?? null,
+    };
+}
+/**
+ * Whether a graph answer must be refused as stale: the index trails the
+ * checked-out HEAD by more than the policy allows, or the target is missing
+ * from an index that is stale for this checkout (commits behind HEAD or
+ * changed files), so it may exist in code the index never saw. Distance to the
+ * base branch (`commitsBehind`) is reported only: on a feature branch or
+ * worktree it grows as the base moves, and no reindex here could clear it.
+ *
+ * @param freshness - The assessment behind the answer.
+ * @param policy - The stale-answer policy.
+ * @param options - `targetMissing` when the query found no symbol; `projectRoot`
+ *   names the checkout in the reindex command.
+ * @returns The refusal, or `null` when the answer may stand.
+ * @example
+ * ```ts
+ * const refusal = staleIndexRefusal(freshness, policy, { projectRoot: root });
+ * if (refusal) return refusalEnvelope(refusal);
+ * ```
+ */
+export function staleIndexRefusal(freshness, policy, options = {}) {
+    if (policy.allowStale)
+        return null;
+    // Judged against what is checked out: a reindex here clears it on any branch
+    // or worktree. Distance to the base branch is reported, never refused on.
+    const behind = freshness.commitsBehindHead ?? null;
+    const tooFar = behind !== null && behind > policy.maxCommitsBehind;
+    const staleHere = freshness.status === 'stale' || (behind !== null && behind > 0);
+    if (!tooFar && !(options.targetMissing && staleHere))
+        return null;
+    const reason = tooFar
+        ? `The index is ${behind} commit(s) behind the checked-out HEAD (more than nexus.freshness.maxCommitsBehind = ${policy.maxCommitsBehind})`
+        : `The symbol is missing from an index that is stale for this checkout (${behind ?? 0} commit(s) behind HEAD, ${freshness.staleFileCount} changed file(s)); it may exist in code the index has not seen`;
+    const reindex = options.projectRoot
+        ? `${NEXUS_REFRESH_COMMAND} ${JSON.stringify(options.projectRoot)}`
+        : NEXUS_REFRESH_COMMAND;
+    return {
+        code: 'E_NEXUS_INDEX_STALE',
+        message: `${reason}; this answer would describe code that has changed.`,
+        fix: `${reindex} (then repeat the query); to accept the stale answer, pass --allow-stale (nexus impact, nexus context) or set ${NEXUS_ALLOW_STALE_ENV}=1`,
+        details: { ...answerFreshness(freshness), maxCommitsBehind: policy.maxCommitsBehind },
+    };
 }
 /**
  * Read the auto-refresh policy from `nexus.autoRefresh.*`, applying defaults.
@@ -210,15 +342,6 @@ export async function readNexusAutoRefreshPolicy(projectRoot) {
         return { ...policyFrom(false, maxFiles, budgetMs), disabledBy: 'CLEO_NEXUS_AUTO_REFRESH' };
     return policyFrom(enabled, maxFiles, budgetMs);
 }
-/** Read an on/off env value (`true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`); `undefined` otherwise. */
-function envSwitch(value) {
-    const text = String(value).trim().toLowerCase();
-    if (['true', '1', 'yes', 'on'].includes(text))
-        return true;
-    if (['false', '0', 'no', 'off'].includes(text))
-        return false;
-    return undefined;
-}
 /** Apply defaults to raw `nexus.autoRefresh.*` values. */
 function policyFrom(enabled, maxFiles, budgetMs) {
     return {
@@ -232,8 +355,8 @@ function policyFrom(enabled, maxFiles, budgetMs) {
     };
 }
 /**
- * Run a refresh in this thread, incrementally or not at all. Unbounded in
- * memory: {@link runRefreshInChild} runs it inside a heap-limited child process.
+ * Run a refresh in this thread, bounded by its budget. Unbounded in memory:
+ * {@link runRefreshInChild} runs it inside a heap-limited child process.
  *
  * @param input - The refresh to run.
  * @returns The refresh summary.
@@ -244,7 +367,8 @@ export async function runRefreshInProcess(input) {
         repoPath: input.repoPath,
         ...(input.includedRepositories ? { includedRepositories: input.includedRepositories } : {}),
         parserLimits: { signal: AbortSignal.timeout(input.budgetMs) },
-        requireIncremental: true,
+        // T14016: the same budget, as a deadline uninterruptible phases can check.
+        deadlineAt: Date.now() + input.budgetMs,
     });
     return { mode: summary.mode, reason: summary.reason };
 }
@@ -311,89 +435,235 @@ export async function runRefreshInChild(input, options = {}) {
         await handle.stop();
     }
 }
+/** Cooldown after an inline refresh fails or is aborted (T14014). */
+export const INLINE_REFRESH_COOLDOWN_MS = 30 * 60_000;
+/** A refresh parsing more than this many files (or 30% of them) needs `cleo run` admission. */
+const ADMISSION_FREE_PARSE_FILES = 25;
+/** Share of files above which a refresh needs `cleo run` admission. */
+const ADMISSION_FREE_PARSE_RATIO = 0.3;
+/**
+ * Indexed files above which every inline refresh needs `cleo run` admission
+ * (T14019): resolve, communities, flows and the republish run over the whole
+ * graph, so on a large repository they dominate memory even when one file is
+ * re-parsed.
+ */
+export const ADMISSION_GRAPH_FILES = 2_000;
+/** Admission footprint per indexed file of an inline refresh (T14019). */
+const REFRESH_BYTES_PER_INDEXED_FILE = 256 * 1024;
+/** Smallest admission footprint of an inline refresh (T14019). */
+const REFRESH_MIN_FOOTPRINT_BYTES = 256 * 1024 * 1024;
+/**
+ * The memory an inline refresh asks `cleo run` admission for (T14019): scaled
+ * to the graph it re-resolves (indexed files), at least
+ * {@link REFRESH_MIN_FOOTPRINT_BYTES}, at most the build class's footprint.
+ *
+ * @param indexedFiles - Files in the published generation.
+ * @param classBytes - Footprint of the `scoped-build` class on this machine.
+ * @returns Footprint in bytes.
+ * @example
+ * ```ts
+ * inlineRefreshFootprintBytes(10_000, footprintForClass('scoped-build'));
+ * ```
+ */
+export function inlineRefreshFootprintBytes(indexedFiles, classBytes) {
+    const scaled = Math.max(0, indexedFiles) * REFRESH_BYTES_PER_INDEXED_FILE;
+    return Math.min(classBytes, Math.max(REFRESH_MIN_FOOTPRINT_BYTES, scaled));
+}
+/** Fallback cooldown file under `.cleo/` when `_nexus_meta` cannot be written (T14014). */
+export const INLINE_REFRESH_COOLDOWN_FILE = 'nexus-refresh-cooldown.json';
+/** Last resort when neither the store nor the file can hold a cooldown. */
+let inProcessCooldown = null;
 /**
- * Assess freshness and, when only a few files are stale, refresh the index
+ * Record a cooldown: in `_nexus_meta`, else (SQLITE_BUSY while another
+ * analysis publishes, a read-only store) in a file under `.cleo/`, else in
+ * this process. Never throws: a failed write must not fail the query or lose
+ * the cooldown.
+ */
+function recordCooldown(db, cleoDir, cooldown) {
+    try {
+        writeRefreshCooldown(db, cooldown);
+        return;
+    }
+    catch {
+        // fall through to the file
+    }
+    try {
+        mkdirSync(cleoDir, { recursive: true });
+        writeFileSync(join(cleoDir, INLINE_REFRESH_COOLDOWN_FILE), JSON.stringify(cooldown));
+    }
+    catch {
+        inProcessCooldown = cooldown;
+    }
+}
+/** The cooldown in force from the store, its fallback file, or this process. */
+function activeCooldown(db, cleoDir) {
+    const applies = (cooldown) => {
+        try {
+            return cooldown && refreshCooldownApplies(db, cooldown) ? cooldown : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    let stored = null;
+    try {
+        stored = readActiveRefreshCooldown(db);
+    }
+    catch {
+        stored = null;
+    }
+    if (stored)
+        return stored;
+    let filed = null;
+    try {
+        filed = JSON.parse(readFileSync(join(cleoDir, INLINE_REFRESH_COOLDOWN_FILE), 'utf-8'));
+    }
+    catch {
+        filed = null;
+    }
+    return applies(filed) ?? applies(inProcessCooldown);
+}
+/** Lock file under `.cleo/`: one inline refresh at a time per project. */
+export const INLINE_REFRESH_LOCK_FILE = 'nexus-inline-refresh.lock';
+/** The production admitter: one non-waiting `cleo run` admission pass, sized to the graph. */
+const admitRefresh = async (projectRoot, indexedFiles) => {
+    const { admit, footprintForClass } = await import('../resources/admission-ledger.js');
+    const outcome = await admit({
+        label: 'nexus:inline-refresh',
+        footprintBytes: inlineRefreshFootprintBytes(indexedFiles, footprintForClass('scoped-build')),
+        cwd: projectRoot,
+        footprintReason: `inline NEXUS refresh re-resolving a ${indexedFiles}-file graph (T14014, T14019)`,
+    }, { wait: false, timeoutMs: 0 });
+    return outcome.admitted ? outcome.grant : { refused: outcome.refusal.reason };
+};
+/**
+ * Assess freshness and, when the refresh is affordable, refresh the index
  * inline before the caller answers from it.
  *
- * A refresh runs only when `0 < stale ≤ maxFiles` and the recorded cost
- * estimate fits `budgetMs`; the budget also cancels the run at its next phase
- * boundary, and publication is atomic, so an abandoned refresh leaves the
- * previous graph intact. Every decision — refreshed, skipped or failed — is
- * disclosed in `autoRefresh`, and the returned freshness describes the index
- * the caller is about to read.
+ * A refresh runs when the recorded cost, scaled to the repository and to the
+ * files it must parse (T14014), fits `budgetMs`. It is guarded so a stale
+ * index never turns every query into another heavy run:
+ * - one inline refresh at a time per project (a pid lock; a concurrent query
+ *   answers from the stale index);
+ * - a refresh beyond a small incremental set needs a non-waiting `cleo run`
+ *   admission, and is skipped when the machine is busy;
+ * - a refresh that fails or is aborted sets a cooldown: no inline refresh for
+ *   {@link INLINE_REFRESH_COOLDOWN_MS}, or until an analysis publishes a new
+ *   generation. The cooldown is reported as `refreshCooldownUntil`.
+ * The budget also cancels a run at its next check, and publication is atomic,
+ * so an abandoned refresh leaves the previous graph intact. Every decision is
+ * disclosed in `autoRefresh`.
  *
  * @param projectRoot - Project whose graph is about to be queried.
  * @param policy - Explicit policy; read from config when omitted.
  * @param runRefresh - Runs the refresh; a heap-bounded worker unless supplied (T13537).
+ * @param admitter - Admits a heavy refresh; `cleo run` admission unless supplied.
  * @returns Freshness of the index as it stands after any refresh, with its stale set.
  */
-export async function ensureNexusIndexFresh(projectRoot, policy, runRefresh = runRefreshInChild) {
+export async function ensureNexusIndexFresh(projectRoot, policy, runRefresh = runRefreshInChild, admitter = admitRefresh) {
     const initial = await assessWithStaleSet(projectRoot);
     const before = initial.freshness;
     if (before.status !== 'stale')
         return initial;
     const effective = policy ?? (await readNexusAutoRefreshPolicy(projectRoot));
-    const skip = (reason) => ({
+    const skip = (reason, cooldownUntil) => ({
         staleFiles: initial.staleFiles,
+        ...(initial.refreshPlan ? { refreshPlan: initial.refreshPlan } : {}),
         freshness: {
             ...before,
+            ...(cooldownUntil ? { refreshCooldownUntil: cooldownUntil } : {}),
             autoRefresh: { refreshed: false, staleFiles: before.staleFileCount, durationMs: 0, reason },
         },
     });
     if (!effective.enabled)
         return skip(`auto-refresh is disabled (${effective.disabledBy ?? 'nexus.autoRefresh.enabled = false'}); answered from the stale index`);
-    if (before.staleFileCount > effective.maxFiles)
-        return skip(`${before.staleFileCount} stale files exceed nexus.autoRefresh.maxFiles = ${effective.maxFiles}; ` +
-            'answered from the stale index');
-    // T13523: a read query never runs a full rebuild inline; the pipeline also
-    // refuses one it would fall back to (requireIncremental below).
-    if (before.fileCount > 0 && before.staleFileCount / before.fileCount > FULL_REBUILD_RATIO)
-        return skip(`${before.staleFileCount} of ${before.fileCount} files are stale, which needs a full rebuild; answered from the stale index (run ${NEXUS_REFRESH_COMMAND})`);
     const db = await getNexusDb(projectRoot);
-    const estimate = estimateRefreshMs(readRunCost(db), before.staleFileCount, before.fileCount);
-    // T13523: with no recorded cost there is no bound on the run (a full
-    // analysis, Leiden included, can exhaust the CLI heap), so do not start one.
+    const cleoDir = getCleoDirAbsolute(projectRoot);
+    const cooldown = activeCooldown(db, cleoDir);
+    if (cooldown)
+        return skip(`a recent inline refresh did not finish (${cooldown.reason}); no inline refresh until ${cooldown.until} or the next ${NEXUS_REFRESH_COMMAND}; answered from the stale index`, cooldown.until);
+    const plan = initial.refreshPlan;
+    const estimate = plan?.estimateMs ?? null;
+    // T13523: with no comparable recorded cost there is no bound on the run, so
+    // do not start one.
     if (estimate === null)
-        return skip(`no previous analysis cost recorded, so the refresh cannot be bounded; answered from the stale index (run ${NEXUS_REFRESH_COMMAND} to refresh and record one)`);
+        return skip(`no previous analysis cost recorded (or the repository has grown more than ${MAX_COST_SCALE}x since), so the refresh cannot be bounded; answered from the stale index (run ${NEXUS_REFRESH_COMMAND} to refresh and record one)`);
     if (estimate > effective.budgetMs)
         return skip(`estimated refresh ${Math.round(estimate / 1000)}s exceeds nexus.autoRefresh.budgetMs = ` +
             `${effective.budgetMs}; answered from the stale index`);
-    const manifest = readFileManifest(db, projectRoot);
-    const started = performance.now();
+    mkdirSync(cleoDir, { recursive: true });
+    const lockPath = join(cleoDir, INLINE_REFRESH_LOCK_FILE);
+    const holder = takePidLock(lockPath);
+    if (holder !== null)
+        return skip(`an inline refresh is already running${holder > 0 ? ` (pid ${holder})` : ''}; answered from the stale index`);
+    let grant = null;
     try {
-        const summary = await runRefresh({
-            projectRoot,
-            repoPath: manifest?.sourceRoot ?? projectRoot,
-            ...(manifest ? { includedRepositories: manifest.includedRepositories } : {}),
-            budgetMs: effective.budgetMs,
-        });
-        const after = await assessWithStaleSet(projectRoot);
-        return {
-            staleFiles: after.staleFiles,
-            freshness: {
-                ...after.freshness,
-                autoRefresh: {
-                    refreshed: summary.mode !== 'unchanged',
-                    staleFiles: before.staleFileCount,
-                    durationMs: Math.round(performance.now() - started),
-                    reason: `${summary.mode}: ${summary.reason}`,
+        const toParse = plan?.toParse ?? before.staleFileCount;
+        // T14019: the whole-graph phases make a large graph heavy even for one file.
+        const largeGraph = before.fileCount > (effective.admissionGraphFiles ?? ADMISSION_GRAPH_FILES);
+        const heavy = largeGraph ||
+            toParse > ADMISSION_FREE_PARSE_FILES ||
+            (before.fileCount > 0 && toParse / before.fileCount > ADMISSION_FREE_PARSE_RATIO);
+        if (heavy) {
+            const admitted = await admitter(projectRoot, before.fileCount);
+            if ('refused' in admitted)
+                return skip(`a refresh ${largeGraph ? `re-resolving a ${before.fileCount}-file graph` : `parsing ~${toParse} file(s)`} needs cleo run admission and the machine is busy (${admitted.refused}); answered from the stale index`);
+            grant = admitted;
+        }
+        const manifest = readFileManifest(db, projectRoot);
+        const started = performance.now();
+        const generation = db.values(sql `SELECT value FROM main._nexus_meta WHERE key = 'graph_generation'`)[0]?.[0];
+        try {
+            const summary = await runRefresh({
+                projectRoot,
+                repoPath: manifest?.sourceRoot ?? projectRoot,
+                ...(manifest ? { includedRepositories: manifest.includedRepositories } : {}),
+                budgetMs: effective.budgetMs,
+            });
+            const after = await assessWithStaleSet(projectRoot);
+            return {
+                staleFiles: after.staleFiles,
+                ...(after.refreshPlan ? { refreshPlan: after.refreshPlan } : {}),
+                freshness: {
+                    ...after.freshness,
+                    autoRefresh: {
+                        refreshed: summary.mode !== 'unchanged',
+                        staleFiles: before.staleFileCount,
+                        durationMs: Math.round(performance.now() - started),
+                        reason: `${summary.mode}: ${summary.reason}`,
+                    },
                 },
-            },
-        };
-    }
-    catch (error) {
-        return {
-            staleFiles: initial.staleFiles,
-            freshness: {
-                ...before,
-                autoRefresh: {
-                    refreshed: false,
-                    staleFiles: before.staleFileCount,
-                    durationMs: Math.round(performance.now() - started),
-                    reason: `refresh failed, previous graph retained: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // T14014: an aborted or failed refresh records no cost, so without a
+            // cooldown every query would start another one.
+            const until = new Date(Date.now() + INLINE_REFRESH_COOLDOWN_MS).toISOString();
+            recordCooldown(db, cleoDir, {
+                until,
+                generation: typeof generation === 'string' ? generation : null,
+                reason: message.slice(0, 300),
+            });
+            return {
+                staleFiles: initial.staleFiles,
+                ...(initial.refreshPlan ? { refreshPlan: initial.refreshPlan } : {}),
+                freshness: {
+                    ...before,
+                    refreshCooldownUntil: until,
+                    autoRefresh: {
+                        refreshed: false,
+                        staleFiles: before.staleFileCount,
+                        durationMs: Math.round(performance.now() - started),
+                        reason: `refresh failed, previous graph retained: ${message}; inline refresh paused until ${until}`,
+                    },
                 },
-            },
-        };
+            };
+        }
+    }
+    finally {
+        await grant?.release();
+        releasePidLock(lockPath);
     }
 }
 /**
@@ -497,6 +767,24 @@ export function discloseNexusFreshness(subject, freshness) {
             message: `Refreshed the index inline before answering (${refresh.staleFiles} stale file(s), ${refresh.durationMs}ms): ${refresh.reason}`,
         });
     }
+    const missing = freshness.missingFileCount ?? 0;
+    if (missing > 0) {
+        pushWarning({
+            code: 'W_NEXUS_INDEX_MISSING_PATHS',
+            severity: 'warn',
+            message: `${subject} answered from an index that still holds ${missing} file(s) no longer on disk ` +
+                `(e.g. ${(freshness.missingPaths ?? []).slice(0, 3).join(', ')}); results may cite deleted code. ` +
+                `Refresh: ${freshness.refreshCommand}.`,
+        });
+    }
+    if (freshness.communitiesSkipped) {
+        pushWarning({
+            code: 'W_NEXUS_COMMUNITIES_SKIPPED',
+            severity: 'warn',
+            message: `${subject} answered from an index with no communities: ${freshness.communitiesSkipped}. ` +
+                `Community-based results are missing until ${freshness.refreshCommand} runs without a budget.`,
+        });
+    }
     if (freshness.status === 'fresh')
         return;
     const symbol = freshness.symbolFileStale === true