gitnexus 1.6.12-rc.30 → 1.6.12-rc.32

package/dist/cli/embeddings-sync.js

@@ -7,7 +7,8 @@ import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js'
 import { closeLbug, executeQuery, executeWithReusedStatement, fetchExistingEmbeddingHashes, initLbug, } from '../core/lbug/lbug-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
 import { resolveEmbeddingIdentity } from '../core/embeddings/embedding-identity.js';
-import { checkpointKind, decideEmbeddingResume, mintInterruptedCheckpoint, mintPartialCheckpoint, mintUnverifiedCountCheckpoint, } from '../core/embedding-checkpoint.js';
+import { decideEmbeddingResume, mintInterruptedCheckpoint, mintPartialCheckpoint, mintUnverifiedCountCheckpoint, } from '../core/embedding-checkpoint.js';
+import { EMBEDDING_DIMS, embeddingDimsMismatch } from '../core/lbug/schema.js';
 import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } from '../core/embedding-count.js';
 /** Add missing embeddings directly to a healthy index, checkpointing periodically. */
 export const embeddingsSyncCommand = async (inputPath) => {
@@ -45,10 +46,16 @@ export const embeddingsSyncCommand = async (inputPath) => {
             const identityDiffers = checkpoint.provider !== identity.provider ||
                 checkpoint.model !== identity.model ||
                 checkpoint.dimensions !== identity.dimensions;
-            // `abandon` on a non-interrupted foreign identity drops the pending set
-            // only. Existing rows stay; sync would then embed the holes under the new
-            // identity and mix vector spaces. Fail closed — rebuild via analyze.
-            if (identityDiffers && checkpointKind(checkpoint) !== 'unverified-count') {
+            // `abandon` on a foreign identity drops the pending set only. Existing
+            // rows stay; sync would then embed the holes under the new identity and
+            // mix vector spaces. Fail closed — rebuild via analyze.
+            //
+            // Every kind is gated, `unverified-count` included. Exempting it looked
+            // safe because that kind only records "the count could not be read", but
+            // `decideEmbeddingResume` returns `abandon` for it BEFORE comparing
+            // identity, so the exemption was the only thing standing between a
+            // foreign identity and a silently mixed table.
+            if (identityDiffers) {
                 throw new Error(`Cannot sync embeddings: the index checkpoint was written by ${checkpoint.model} ` +
                     `(${checkpoint.provider}) at ${checkpoint.dimensions} dimensions, but this run ` +
                     `resolves ${identity.model} (${identity.provider}) at ${identity.dimensions}. ` +
@@ -60,19 +67,34 @@ export const embeddingsSyncCommand = async (inputPath) => {
                 resumedFrom = decision.resumedFrom;
             }
         }
+        // The vector column is FLOAT[N] fixed when the index was built, and the
+        // pipeline deletes each batch's stale rows immediately before inserting the
+        // replacements — so a width change here deletes rows it cannot re-insert.
+        // `analyze` forces a full rebuild on the same mismatch; only a rebuild can
+        // retype the column, so this writer refuses instead. An absent recorded
+        // width is not a mismatch (see `embeddingDimsMismatch`).
+        if (embeddingDimsMismatch(meta.embeddingDims, EMBEDDING_DIMS)) {
+            throw new Error(`Cannot sync embeddings: this index stores FLOAT[${meta.embeddingDims}] vectors, ` +
+                `but this run embeds at ${EMBEDDING_DIMS} dimensions. ` +
+                'Run `gitnexus analyze --embeddings --force` to rebuild the column at the new width.');
+        }
         await initLbug(lbugPath);
         try {
             const existing = await fetchExistingEmbeddingHashes(executeQuery);
             let lastPercent = -1;
             const countEmbeddings = async () => persistedEmbeddingCountOrUndefined(await measurePersistedEmbeddingCount(executeQuery));
-            const saveCheckpoint = async (checkpoint, pendingNodeIds, embeddings) => {
+            // One write path for every meta update this command makes. The re-read
+            // happens immediately before each save so a concurrent writer's fields
+            // survive. #2790 traced two production drifts to hand-copied writers of
+            // these exact fields, so this file keeps one copy instead of three.
+            const persistMeta = async (patch) => {
                 const latest = (await loadMeta(metaDir)) ?? meta;
-                await saveMeta(metaDir, {
-                    ...latest,
-                    ...(embeddings === undefined ? {} : { stats: { ...latest.stats, embeddings } }),
-                    embeddingCheckpoint: mintInterruptedCheckpoint(identity, checkpoint, pendingNodeIds),
-                });
+                await saveMeta(metaDir, { ...latest, ...patch(latest) });
             };
+            const saveCheckpoint = async (checkpoint, pendingNodeIds, embeddings) => persistMeta((latest) => ({
+                ...(embeddings === undefined ? {} : { stats: { ...latest.stats, embeddings } }),
+                embeddingCheckpoint: mintInterruptedCheckpoint(identity, checkpoint, pendingNodeIds),
+            }));
             cliInfo(`Embedding ${repoPath}`);
             cliInfo(`Checkpointed nodes already present: ${existing?.size ?? 0}`);
             const result = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
@@ -91,13 +113,11 @@ export const embeddingsSyncCommand = async (inputPath) => {
                 },
             });
             const embeddings = await countEmbeddings();
-            const latest = (await loadMeta(metaDir)) ?? meta;
             if (embeddings === undefined) {
                 // Keep last-known stats.embeddings. An interrupted window marker would
                 // fail the identity gate on the next run even though this run finished;
                 // unverified-count is the recovery kind that forces a recount (#2790).
-                await saveMeta(metaDir, {
-                    ...latest,
+                await persistMeta(() => ({
                     embeddingCheckpoint: result.failedNodeIds.length
                         ? mintPartialCheckpoint(identity, result, resumedFrom)
                         : mintUnverifiedCountCheckpoint(identity, {
@@ -105,16 +125,15 @@ export const embeddingsSyncCommand = async (inputPath) => {
                             totalNodes: result.nodesProcessed,
                             chunksProcessed: result.chunksProcessed,
                         }),
-                });
+                }));
                 throw new Error('Could not verify persisted embedding count.');
             }
-            await saveMeta(metaDir, {
-                ...latest,
+            await persistMeta((latest) => ({
                 stats: { ...latest.stats, embeddings },
                 embeddingCheckpoint: result.failedNodeIds.length
                     ? mintPartialCheckpoint(identity, result, resumedFrom)
                     : undefined,
-            });
+            }));
             cliInfo(`Embeddings ready: ${embeddings}`);
         }
         finally {

package/dist/cli/group-status-format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rendering for `gitnexus group status` rows, kept out of the Commander action
+ * so it can be tested. Inline, the cell was only reachable by booting a backend
+ * against a real group, which is how `STALE (-1 commits behind)` went unnoticed
+ * (#3256).
+ */
+/** The fields of a `groupStatus` repo row the index column reads. */
+export interface GroupRepoIndexRow {
+    indexStale: boolean;
+    commitsBehind?: number;
+}
+/**
+ * The index column of a `group status` row. The output is unchanged except
+ * for one case: a count that is not a real count renders as `?`.
+ *
+ * `group/service.ts` has always reported a repo with no recorded commit as
+ * `{ indexStale: true, commitsBehind: -1 }`. The previous `?? '?'` fallback
+ * never caught that, because `??` only falls back on `null` / `undefined`.
+ */
+export declare const formatIndexStatusCell: (row: GroupRepoIndexRow) => string;

package/dist/cli/group-status-format.js

@@ -0,0 +1,21 @@
+/**
+ * Rendering for `gitnexus group status` rows, kept out of the Commander action
+ * so it can be tested. Inline, the cell was only reachable by booting a backend
+ * against a real group, which is how `STALE (-1 commits behind)` went unnoticed
+ * (#3256).
+ */
+/**
+ * The index column of a `group status` row. The output is unchanged except
+ * for one case: a count that is not a real count renders as `?`.
+ *
+ * `group/service.ts` has always reported a repo with no recorded commit as
+ * `{ indexStale: true, commitsBehind: -1 }`. The previous `?? '?'` fallback
+ * never caught that, because `??` only falls back on `null` / `undefined`.
+ */
+export const formatIndexStatusCell = (row) => {
+    if (!row.indexStale)
+        return 'OK        ';
+    const n = row.commitsBehind;
+    const count = typeof n === 'number' && n >= 0 ? String(n) : '?';
+    return `STALE     (${count} commits behind)`;
+};

package/dist/cli/group.js

@@ -1,6 +1,7 @@
 // gitnexus/src/cli/group.ts
 import { createRequire } from 'node:module';
 import { logger } from '../core/logger.js';
+import { formatIndexStatusCell } from './group-status-format.js';
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml');
 export function registerGroupCommands(program) {
@@ -120,9 +121,7 @@ export function registerGroupCommands(program) {
                     console.log(`  ${repoPath.padEnd(25)} MISSING   (no entry in the registry)`);
                     continue;
                 }
-                const idx = row.indexStale
-                    ? `STALE     (${row.commitsBehind ?? '?'} commits behind)`
-                    : 'OK        ';
+                const idx = formatIndexStatusCell(row);
                 const ctr = row.contractsStale ? ' CONTRACTS_STALE' : '';
                 console.log(`  ${repoPath.padEnd(25)} ${idx}${ctr}`);
             }

package/dist/core/embeddings/http-client.js

@@ -11,6 +11,7 @@
  * via `AbortSignal.timeout` on the underlying fetch.
  */
 import { chunk } from '../../lib/utils.js';
+import { parseTruthyEnv } from '../ingestion/utils/env.js';
 import { CircuitOpenError, ResilientFetchExhaustedError, isTerminalNetworkError, resilientFetch, } from '../../_shared/index.js';
 const DEFAULT_HTTP_TIMEOUT_MS = 180_000;
 const MAX_HTTP_TIMEOUT_MS = 300_000;
@@ -157,7 +158,12 @@ const readConfig = () => {
         retryCapMs: parsePositiveIntegerEnv('GITNEXUS_EMBEDDING_RETRY_CAP_MS', HTTP_RETRY_CAP_MS, 300_000),
         minIntervalMs: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_MIN_INTERVAL_MS', 0, 300_000),
         timeoutMs: parsePositiveIntegerEnv(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT_MS, MAX_HTTP_TIMEOUT_MS),
-        retryTimeouts: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_RETRY_TIMEOUTS', 0, 1) === 1,
+        // A boolean toggle, so it takes the repo's truthy convention (`1`/`true`/
+        // `yes`) and falls back to the documented default on anything else. The
+        // integer parser this used throws on a non-digit, which turned the
+        // conventional `=true` into a hard failure of every embedding call rather
+        // than either enabling the flag or leaving it off.
+        retryTimeouts: parseTruthyEnv(process.env.GITNEXUS_EMBEDDING_RETRY_TIMEOUTS),
         requestDimensions,
     };
 };

package/dist/core/git-staleness.d.ts

@@ -3,11 +3,8 @@
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
 import { type CwdMatch } from '../storage/repo-manager.js';
-export interface StalenessInfo {
-    isStale: boolean;
-    commitsBehind: number;
-    hint?: string;
-}
+import type { StalenessInfo } from './staleness-status.js';
+export type { StalenessInfo, StalenessStatus } from './staleness-status.js';
 /**
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */

package/dist/core/git-staleness.js

@@ -14,10 +14,64 @@ const execFileAsync = promisify(execFile);
  * degrades to "not stale" quickly rather than holding a request open.
  */
 const STALENESS_TIMEOUT_MS = 5_000;
+const behindHint = (n) => `⚠️ Index is ${n} commit${n > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`;
+// Says only what a failed count plus a resolved HEAD establish: the index is not
+// at HEAD and the gap is uncountable. Reaching here does NOT prove the indexed
+// commit left history — that is the usual cause (a pruned `fetch --depth 1`),
+// but any other `rev-list` failure lands here too, so the cause is hedged.
+const DIVERGED_HINT = "⚠️ Index is not at HEAD and the commit gap could not be counted — the recorded commit may no longer be in this clone's history. Run analyze tool to update.";
+const unknown = () => ({ isStale: false, commitsBehind: 0, status: 'unknown' });
+const fromCount = (commitsBehind) => commitsBehind > 0
+    ? { isStale: true, commitsBehind, hint: behindHint(commitsBehind), status: 'behind' }
+    : { isStale: false, commitsBehind: 0, status: 'current' };
+/**
+ * `rev-list` could not answer. Asking for HEAD alone needs no history walk and
+ * still separates all three answers: HEAD unreadable is `unknown`, HEAD past the
+ * indexed commit is `diverged`, and HEAD still *at* it is `current` — the ref
+ * prints the indexed SHA, so the index is at HEAD however `rev-list` failed. The
+ * historical fail-open values are kept either way; only `status` differs.
+ */
+const fromHead = (head, lastCommit) => {
+    if (!head)
+        return unknown();
+    if (head === lastCommit)
+        return { isStale: false, commitsBehind: 0, status: 'current' };
+    return { isStale: false, commitsBehind: 0, hint: DIVERGED_HINT, status: 'diverged' };
+};
+const readHeadSync = (repoPath) => {
+    try {
+        return (execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        }).trim() || null);
+    }
+    catch {
+        return null;
+    }
+};
+const readHeadAsync = async (repoPath) => {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            windowsHide: true,
+            timeout: STALENESS_TIMEOUT_MS,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
 export function checkStaleness(repoPath, lastCommit) {
+    // No recorded commit is not "at HEAD": there is nothing to measure against.
+    if (!lastCommit)
+        return unknown();
     try {
         const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
             cwd: repoPath,
@@ -25,18 +79,10 @@ export function checkStaleness(repoPath, lastCommit) {
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
         }).trim();
-        const commitsBehind = parseInt(result, 10) || 0;
-        if (commitsBehind > 0) {
-            return {
-                isStale: true,
-                commitsBehind,
-                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
-            };
-        }
-        return { isStale: false, commitsBehind: 0 };
+        return fromCount(parseInt(result, 10) || 0);
     }
     catch {
-        return { isStale: false, commitsBehind: 0 };
+        return fromHead(readHeadSync(repoPath), lastCommit);
     }
 }
 /**
@@ -45,6 +91,8 @@ export function checkStaleness(repoPath, lastCommit) {
  * repos in parallel (issue #1363: 200 repos × sync spawn ≈ 50 s).
  */
 export async function checkStalenessAsync(repoPath, lastCommit) {
+    if (!lastCommit)
+        return unknown();
     try {
         // Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
         // unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
@@ -57,22 +105,18 @@ export async function checkStalenessAsync(repoPath, lastCommit) {
             // A working tree on a disconnected network mount or behind a stuck lock
             // does exactly that, and `/api/repos` fans this out once per registered
             // repo, so one unreachable mount could hold the whole listing open
-            // (#3232 review). The timeout kills the child and rejects, which routes
-            // a hang into the same fail-closed "not stale" answer as a bad SHA.
+            // (#3232 review). The timeout kills the child and rejects, and the catch
+            // below reports it as `unknown` — still the fail-closed `isStale: false`.
             timeout: STALENESS_TIMEOUT_MS,
         });
-        const commitsBehind = parseInt(stdout.trim(), 10) || 0;
-        if (commitsBehind > 0) {
-            return {
-                isStale: true,
-                commitsBehind,
-                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
-            };
-        }
-        return { isStale: false, commitsBehind: 0 };
+        return fromCount(parseInt(stdout.trim(), 10) || 0);
     }
-    catch {
-        return { isStale: false, commitsBehind: 0 };
+    catch (err) {
+        // A rev-list that timed out means the working tree is not answering. Asking
+        // it again for HEAD would only double the bound #3232 put on a hung mount.
+        if (err.killed)
+            return unknown();
+        return fromHead(await readHeadAsync(repoPath), lastCommit);
     }
 }
 /**

package/dist/core/group/service.js

@@ -5,6 +5,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
+import { stalenessStatus } from '../staleness-status.js';
 import { canonicalizePath, loadMeta, readRegistryStrict, registryPathEquals, } from '../../storage/repo-manager.js';
 import { crossRepoCompleteness } from './completeness.js';
 import { recordedMatchStages, recordedRepoList } from './completeness.js';
@@ -635,7 +636,7 @@ export class GroupService {
                 const meta = (await loadMeta(repoObj.storagePath)) ?? {};
                 const staleness = meta.lastCommit
                     ? checkStaleness(repoObj.repoPath, meta.lastCommit)
-                    : { isStale: true, commitsBehind: -1 };
+                    : { isStale: true, commitsBehind: -1, status: 'unknown' };
                 const snapshot = registry?.repoSnapshots?.[repoPath];
                 const contractsStale = snapshot && meta.indexedAt ? snapshot.indexedAt !== meta.indexedAt : !snapshot;
                 repoStatuses[repoPath] = {
@@ -644,6 +645,7 @@ export class GroupService {
                     missing: false,
                     unresolvable: false,
                     commitsBehind: staleness.commitsBehind,
+                    status: stalenessStatus(staleness),
                 };
             }
             catch (err) {

package/dist/core/staleness-status.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The shape of a staleness answer, and the one wire payload every surface
+ * emits for it (#3256). Pure: no git, no I/O.
+ *
+ * Kept apart from `git-staleness.ts` on purpose. Tests across the suite stub
+ * that module with a fixed `vi.mock` factory so nothing shells out to git; a
+ * pure helper exported from it would come back `undefined` under every such
+ * stub. Here it is imported for real wherever the git probes are mocked.
+ */
+/**
+ * What a staleness check was able to establish.
+ *
+ * `isStale` / `commitsBehind` alone cannot say "could not tell": every git
+ * failure collapses into `{ isStale: false, commitsBehind: 0 }`. That is
+ * deliberate — pinned by the fail-open tests, because the hot read tools must
+ * never fail or nag on an index they cannot measure — but it also made a
+ * provably stale index indistinguishable from a fresh one. `status` is the
+ * additive channel that separates them for a caller that wants to act on it:
+ *
+ * - `current`  — the index is at HEAD: `rev-list` answered 0, or it could not
+ *   answer but HEAD alone resolved to the indexed commit.
+ * - `behind`   — `rev-list` answered N > 0; `commitsBehind` is N.
+ * - `diverged` — `rev-list` could not answer, but HEAD resolved and is not the
+ *   indexed commit. The index is provably not at HEAD; only the count is
+ *   unknown. A branch-pinned `serve` clone reaches this once git prunes the
+ *   commit a failed re-index left behind — the pinned update is a
+ *   `fetch --depth 1`, which orphans it — and a rewritten history reaches it
+ *   directly. It is the rule the Claude hook already applies:
+ *   HEAD !== lastCommit.
+ * - `unknown`  — HEAD could not be resolved at all: not a git repository, git
+ *   timed out, or no commit was recorded.
+ *
+ * `isStale` and `commitsBehind` keep their historical values in every case, so
+ * no existing consumer changes behaviour unless it reads `status`.
+ */
+export type StalenessStatus = 'current' | 'behind' | 'diverged' | 'unknown';
+export interface StalenessInfo {
+    isStale: boolean;
+    commitsBehind: number;
+    hint?: string;
+    /**
+     * Always set by `checkStaleness` and `checkStalenessAsync`. Optional on the
+     * type so a hand-built info (tests, legacy literals) still compiles; read it
+     * through {@link stalenessStatus}, which derives it from `isStale` when absent.
+     */
+    status?: StalenessStatus;
+}
+/** `info.status`, or the answer `isStale` implies for an info built without one. */
+export declare const stalenessStatus: (info: StalenessInfo) => StalenessStatus;
+/**
+ * The wire shape for staleness on every surface: MCP `list_repos`, the hot read
+ * tools, and the `serve` repo routes. One builder so one fact has one shape
+ * (#3232 review: "same sentinel as MCP").
+ *
+ * Absent for `current`, as before. `commitsBehind` is present only when git
+ * actually counted it, so `diverged` carries `status` and `hint` but no number —
+ * inventing one would be the silent wrong answer this exists to remove.
+ */
+export interface StalenessPayload {
+    status: Exclude<StalenessStatus, 'current'>;
+    commitsBehind?: number;
+    hint?: string;
+}
+/**
+ * Project a check into {@link StalenessPayload}, or `undefined` when there is
+ * nothing to report.
+ *
+ * `unknown` is emitted only when `includeUnknown` is set. A listing a monitor
+ * reads wants it; the hot read tools do not, because a `--skip-git` folder has
+ * no history to measure and would otherwise repeat that on every response.
+ */
+export declare const stalenessPayload: (info: StalenessInfo | undefined, opts?: {
+    includeUnknown?: boolean;
+}) => StalenessPayload | undefined;

package/dist/core/staleness-status.js

@@ -0,0 +1,32 @@
+/**
+ * The shape of a staleness answer, and the one wire payload every surface
+ * emits for it (#3256). Pure: no git, no I/O.
+ *
+ * Kept apart from `git-staleness.ts` on purpose. Tests across the suite stub
+ * that module with a fixed `vi.mock` factory so nothing shells out to git; a
+ * pure helper exported from it would come back `undefined` under every such
+ * stub. Here it is imported for real wherever the git probes are mocked.
+ */
+/** `info.status`, or the answer `isStale` implies for an info built without one. */
+export const stalenessStatus = (info) => info.status ?? (info.isStale ? 'behind' : 'current');
+/**
+ * Project a check into {@link StalenessPayload}, or `undefined` when there is
+ * nothing to report.
+ *
+ * `unknown` is emitted only when `includeUnknown` is set. A listing a monitor
+ * reads wants it; the hot read tools do not, because a `--skip-git` folder has
+ * no history to measure and would otherwise repeat that on every response.
+ */
+export const stalenessPayload = (info, opts = {}) => {
+    if (!info)
+        return undefined;
+    const status = stalenessStatus(info);
+    const hint = info.hint ? { hint: info.hint } : {};
+    if (status === 'current')
+        return undefined;
+    if (status === 'unknown')
+        return opts.includeUnknown ? { status } : undefined;
+    if (status === 'diverged')
+        return { status, ...hint };
+    return { status, commitsBehind: info.commitsBehind, ...hint };
+};

package/dist/mcp/local/local-backend.d.ts

@@ -8,7 +8,7 @@
 import { isTestFilePath } from '../../core/ingestion/utils/test-file-path.js';
 import { type RegistryEntry, type BranchSummary } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
-import { type StalenessInfo } from '../../core/git-staleness.js';
+import { type StalenessInfo, type StalenessPayload } from '../../core/staleness-status.js';
 /** Shared predicate; re-exported so MCP importers keep the old public name. */
 export { isTestFilePath };
 /** Valid LadybugDB node labels for safe Cypher query construction */
@@ -233,10 +233,7 @@ export interface RepoListing {
     lastCommit: string;
     remoteUrl?: string;
     stats?: any;
-    staleness?: {
-        commitsBehind: number;
-        hint?: string;
-    };
+    staleness?: StalenessPayload;
     siblings?: Array<{
         name: string;
         path: string;
@@ -264,11 +261,16 @@ export interface ListReposPagination {
 }
 /**
  * #2655: attach a non-blocking `staleness` signal to a tool result when the
- * index is behind HEAD, mirroring the `list_repos` `{commitsBehind, hint}`
- * shape. Only ever ADDS a field to a carryable object result (see
+ * index is not at HEAD, in the same {@link stalenessPayload} shape `list_repos`
+ * returns. Only ever ADDS a field to a carryable object result (see
  * {@link canCarryStaleness}) — it never changes an existing result's shape.
+ *
+ * `diverged` is attached: it is a positive finding that the index is not at
+ * HEAD, only uncountable. `unknown` is not — these are the hot read tools, and a
+ * `--skip-git` folder has no history to measure, so it would ride on every
+ * response as noise rather than signal (#3256).
  */
-export declare function attachToolStaleness(result: unknown, staleness: StalenessInfo | undefined): unknown;
+export declare function attachToolStaleness(result: unknown, info: StalenessInfo | undefined): unknown;
 export declare class LocalBackend {
     private static readonly TOOL_STALENESS_TTL_MS;
     private repos;
@@ -553,9 +555,10 @@ export declare class LocalBackend {
      * one `git rev-list` per index per TTL window; the resolved value is cached
      * for TOOL_STALENESS_TTL_MS. Keyed by lbugPath so flat and branch handles
      * (same repoPath, different lastCommit) don't share an entry. Non-blocking by
-     * construction: `checkStalenessAsync` swallows git failures to
-     * `{ isStale: false }`, so a git error never fails the tool — it just omits
-     * the `staleness` field.
+     * construction: `checkStalenessAsync` keeps `isStale: false` on every git
+     * failure and reports what it could still establish in `status` (`diverged`,
+     * `unknown`, or `current` when HEAD alone matches the index), so a git error
+     * never fails the tool — at most it attaches a `diverged` staleness field.
      */
     private stalenessForTool;
     callTool(method: string, params: any): Promise<any>;

package/dist/mcp/local/local-backend.js

@@ -49,7 +49,8 @@ import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { ftsDegradedWarning, ftsQueryFailedWarning } from '../../core/search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, containsSegmentableCjkRun, getSearchFTSCjkSegmentation, isSupportedCjkSegmentationMode, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from '../../core/search/cjk-segmentation.js';
-import { checkStalenessAsync, checkCwdMatch, } from '../../core/git-staleness.js';
+import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
+import { stalenessPayload, } from '../../core/staleness-status.js';
 import { logger } from '../../core/logger.js';
 import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
@@ -900,18 +901,21 @@ function canCarryStaleness(result) {
 }
 /**
  * #2655: attach a non-blocking `staleness` signal to a tool result when the
- * index is behind HEAD, mirroring the `list_repos` `{commitsBehind, hint}`
- * shape. Only ever ADDS a field to a carryable object result (see
+ * index is not at HEAD, in the same {@link stalenessPayload} shape `list_repos`
+ * returns. Only ever ADDS a field to a carryable object result (see
  * {@link canCarryStaleness}) — it never changes an existing result's shape.
+ *
+ * `diverged` is attached: it is a positive finding that the index is not at
+ * HEAD, only uncountable. `unknown` is not — these are the hot read tools, and a
+ * `--skip-git` folder has no history to measure, so it would ride on every
+ * response as noise rather than signal (#3256).
  */
-export function attachToolStaleness(result, staleness) {
-    if (!staleness?.isStale || !canCarryStaleness(result)) {
+export function attachToolStaleness(result, info) {
+    const staleness = stalenessPayload(info);
+    if (!staleness || !canCarryStaleness(result)) {
         return result;
     }
-    return {
-        ...result,
-        staleness: { commitsBehind: staleness.commitsBehind, hint: staleness.hint },
-    };
+    return { ...result, staleness };
 }
 export class LocalBackend {
     static TOOL_STALENESS_TTL_MS = 5000;
@@ -1818,9 +1822,7 @@ export class LocalBackend {
                 lastCommit: h.lastCommit,
                 remoteUrl: h.remoteUrl,
                 stats: h.stats,
-                staleness: stale.isStale
-                    ? { commitsBehind: stale.commitsBehind, hint: stale.hint }
-                    : undefined,
+                staleness: stalenessPayload(stale, { includeUnknown: true }),
                 siblings: siblings.length > 0
                     ? siblings.map((s) => ({
                         name: s.name,
@@ -1958,9 +1960,10 @@ export class LocalBackend {
      * one `git rev-list` per index per TTL window; the resolved value is cached
      * for TOOL_STALENESS_TTL_MS. Keyed by lbugPath so flat and branch handles
      * (same repoPath, different lastCommit) don't share an entry. Non-blocking by
-     * construction: `checkStalenessAsync` swallows git failures to
-     * `{ isStale: false }`, so a git error never fails the tool — it just omits
-     * the `staleness` field.
+     * construction: `checkStalenessAsync` keeps `isStale: false` on every git
+     * failure and reports what it could still establish in `status` (`diverged`,
+     * `unknown`, or `current` when HEAD alone matches the index), so a git error
+     * never fails the tool — at most it attaches a `diverged` staleness field.
      */
     stalenessForTool(repo) {
         const now = Date.now();

package/dist/mcp/staleness.d.ts

@@ -1,5 +1,7 @@
 /**
- * Staleness Check — re-export from core (see `core/git-staleness.ts`).
+ * Staleness Check — re-export from core (see `core/git-staleness.ts` and
+ * `core/staleness-status.ts`).
  */
-export type { StalenessInfo } from '../core/git-staleness.js';
+export type { StalenessInfo, StalenessPayload, StalenessStatus } from '../core/staleness-status.js';
 export { checkStaleness } from '../core/git-staleness.js';
+export { stalenessPayload, stalenessStatus } from '../core/staleness-status.js';

package/dist/mcp/staleness.js

@@ -1,4 +1,6 @@
 /**
- * Staleness Check — re-export from core (see `core/git-staleness.ts`).
+ * Staleness Check — re-export from core (see `core/git-staleness.ts` and
+ * `core/staleness-status.ts`).
  */
 export { checkStaleness } from '../core/git-staleness.js';
+export { stalenessPayload, stalenessStatus } from '../core/staleness-status.js';

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

@@ -9,41 +9,30 @@
  * 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 StalenessInfo, type StalenessPayload } from '../core/staleness-status.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.
+ * Staleness through the shared {@link stalenessPayload} builder, so this route
+ * and MCP `list_repos` emit one shape for one fact (#3232 review, #3256).
  *
- * `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.
+ * Absent when the index is current. Otherwise `staleness.status` says what git
+ * could establish: `behind` with the counted `commitsBehind`; `diverged` when
+ * HEAD has provably moved off the indexed commit but the history needed to
+ * count the gap is gone — the state a branch-pinned `url` clone reaches once
+ * git prunes the commit a failed re-index left behind; or `unknown` when the
+ * repository could not be measured at all. This is a listing a monitor reads,
+ * so `unknown` is included here, unlike on the hot read tools.
  *
- * 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.
+ * All of it measures the index against the local working tree — the same thing
+ * `gitnexus status` and MCP `list_repos` measure — not against the remote.
  */
 export declare const stalenessField: (info: StalenessInfo) => {
-    staleness?: {
-        commitsBehind: number;
-        hint?: string;
-    };
+    staleness?: StalenessPayload;
 };
 /** One entry of `GET /api/repos`. */
 export declare const projectRepoListEntry: (entry: RegistryEntry, staleness: StalenessInfo) => {
-    staleness?: {
-        commitsBehind: number;
-        hint?: string;
-    };
+    staleness?: StalenessPayload;
     name: string;
     path: string;
     repoPath: string;
@@ -66,10 +55,7 @@ export declare const projectRepoListEntry: (entry: RegistryEntry, staleness: Sta
  * 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;
-    };
+    staleness?: StalenessPayload;
     name: string;
     repoPath: string;
     indexedAt: string;

package/dist/server/repo-projection.js

@@ -1,24 +1,34 @@
 /**
- * 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.
+ * Response projections for the `serve` repo routes.
  *
- * `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.
+ * 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).
  *
- * 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.
+ * These are pure: the caller resolves the registry entry, the on-disk metadata
+ * and the staleness check, and passes the results in.
  */
-export const stalenessField = (info) => info.isStale ? { staleness: { commitsBehind: info.commitsBehind, hint: info.hint } } : {};
+import { stalenessPayload, } from '../core/staleness-status.js';
+/**
+ * Staleness through the shared {@link stalenessPayload} builder, so this route
+ * and MCP `list_repos` emit one shape for one fact (#3232 review, #3256).
+ *
+ * Absent when the index is current. Otherwise `staleness.status` says what git
+ * could establish: `behind` with the counted `commitsBehind`; `diverged` when
+ * HEAD has provably moved off the indexed commit but the history needed to
+ * count the gap is gone — the state a branch-pinned `url` clone reaches once
+ * git prunes the commit a failed re-index left behind; or `unknown` when the
+ * repository could not be measured at all. This is a listing a monitor reads,
+ * so `unknown` is included here, unlike on the hot read tools.
+ *
+ * All of it measures the index against the local working tree — the same thing
+ * `gitnexus status` and MCP `list_repos` measure — not against the remote.
+ */
+export const stalenessField = (info) => {
+    const staleness = stalenessPayload(info, { includeUnknown: true });
+    return staleness ? { staleness } : {};
+};
 /** One entry of `GET /api/repos`. */
 export const projectRepoListEntry = (entry, staleness) => ({
     name: entry.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.12-rc.30",
+  "version": "1.6.12-rc.32",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",