gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/server/git-clone.js

@@ -10,6 +10,7 @@ import fs from 'fs/promises';
 import os from 'node:os';
 import { logger } from '../core/logger.js';
 import { getGlobalDir } from '../storage/repo-manager.js';
+import { branchSlug } from '../storage/branch-index.js';
 import { sanitizeRepoName, stripUrlCredentials } from '../storage/git.js';
 import { validateGitUrl } from '../core/net/url-guard.js';
 import { assertDirectoryOwnerAndPermissions, quarantineAutoSyncPartial, } from '../core/auto-sync/path-security.js';
@@ -74,14 +75,83 @@ export function extractWebRepoName(url) {
     }
     return safeName;
 }
-/** Get the clone target directory for a repo name. */
-export function getCloneDir(repoName) {
+/**
+ * Longest single path component the supported filesystems accept (ext4, APFS,
+ * NTFS all cap at 255). Compared against `.length`, which equals the byte
+ * count here because every name this guards is ASCII by construction
+ * (REPO_NAME_PATTERN and sanitizeRepoName both restrict to `[a-zA-Z0-9._-]`).
+ */
+const MAX_PATH_COMPONENT_BYTES = 255;
+/**
+ * `branchSlug` for a clone-directory name, trimmed to fit one path component.
+ *
+ * `validateBranchName` allows a ref up to 255 characters and `branchSlug`
+ * appends `-` plus 8 hash characters, so `<repo>__<slug>` can reach 267 — past
+ * the filesystem limit, and the clone would then fail to create its target
+ * directory (#3199 review).
+ *
+ * Only the READABLE half is trimmed; the 8-character hash is always kept, and
+ * it is a digest of the full ref, so two long branches that share a prefix
+ * still get different directories. The slug is not trimmed inside
+ * `branchSlug` itself because the per-branch *index* slots already use those
+ * names on disk — shortening them there would orphan existing indexes.
+ */
+const boundedBranchSegment = (repoName, branch) => {
+    const slug = branchSlug(branch);
+    if (`${repoName}__${slug}`.length <= MAX_PATH_COMPONENT_BYTES)
+        return slug;
+    const hash = slug.slice(slug.lastIndexOf('-')); // "-" + 8 hex
+    const budget = MAX_PATH_COMPONENT_BYTES - repoName.length - '__'.length - hash.length;
+    // A repo name long enough to leave no budget falls through to the caller's
+    // length check, which rejects it rather than building an unusable path.
+    return `${slug.slice(0, Math.max(0, budget))}${hash}`;
+};
+/** Get the clone target directory for a repo name, optionally pinned to a branch. */
+export function getCloneDir(repoName, branch) {
     // Re-validate at the boundary even though extractRepoName already checked —
     // callers may pass a repoName from another source (test fixtures, scripts).
     if (!repoName || repoName === '.' || repoName === '..' || !REPO_NAME_PATTERN.test(repoName)) {
         throw new Error('Invalid repository name');
     }
-    return path.join(CLONE_ROOT, repoName);
+    // A branch-pinned analyze gets its OWN working tree.
+    //
+    // Sharing one checkout per repo made `branch` unusable in practice: the tree
+    // is dirty after any analyze (generated AGENTS.md / CLAUDE.md / .claude/), so
+    // a pinned request hit `cloneOrPull`'s porcelain refusal; and a later request
+    // that OMITTED `branch` would pull whatever branch the last pin left checked
+    // out and index it as the default (#3199 review). Separate directories remove
+    // both, because the two requests no longer share a tree.
+    //
+    // `branchSlug` is the same helper the per-branch index slots use, so the two
+    // layouts agree on how a ref becomes a path segment. It emits only
+    // `[a-zA-Z0-9._-]`, so the composed name still satisfies REPO_NAME_PATTERN and
+    // round-trips through this function — which is how DELETE /api/repo re-derives
+    // the directory from the registry name.
+    const dirName = branch ? `${repoName}__${boundedBranchSegment(repoName, branch)}` : repoName;
+    if (!REPO_NAME_PATTERN.test(dirName) || dirName.length > MAX_PATH_COMPONENT_BYTES) {
+        throw new Error('Invalid repository name');
+    }
+    return path.join(CLONE_ROOT, dirName);
+}
+/**
+ * Build the `cloneOrPull` options for an `/api/analyze` request.
+ *
+ * Extracted from the route so the token/branch combination is unit-testable.
+ * Inline, the branch-only case was the one nothing asserted: every existing
+ * test still passed if `branch` were dropped whenever no token was supplied —
+ * i.e. silently cloning the default branch for every public URL, which is the
+ * exact behavior #3198 is about (#3199 review).
+ *
+ * Returns `undefined` rather than `{}` when neither is set, because that is
+ * what `cloneOrPull` treats as "no options" at its own call sites.
+ */
+export function analyzeCloneOptions(token, branch) {
+    if (!token && !branch)
+        return undefined;
+    return {
+        ...(token ? { token } : {}),
+        ...(branch ? { branch } : {}),
+    };
 }
 /**
  * Build the `git clone` argument list for a given URL and target directory.
@@ -248,11 +318,110 @@ export async function assertRemoteMatchesRequestedUrl(targetDir, requestedUrl, t
             `not the requested URL ${stripUrlCredentials(requestedUrl)}`);
     }
 }
+/**
+ * Fetch refspec that updates `origin/<branch>` from `refs/heads/<branch>`.
+ *
+ * The leading `+` is git's dest-update prefix (`+refs/heads/*:refs/remotes/origin/*`
+ * is what `git clone` writes into `.git/config`). Without it, `fetch --depth 1`
+ * refuses to move `origin/<branch>` when the shallow history cannot prove a
+ * fast-forward — so a same-branch re-index stays stuck on the old tip.
+ *
+ * The user string is interpolated inside `refs/heads/…`, never as a raw pull
+ * dest. A branch named `+develop` becomes `+refs/heads/+develop:…`, not a
+ * force-update of `develop`.
+ */
+function branchFetchRefspec(branch) {
+    return `+refs/heads/${branch}:refs/remotes/origin/${branch}`;
+}
+/** Overlays `analyze` writes into a clone; they must not block a same-ref update. */
+const GITNEXUS_GENERATED_OVERLAYS = ['./AGENTS.md', './CLAUDE.md', './.claude'];
+/**
+ * Restore only GitNexus-generated overlays so a same-ref update is not
+ * blocked by analyze dirt. Path-limited and root-anchored (`./`): tracked
+ * files are checked out from HEAD; untracked overlays (including gitignored
+ * ones — `AGENTS.md` / `.claude/` are commonly ignored) are `git clean -fdx`'d.
+ * A slash-free `AGENTS.md` would also hit `docs/AGENTS.md`. Never a
+ * whole-clone `git clean --force -d`.
+ */
+async function restoreGitNexusGeneratedOverlays(runGitImpl, cwd, gitOpts) {
+    for (const overlay of GITNEXUS_GENERATED_OVERLAYS) {
+        const listed = (await runGitImpl(['ls-files', '--', overlay], cwd, gitOpts)).trim();
+        if (!listed)
+            continue;
+        await runGitImpl(['checkout', 'HEAD', '--', overlay], cwd, gitOpts);
+    }
+    // Path-limited: untracked analyze output still blocks checkout when the
+    // incoming tree has the same path, and otherwise leaves a dirty tree to
+    // index. `-x` is required because these overlays are often gitignored.
+    // Never a whole-clone `git clean --force -d`.
+    await runGitImpl(['clean', '-fdx', '--', ...GITNEXUS_GENERATED_OVERLAYS], cwd, gitOpts);
+}
+/**
+ * True when the working tree is already at the requested pin: either HEAD is
+ * that named branch, or HEAD is detached at the same SHA as `branch` /
+ * `origin/<branch>`. A missing ref falls through to the switch path.
+ */
+async function matchRequestedRef(runGitImpl, cwd, branch, gitOpts) {
+    const abbrev = (await runGitImpl(['rev-parse', '--abbrev-ref', 'HEAD'], cwd, gitOpts)).trim();
+    if (abbrev === branch)
+        return 'branch';
+    // Detached HEAD reports `HEAD`; compare SHAs so a tag/SHA pin is not a switch.
+    if (abbrev !== 'HEAD')
+        return undefined;
+    let headSha;
+    try {
+        headSha = (await runGitImpl(['rev-parse', 'HEAD'], cwd, gitOpts)).trim();
+    }
+    catch {
+        return undefined;
+    }
+    for (const candidate of [branch, `origin/${branch}`]) {
+        try {
+            // Peel annotated tags (`v1.0` is a tag object; HEAD is the commit).
+            const requestedSha = (await runGitImpl(['rev-parse', `${candidate}^{commit}`], cwd, gitOpts)).trim();
+            if (requestedSha && requestedSha === headSha)
+                return 'sha';
+        }
+        catch {
+            // Ref missing — try origin/<branch>, then the switch path.
+        }
+    }
+    return undefined;
+}
+async function fetchAndCheckoutRequestedBranch(runGitImpl, cwd, branch, gitOpts) {
+    // Analyze clones are `--depth 1`. `merge --ff-only` cannot walk O→N when
+    // the remote moved 2+ commits (the merge-base is not in the shallow
+    // history). `checkout -B` points the local branch at the fetched tip —
+    // same as the switch path, no ancestry walk. No `--force`: leftover
+    // non-overlay dirt still refuses.
+    await runGitImpl(['fetch', '--depth', '1', 'origin', branchFetchRefspec(branch)], cwd, gitOpts);
+    await runGitImpl(['checkout', '-B', branch, `origin/${branch}`], cwd, gitOpts);
+}
 /**
  * Clone or pull a git repository.
- * If targetDir doesn't exist: git clone --depth 1
- * If targetDir exists with .git: git pull --ff-only (after verifying the
- * existing clone's remote.origin matches the requested URL).
+ *
+ * If targetDir doesn't exist: git clone --depth 1, adding `--branch <branch>`
+ * when one is requested.
+ *
+ * If targetDir exists with .git, its remote.origin is verified against the
+ * requested URL first, and then the branch decides the update:
+ *   - no `options.branch`: git pull --ff-only, which updates the current
+ *     branch in place via its configured upstream. Nothing moves, so no
+ *     dirty-tree check applies.
+ *   - a `options.branch` that is ALREADY the current named branch: restore
+ *     GitNexus overlays, then fetch via
+ *     `+refs/heads/<branch>:refs/remotes/origin/<branch>` and
+ *     `checkout -B <branch> origin/<branch>` (shallow clones cannot
+ *     `merge --ff-only` across a 2+ commit move). Never a raw
+ *     `origin <branch>` pull refspec. No porcelain refuse.
+ *   - a detached HEAD whose SHA already matches the requested ref (tag /
+ *     SHA pin): restore overlays only. Do not fetch/merge — a same-named
+ *     branch could otherwise fast-forward the pin past the tag.
+ *   - a `options.branch` that DIFFERS from the current pin: fetch that ref,
+ *     then `checkout -B <branch> origin/<branch>` — so the requested branch,
+ *     not the one already checked out, is what ends up in the working tree.
+ *     This is the switching case, and it refuses a dirty tree unless
+ *     `overwriteLocalChanges` is set.
  *
  * Security:
  *   - targetDir must resolve inside CLONE_ROOT (~/.gitnexus/repos/). The
@@ -321,39 +490,47 @@ export async function cloneOrPull(url, targetDir, onProgress, options) {
         await assertRemoteMatchesRequestedUrl(safeTarget, url, options?.timeoutMs);
         onProgress?.({ phase: 'pulling', message: 'Pulling latest changes...' });
         const runGitImpl = options?.runGitForTest ?? runGit;
-        if (options?.branch) {
+        const gitOpts = {
+            token: options?.token,
+            url,
+            timeoutMs: options?.timeoutMs,
+        };
+        // Already at the requested pin? Then there is no switch to make, so do
+        // not take the checkout path below — that would run the porcelain check
+        // against a tree ANALYZE ITSELF dirtied (it writes AGENTS.md / CLAUDE.md /
+        // .claude/ into the clone), which made a pinned RE-index impossible: the
+        // first pin succeeded and every later one failed asking for
+        // `overwrite_local_changes`, a flag this route deliberately does not pass
+        // because it would `git clean --force -d` the directory (#3199 review).
+        //
+        // "Already there" is a named-branch match OR a detached HEAD whose SHA
+        // equals `branch` / `origin/<branch>` (tag / SHA pin). A missing ref
+        // falls through to the switch path, which still refuses a dirty tree.
+        //
+        // Same-named-branch update uses the heads/ → remotes/ fetch refspec plus
+        // `checkout -B <branch> origin/<branch>`, never `pull origin <user-string>`
+        // (a leading `+` would otherwise be a force-fetch). Only
+        // `remote.origin.url` is verified above; `branch.<name>.remote` /
+        // `.merge` are not, so an implicit-upstream pull can update a different
+        // ref while the job still carries this branch (#3199 review).
+        const requestedRefMatch = options?.branch
+            ? await matchRequestedRef(runGitImpl, safeTarget, options.branch, gitOpts)
+            : undefined;
+        if (options?.branch && !requestedRefMatch) {
             if (!options.overwriteLocalChanges) {
-                const status = await runGitImpl(['status', '--porcelain'], safeTarget, {
-                    token: options?.token,
-                    url,
-                    timeoutMs: options?.timeoutMs,
-                });
+                const status = await runGitImpl(['status', '--porcelain'], safeTarget, gitOpts);
                 if (status.trim()) {
                     throw new Error(`Refusing to update ${safeTarget}: local changes detected. Set overwrite_local_changes: true to overwrite them.`);
                 }
             }
-            await runGitImpl([
-                'fetch',
-                '--depth',
-                '1',
-                'origin',
-                `refs/heads/${options.branch}:refs/remotes/origin/${options.branch}`,
-            ], safeTarget, {
-                token: options?.token,
-                url,
-                timeoutMs: options?.timeoutMs,
-            });
+            await runGitImpl(['fetch', '--depth', '1', 'origin', branchFetchRefspec(options.branch)], safeTarget, gitOpts);
             await runGitImpl([
                 'checkout',
                 ...(options.overwriteLocalChanges ? ['--force'] : []),
                 '-B',
                 options.branch,
                 `origin/${options.branch}`,
-            ], safeTarget, {
-                token: options?.token,
-                url,
-                timeoutMs: options?.timeoutMs,
-            });
+            ], safeTarget, gitOpts);
             if (options.overwriteLocalChanges) {
                 // `checkout --force` rewrites tracked files only, so untracked sources
                 // left by an operator or an earlier branch survive and then get indexed
@@ -361,19 +538,20 @@ export async function cloneOrPull(url, targetDir, onProgress, options) {
                 // ignored paths must survive, and `-e /.gitnexus` is belt-and-braces
                 // because `.git/info/exclude` is skipped on a read-only storage mount
                 // and a freshly cloned repo may not have been analyzed yet at all.
-                await runGitImpl(['clean', '--force', '-d', '-e', '/.gitnexus'], safeTarget, {
-                    token: options?.token,
-                    url,
-                    timeoutMs: options?.timeoutMs,
-                });
+                await runGitImpl(['clean', '--force', '-d', '-e', '/.gitnexus'], safeTarget, gitOpts);
             }
         }
+        else if (options?.branch && requestedRefMatch === 'branch') {
+            await restoreGitNexusGeneratedOverlays(runGitImpl, safeTarget, gitOpts);
+            await fetchAndCheckoutRequestedBranch(runGitImpl, safeTarget, options.branch, gitOpts);
+        }
+        else if (options?.branch && requestedRefMatch === 'sha') {
+            // Tag / SHA pin: already at the requested commit. Fetching
+            // `refs/heads/<name>` would follow a same-named branch past the pin.
+            await restoreGitNexusGeneratedOverlays(runGitImpl, safeTarget, gitOpts);
+        }
         else {
-            await runGitImpl(['pull', '--ff-only'], safeTarget, {
-                token: options?.token,
-                url,
-                timeoutMs: options?.timeoutMs,
-            });
+            await runGitImpl(['pull', '--ff-only'], safeTarget, gitOpts);
         }
     }
     else {

package/dist/server/repo-projection.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Response projections for the `serve` repo routes.
+ *
+ * Extracted from the route bodies so the field list is assertable. Inline, the
+ * projections were only reachable by booting a server and indexing a real
+ * repository, which is how `branch` came to sit on `RegistryEntry` unexposed
+ * over HTTP while `gitnexus list` printed it, with no test to notice (#3226).
+ *
+ * These are pure: the caller resolves the registry entry, the on-disk metadata
+ * and the staleness check, and passes the results in.
+ */
+import type { StalenessInfo } from '../core/git-staleness.js';
+import type { RegistryEntry } from '../storage/repo-manager.js';
+import type { RepoMeta } from '../storage/repo-meta.js';
+/**
+ * Staleness in the shape MCP `list_repos` already returns
+ * (`mcp/local/local-backend.ts`): the key is present only when the index is
+ * actually behind, so "fresh" stays the absence of a field rather than a second
+ * thing for a client to interpret. Deliberately identical across the two
+ * surfaces — the same fact should not have two shapes.
+ *
+ * `checkStalenessAsync` self-catches and reports 0 commits behind when the
+ * commit cannot be resolved, so an unanswerable check degrades to "not stale"
+ * rather than failing the request that carries it.
+ *
+ * That makes the field meaningful mainly for `path`-registered repositories,
+ * where an operator commits into the working tree the index was built from.
+ * A `url` repository is cloned `--depth 1` and is re-analyzed by the same run
+ * that pulls it, so its recorded commit is HEAD; and were the two ever to
+ * diverge, `git rev-list <old>..HEAD` cannot walk a shallow history and fails
+ * closed to "not stale". Reporting fresh there is not a claim that the remote
+ * has not moved — this measures the index against the local working tree, the
+ * same thing `gitnexus status` and MCP `list_repos` measure.
+ */
+export declare const stalenessField: (info: StalenessInfo) => {
+    staleness?: {
+        commitsBehind: number;
+        hint?: string;
+    };
+};
+/** One entry of `GET /api/repos`. */
+export declare const projectRepoListEntry: (entry: RegistryEntry, staleness: StalenessInfo) => {
+    staleness?: {
+        commitsBehind: number;
+        hint?: string;
+    };
+    name: string;
+    path: string;
+    repoPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats: {
+        files?: number;
+        nodes?: number;
+        edges?: number;
+        communities?: number;
+        processes?: number;
+        embeddings?: number;
+    };
+    branch: string;
+    branches: import("../storage/branch-index.js").BranchSummary[];
+};
+/**
+ * `GET /api/repo`. `meta ?? entry` throughout, for the reason `indexedAt`
+ * already did it: the on-disk metadata is the fresher record when the two
+ * disagree, and the entry is the fallback for a repo whose meta cannot be read.
+ */
+export declare const projectRepoDetail: (entry: RegistryEntry, meta: RepoMeta | null | undefined, staleness: StalenessInfo) => {
+    staleness?: {
+        commitsBehind: number;
+        hint?: string;
+    };
+    name: string;
+    repoPath: string;
+    indexedAt: string;
+    stats: {
+        files?: number;
+        nodes?: number;
+        edges?: number;
+        communities?: number;
+        processes?: number;
+        embeddings?: number;
+    };
+    lastCommit: string;
+    branch: string;
+};
+/** The commit a `/api/repo` staleness check should be measured against. */
+export declare const resolveLastCommit: (entry: RegistryEntry, meta: RepoMeta | null | undefined) => string;

package/dist/server/repo-projection.js

@@ -0,0 +1,53 @@
+/**
+ * Staleness in the shape MCP `list_repos` already returns
+ * (`mcp/local/local-backend.ts`): the key is present only when the index is
+ * actually behind, so "fresh" stays the absence of a field rather than a second
+ * thing for a client to interpret. Deliberately identical across the two
+ * surfaces — the same fact should not have two shapes.
+ *
+ * `checkStalenessAsync` self-catches and reports 0 commits behind when the
+ * commit cannot be resolved, so an unanswerable check degrades to "not stale"
+ * rather than failing the request that carries it.
+ *
+ * That makes the field meaningful mainly for `path`-registered repositories,
+ * where an operator commits into the working tree the index was built from.
+ * A `url` repository is cloned `--depth 1` and is re-analyzed by the same run
+ * that pulls it, so its recorded commit is HEAD; and were the two ever to
+ * diverge, `git rev-list <old>..HEAD` cannot walk a shallow history and fails
+ * closed to "not stale". Reporting fresh there is not a claim that the remote
+ * has not moved — this measures the index against the local working tree, the
+ * same thing `gitnexus status` and MCP `list_repos` measure.
+ */
+export const stalenessField = (info) => info.isStale ? { staleness: { commitsBehind: info.commitsBehind, hint: info.hint } } : {};
+/** One entry of `GET /api/repos`. */
+export const projectRepoListEntry = (entry, staleness) => ({
+    name: entry.name,
+    path: entry.path,
+    repoPath: entry.path,
+    indexedAt: entry.indexedAt,
+    lastCommit: entry.lastCommit,
+    stats: entry.stats,
+    // The registry has carried these since #2106; #3199 made them load-bearing
+    // over HTTP, because a branch-pinned analyze now gets its own entry and the
+    // only other way to tell two entries apart is to parse the clone-directory
+    // slug — a layout detail, not an API contract.
+    branch: entry.branch,
+    branches: entry.branches,
+    ...stalenessField(staleness),
+});
+/**
+ * `GET /api/repo`. `meta ?? entry` throughout, for the reason `indexedAt`
+ * already did it: the on-disk metadata is the fresher record when the two
+ * disagree, and the entry is the fallback for a repo whose meta cannot be read.
+ */
+export const projectRepoDetail = (entry, meta, staleness) => ({
+    name: entry.name,
+    repoPath: entry.path,
+    indexedAt: meta?.indexedAt ?? entry.indexedAt,
+    stats: meta?.stats ?? entry.stats ?? {},
+    lastCommit: meta?.lastCommit ?? entry.lastCommit,
+    branch: meta?.branch ?? entry.branch,
+    ...stalenessField(staleness),
+});
+/** The commit a `/api/repo` staleness check should be measured against. */
+export const resolveLastCommit = (entry, meta) => meta?.lastCommit ?? entry.lastCommit;

package/dist/storage/file-lock.js

@@ -3,7 +3,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { isProcessAlive, readProcessStartTime } from '../utils/process-identity.js';
+import { isProcessAlive, readProcessStartTimeCached } from '../utils/process-identity.js';
 const HOSTNAME = os.hostname();
 export class FileLockBusyError extends Error {
     lockPath;
@@ -22,7 +22,9 @@ export async function acquireFileLock(lockPath, options = {}) {
     const owner = {
         pid,
         ownerId: crypto.randomUUID(),
-        processStartTime: options.processStartTime ?? (options.readProcessStartTime ?? readProcessStartTime)(pid) ?? '',
+        processStartTime: options.processStartTime ??
+            (options.readProcessStartTime ?? readProcessStartTimeCached)(pid) ??
+            '',
         hostname: options.hostname ?? HOSTNAME,
     };
     if (!owner.processStartTime) {
@@ -40,7 +42,7 @@ export async function acquireFileLock(lockPath, options = {}) {
             catch (error) {
                 if (!(await isLockConflict(error, resolvedPath)))
                     throw error;
-                if (await reclaimStaleLock(resolvedPath, owner, options.isProcessAlive ?? isProcessAlive, options.readProcessStartTime ?? readProcessStartTime)) {
+                if (await reclaimStaleLock(resolvedPath, owner, options.isProcessAlive ?? isProcessAlive, options.readProcessStartTime ?? readProcessStartTimeCached)) {
                     continue;
                 }
                 if (attempt >= retries)

package/dist/storage/parse-cache.js

@@ -730,7 +730,38 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // v93: Zig call captures inside a comptime-false branch carry
 // `@reference.static-gated` (feat/zig-static-gated-edges); the site gains
 // `staticGated` and the CALLS edge a BOOLEAN column.
-const SCHEMA_BUMP = 93;
+// v94: Objective-C now elides bare, file-scope macro markers before parsing.
+// A warm v93 cache can retain error-recovered trees and provider facts that
+// omit Objective-C declarations following markers such as RCT_EXTERN_C_END.
+// v95: Objective-C header classification no longer treats framework `#import`
+// alone as Objective-C syntax. A warm v94 cache can replay Objective-C worker
+// output for a C++ header during `--force`, even though the current classifier
+// routes that same header through the C++ provider.
+// v96: Objective-C macro-marker preprocessing recognizes all C preprocessing
+// whitespace before a directive or bare marker. A warm v95 cache can retain
+// error-recovered facts for sources that begin those lines with form feed or
+// vertical tab.
+// v97: Objective-C macro-marker preprocessing recognizes comment-prefixed
+// directives and rejects invalid numeric marker prefixes. A warm v96 cache can
+// replay error-recovered facts from the previous normalization behavior.
+// v98 (#3219): `ZIG_SCOPE_QUERY` gained three `@reference.value-ref` rules —
+// bare call argument, qualified call argument (with `@reference.receiver`), and
+// const-binding initialiser — so a Zig callable named in VALUE position now
+// produces a `value-ref` entry in `ParsedFile.referenceSites` where it produced
+// none before. These captures are PARSE-TIME facts, so a warm pre-v98 cache
+// replays unchanged `.zig` files with zero value-ref sites, `--force` included
+// (shards are content-addressed): `emitPropertyDispatchCalls` then emits no
+// USES edge, `callableValueReferenceBoundaries` measures a real zero, and
+// `impact` on a registered accessor republishes `epistemic: "exact"` — the exact
+// #3399 defect this change exists to close, silently un-fixed.
+//
+// 94-97 went to #3179 (Objective-C), which has since merged; 98 is the next
+// value above it. Re-checked against origin/main and every open PR touching
+// this file at merge time, which is the rule the paragraphs above were written
+// by PRs that each checked only once: main is at 97, and the remaining open
+// claims (#3190 at 94, #2840 at 71, #1616 at 2) all sit below it and must
+// re-bump themselves.
+const SCHEMA_BUMP = 98;
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

package/dist/storage/parsedfile-store.js

@@ -149,6 +149,7 @@ export const getParsedFileStoreDir = (storagePath) => path.join(storagePath, STO
 /** Remove any prior run's shards so a fresh parse starts clean. Idempotent. */
 export const clearParsedFileStore = async (storagePath) => {
     await fs.rm(getParsedFileStoreDir(storagePath), { recursive: true, force: true });
+    forgetShardListings();
 };
 const isV8ShardName = (name) => name.endsWith('.v8') && !name.includes('.v8.');
 const shardPath = (storagePath, shardId) => path.join(getParsedFileStoreDir(storagePath), `${shardId}.v8`);
@@ -200,11 +201,46 @@ const listV8Shards = async (dir) => {
         return [];
     }
 };
+/**
+ * Per-run memo of each shard's authenticated path listing, so the SECOND and
+ * later passes over the store can decide "this shard holds nothing I want"
+ * without reopening it.
+ *
+ * Scope resolution calls `loadParsedFilesForPaths` once per language, and each
+ * call walks every shard in the store. The skip decision needs the envelope's
+ * path listing, and that listing is only trustworthy once the payload digest
+ * has been checked — so today a pass that wants 50 Python files still reads and
+ * SHA-256s all ~300MB of a TypeScript-dominated store to prove it can skip it.
+ * Measured on a 2234-file repo: a pass wanting a single file costs 335ms, and
+ * the three language passes together spend 4426ms in here. The cost scales with
+ * LANGUAGE COUNT, so a polyglot repo pays it worst.
+ *
+ * Keyed by size+mtime as well as name. Shard names are content-addressed
+ * (parse-chunk hash + worker id), so a name collision across different content
+ * should be impossible — but that invariant lives in the parse-cache keying,
+ * not here, and one `stat` per shard is a few ms against the hundreds this
+ * saves. The memo holds one store directory at a time: a different `dir` (a new
+ * repo in a long-lived MCP process, or a wiped store) drops the previous set
+ * rather than accumulating.
+ */
+let shardListingMemo;
+const shardIdentity = (file, size, mtimeMs) => `${file}\0${size}\0${mtimeMs}`;
+const memoFor = (dir) => {
+    if (shardListingMemo?.dir !== dir)
+        shardListingMemo = { dir, byIdentity: new Map() };
+    return shardListingMemo.byIdentity;
+};
+/** Drop the memo when the store it describes is removed. */
+const forgetShardListings = () => {
+    shardListingMemo = undefined;
+};
 export const loadParsedFilesForPaths = async (storagePath, wantPaths) => {
     const out = new Map();
     if (wantPaths.size === 0)
         return out;
-    const shardPaths = await listV8Shards(getParsedFileStoreDir(storagePath));
+    const storeDir = getParsedFileStoreDir(storagePath);
+    const shardPaths = await listV8Shards(storeDir);
+    const listings = memoFor(storeDir);
     const pool = new Map();
     let droppedSites = 0;
     let filesWithDroppedSites = 0;
@@ -227,11 +263,27 @@ export const loadParsedFilesForPaths = async (storagePath, wantPaths) => {
         }
     };
     for (const shardFull of shardPaths) {
+        // Re-stat rather than trusting the name alone, then reuse this run's
+        // authenticated listing to skip without opening the file. A shard with no
+        // memoized listing — first pass, or an envelope whose listing did not
+        // validate — falls through to the full read, so this only ever removes
+        // work that a later pass had already proved unnecessary.
+        const st = await fs.stat(shardFull).catch(() => undefined);
+        const identity = st ? shardIdentity(shardFull, st.size, st.mtimeMs) : undefined;
+        const memoized = identity === undefined ? undefined : listings.get(identity);
+        if (memoized !== undefined && !memoized.some((p) => wantPaths.has(p))) {
+            bytesSinceGc += st?.size ?? 0;
+            await maybeYieldAndGc(bytesSinceGc >= parsedFileLoadGc.byteBudget);
+            continue;
+        }
         const loaded = await tryLoadV8Cache(shardFull, pool, wantPaths);
         if (loaded === undefined) {
             await maybeYieldAndGc(false);
             continue;
         }
+        if (identity !== undefined && loaded.paths !== undefined) {
+            listings.set(identity, loaded.paths);
+        }
         if (loaded.kind === 'skip') {
             bytesSinceGc += loaded.bytes;
             await maybeYieldAndGc(bytesSinceGc >= parsedFileLoadGc.byteBudget);

package/dist/storage/v8-sidecar.d.ts

@@ -16,14 +16,25 @@ export declare const encodeCachePathListing: (paths: readonly string[]) => Buffe
  * that does not match the remaining lines.
  */
 export declare const parseCachePathListing: (raw: Buffer) => string[] | null;
+/**
+ * `paths` is the envelope's digest-authenticated path listing, present only
+ * when it parsed and its entry count matched the recorded `pathCount` — i.e.
+ * exactly when the skip decision below is willing to trust it. A caller that
+ * loads the same immutable shard more than once per run can memoize it and
+ * make its own skip decision without reopening the file (see
+ * `parsedfile-store.ts`). Absent means "this envelope has no listing worth
+ * trusting", which is fail-closed: load, never skip.
+ */
 export type V8CacheHit = {
     kind: 'hit';
     value: unknown;
     bytes: number;
+    paths?: readonly string[];
 };
 export type V8CacheSkip = {
     kind: 'skip';
     bytes: number;
+    paths: readonly string[];
 };
 export type V8CacheLoad = V8CacheHit | V8CacheSkip;
 export type V8CacheInspection = {