gitnexus 1.6.13-rc.67 → 1.6.13-rc.69

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

@@ -4,14 +4,16 @@
  * against a real group, which is how `STALE (-1 commits behind)` went unnoticed
  * (#3256).
  */
+import type { StalenessStatus } from '../core/staleness-status.js';
 /** The fields of a `groupStatus` repo row the index column reads. */
 export interface GroupRepoIndexRow {
     indexStale: boolean;
     commitsBehind?: number;
+    status?: StalenessStatus;
 }
 /**
- * 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 `?`.
+ * The index column of a `group status` row. Diverged indexes differ from HEAD
+ * without a forward commit count; an unavailable count renders as `?`.
  *
  * `group/service.ts` has always reported a repo with no recorded commit as
  * `{ indexStale: true, commitsBehind: -1 }`. The previous `?? '?'` fallback

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

@@ -1,12 +1,6 @@
 /**
- * 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 `?`.
+ * The index column of a `group status` row. Diverged indexes differ from HEAD
+ * without a forward commit count; an unavailable count renders as `?`.
  *
  * `group/service.ts` has always reported a repo with no recorded commit as
  * `{ indexStale: true, commitsBehind: -1 }`. The previous `?? '?'` fallback
@@ -15,6 +9,8 @@
 export const formatIndexStatusCell = (row) => {
     if (!row.indexStale)
         return 'OK        ';
+    if (row.status === 'diverged')
+        return 'STALE     (index differs from HEAD)';
     const n = row.commitsBehind;
     const count = typeof n === 'number' && n >= 0 ? String(n) : '?';
     return `STALE     (${count} commits behind)`;

package/dist/core/git-staleness.js

@@ -9,8 +9,8 @@ import { readRegistry } from '../storage/repo-manager.js';
 import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 const execFileAsync = promisify(execFile);
 /**
- * Ceiling for one `git rev-list` staleness probe. Generous for the local
- * history walk this is, and short enough that an unresponsive working tree
+ * Per-command ceiling for async `git rev-list` and both HEAD probes.
+ * Generous for local Git queries, and short enough that an unresponsive working tree
  * degrades to "not stale" quickly rather than holding a request open.
  */
 const STALENESS_TIMEOUT_MS = 5_000;
@@ -20,10 +20,20 @@ const behindHint = (n) => `⚠️ Index is ${n} commit${n > 1 ? 's' : ''} behind
 // 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.";
+// `rev-list --count lastCommit..HEAD` answering 0 does NOT mean "HEAD is the
+// indexed commit" — it means "HEAD has no commits lastCommit lacks", which is
+// also true when HEAD is an *ancestor* of lastCommit (the working tree checked
+// out an older commit than the one indexed, or switched to a line of history
+// behind it). That read a rollback as `current` until this hint existed.
+const REGRESSED_HINT = '⚠️ Index is not at HEAD — the indexed commit is not reachable from the checked-out commit (the working tree may have checked out an older commit, or a different line of 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' };
+// Called only once a positive HEAD-only count is in hand.
+const behind = (commitsBehind) => ({
+    isStale: true,
+    commitsBehind,
+    hint: behindHint(commitsBehind),
+    status: 'behind',
+});
 /**
  * `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
@@ -38,6 +48,28 @@ const fromHead = (head, lastCommit) => {
         return { isStale: false, commitsBehind: 0, status: 'current' };
     return { isStale: false, commitsBehind: 0, hint: DIVERGED_HINT, status: 'diverged' };
 };
+/**
+ * `rev-list --left-right --count lastCommit...HEAD` measures both sides in
+ * one process, so a later HEAD change cannot mix two snapshots. The left
+ * count identifies a rollback even when the HEAD-only (right) count is 0.
+ * Positive right counts keep the existing `behind` behavior, including when
+ * both sides have commits (divergent branches or a re-shallowed clone).
+ */
+const fromCounts = (output) => {
+    const counts = /^(\d+)\s+(\d+)$/.exec(output.trim());
+    if (!counts)
+        return unknown();
+    const indexedOnly = Number(counts[1]);
+    const headOnly = Number(counts[2]);
+    if (!Number.isSafeInteger(indexedOnly) || !Number.isSafeInteger(headOnly))
+        return unknown();
+    if (headOnly > 0)
+        return behind(headOnly);
+    if (indexedOnly > 0) {
+        return { isStale: true, commitsBehind: 0, hint: REGRESSED_HINT, status: 'diverged' };
+    }
+    return { isStale: false, commitsBehind: 0, status: 'current' };
+};
 const readHeadSync = (repoPath) => {
     try {
         return (execFileSync('git', ['rev-parse', 'HEAD'], {
@@ -45,6 +77,7 @@ const readHeadSync = (repoPath) => {
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
+            timeout: STALENESS_TIMEOUT_MS,
         }).trim() || null);
     }
     catch {
@@ -73,13 +106,13 @@ export function checkStaleness(repoPath, lastCommit) {
     if (!lastCommit)
         return unknown();
     try {
-        const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+        const result = execFileSync('git', ['rev-list', '--left-right', '--count', `${lastCommit}...HEAD`], {
             cwd: repoPath,
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
-        }).trim();
-        return fromCount(parseInt(result, 10) || 0);
+        });
+        return fromCounts(result);
     }
     catch {
         return fromHead(readHeadSync(repoPath), lastCommit);
@@ -96,7 +129,7 @@ export async function checkStalenessAsync(repoPath, lastCommit) {
     try {
         // Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
         // unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
-        const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+        const { stdout } = await execFileAsync('git', ['rev-list', '--left-right', '--count', `${lastCommit}...HEAD`], {
             cwd: repoPath,
             encoding: 'utf-8',
             windowsHide: true,
@@ -109,7 +142,7 @@ export async function checkStalenessAsync(repoPath, lastCommit) {
             // below reports it as `unknown` — still the fail-closed `isStale: false`.
             timeout: STALENESS_TIMEOUT_MS,
         });
-        return fromCount(parseInt(stdout.trim(), 10) || 0);
+        return fromCounts(stdout);
     }
     catch (err) {
         // A rev-list that timed out means the working tree is not answering. Asking

package/dist/core/lbug/lbug-adapter.d.ts

@@ -893,9 +893,10 @@ export declare const buildFtsQueryCypher: (tableName: string, indexName: string,
  * @param query - Search query string
  * @param limit - Maximum results
  * @param conjunctive - If true, all terms must match (AND); if false, any term matches (OR)
+ * @param missingIndex - Preserve the empty-result default, or propagate missing indexes for diagnostics
  * @returns Array of { node properties, score }
  */
-export declare const queryFTS: (tableName: string, indexName: string, query: string, limit?: number, conjunctive?: boolean) => Promise<Array<{
+export declare const queryFTS: (tableName: string, indexName: string, query: string, limit?: number, conjunctive?: boolean, missingIndex?: 'empty' | 'throw') => Promise<Array<{
     nodeId: string;
     name: string;
     filePath: string;

package/dist/core/lbug/lbug-adapter.js

@@ -3504,9 +3504,10 @@ export const buildFtsQueryCypher = (tableName, indexName, limit, conjunctive = f
  * @param query - Search query string
  * @param limit - Maximum results
  * @param conjunctive - If true, all terms must match (AND); if false, any term matches (OR)
+ * @param missingIndex - Preserve the empty-result default, or propagate missing indexes for diagnostics
  * @returns Array of { node properties, score }
  */
-export const queryFTS = async (tableName, indexName, query, limit = 20, conjunctive = false) => {
+export const queryFTS = async (tableName, indexName, query, limit = 20, conjunctive = false, missingIndex = 'empty') => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
@@ -3532,7 +3533,7 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
         // NEW-6 — this used to be a bare `.includes('does not exist')` check
         // that could not tell the two apart).
         const message = e instanceof Error ? e.message : String(e);
-        if (classifyFtsQueryError(message) === 'missing-index') {
+        if (missingIndex === 'empty' && classifyFtsQueryError(message) === 'missing-index') {
             return [];
         }
         throw e;

package/dist/core/search/bm25-index.d.ts

@@ -29,6 +29,8 @@ export interface FTSSearchResponse {
      * which only does so when every table failed).
      */
     nonBenignErrors?: string[];
+    /** Configured table.index names that could not be queried because their index is missing. */
+    missingIndexes?: string[];
 }
 /**
  * Search using LadybugDB's built-in FTS (fresh, reads from disk)

package/dist/core/search/bm25-index.js

@@ -86,6 +86,7 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId, disabledReaso
     const resultsByIndex = [];
     let queriesSucceeded = 0;
     const nonBenignErrors = [];
+    const missingIndexes = [];
     const ftsExtension = getExtensionCapabilities().find((c) => c.name === 'fts');
     if (ftsExtension && !ftsExtension.loaded) {
         // tri-review NEW-4 (applies to BOTH the MCP pool path and the CLI/pipeline
@@ -114,26 +115,32 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId, disabledReaso
                 queriesSucceeded++;
                 resultsByIndex.push(outcome.rows);
             }
-            else if (!outcome.benign) {
+            else if (outcome.benign) {
+                missingIndexes.push(`${table}.${indexName}`);
+            }
+            else {
                 nonBenignErrors.push(redactPaths(outcome.message ?? 'Unknown FTS query error'));
             }
         }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
-        // tri-review Residual-1: `queryFTS` itself only swallows a genuinely-missing
-        // index (via the SAME classifyFtsQueryError this module re-exports); a
-        // missing-table or real query error rethrows here — track it the same way
-        // the MCP pool path does instead of a bare `catch {}` that dropped it.
+        // Opt into missing-index propagation so absent indexes cannot masquerade
+        // as successful zero-match queries. Keep core/pool classification identical.
         for (const { table, indexName } of FTS_INDEXES) {
             try {
-                const result = await queryFTS(table, indexName, searchQuery, limit, false);
+                const result = await queryFTS(table, indexName, searchQuery, limit, false, 'throw');
                 queriesSucceeded++;
                 resultsByIndex.push(result);
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
-                nonBenignErrors.push(redactPaths(message));
+                if (classifyFtsQueryError(message) === 'missing-index') {
+                    missingIndexes.push(`${table}.${indexName}`);
+                }
+                else {
+                    nonBenignErrors.push(redactPaths(message));
+                }
             }
         }
     }
@@ -174,5 +181,6 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId, disabledReaso
         })),
         ftsAvailable,
         ...(nonBenignErrors.length > 0 && { nonBenignErrors }),
+        ...(missingIndexes.length > 0 && { missingIndexes }),
     };
 };

package/dist/core/search/fts-indexes.d.ts

@@ -48,15 +48,12 @@ export interface FtsWarningContext {
  */
 export declare const ftsDegradedWarning: (context?: FtsWarningContext, disabledReason?: FtsDisabledReason) => string;
 /**
- * Warning for when the FTS extension is loaded and indexes exist, but every
- * configured table's query failed for a real, non-benign reason (timeout,
- * connection reset, native fault) — as opposed to `ftsDegradedWarning`'s
- * missing-index case. `--repair-fts` will not fix a query/connection error,
- * so this deliberately does NOT suggest it: reusing the missing-index
- * message here would reproduce, for this cause, the exact misleading
- * "run --repair-fts" guidance #2767 itself was about (tri-review NEW-1).
+ * Warning when no FTS query succeeded and at least one failed for a real,
+ * non-benign reason (timeout, connection reset, native fault). `--repair-fts`
+ * will not fix those errors. If indexes are also missing, the caller composes
+ * their repair guidance separately; do not deny that additional failure cause.
  */
-export declare const ftsQueryFailedWarning: (context: FtsWarningContext) => string;
+export declare const ftsQueryFailedWarning: (context: FtsWarningContext, hasMissingIndexes?: boolean) => string;
 export declare const SUPPORTED_FTS_STEMMERS: ReadonlySet<string>;
 export interface CreateSearchFTSIndexesOptions {
     indexes?: readonly FTSIndexDefinition[];

package/dist/core/search/fts-indexes.js

@@ -72,18 +72,17 @@ export const ftsDegradedWarning = (context, disabledReason) => {
         suffix);
 };
 /**
- * Warning for when the FTS extension is loaded and indexes exist, but every
- * configured table's query failed for a real, non-benign reason (timeout,
- * connection reset, native fault) — as opposed to `ftsDegradedWarning`'s
- * missing-index case. `--repair-fts` will not fix a query/connection error,
- * so this deliberately does NOT suggest it: reusing the missing-index
- * message here would reproduce, for this cause, the exact misleading
- * "run --repair-fts" guidance #2767 itself was about (tri-review NEW-1).
+ * Warning when no FTS query succeeded and at least one failed for a real,
+ * non-benign reason (timeout, connection reset, native fault). `--repair-fts`
+ * will not fix those errors. If indexes are also missing, the caller composes
+ * their repair guidance separately; do not deny that additional failure cause.
  */
-export const ftsQueryFailedWarning = (context) => 'FTS keyword search failed — every configured index query returned an error' +
+export const ftsQueryFailedWarning = (context, hasMissingIndexes = false) => 'FTS keyword search failed — every configured index query returned an error' +
     (context.lastErrorRedacted ? ` (${context.lastErrorRedacted})` : '') +
-    '; results do not include keyword matches. This is not a missing-index ' +
-    'condition — see server logs for details.' +
+    '; results do not include keyword matches. ' +
+    (hasMissingIndexes
+        ? 'See server logs for query error details.'
+        : 'This is not a missing-index condition — see server logs for details.') +
     ` (resolved: ${formatResolvedSuffix(context)})`;
 // Stemmers shipped by the LadybugDB FTS extension. Mirrors the lowercase token
 // set in the extension bundled with @ladybugdb/core 0.18.x (see package.json).

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

@@ -17,21 +17,35 @@
  * 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.
+ * The successful probe is `rev-list --left-right --count lastCommit...HEAD`:
+ * the left count is indexed-only commits, and the right is HEAD-only commits.
+ * Both counts come from one HEAD snapshot, without a follow-up process.
  *
- * `isStale` and `commitsBehind` keep their historical values in every case, so
- * no existing consumer changes behaviour unless it reads `status`.
+ * - `current`  — both counts are 0, or `rev-list` could not answer but a
+ *   fallback `rev-parse HEAD` resolved to the indexed commit.
+ * - `behind`   — the right count is N > 0; `commitsBehind` is N, including
+ *   when the left count is positive too (divergent or shallow history).
+ * - `diverged` — the index is provably not at HEAD, reached two different ways:
+ *     - The left count is positive and the right is 0: HEAD is an ancestor
+ *       of the indexed commit (#3127). The working tree checked out an older
+ *       commit than the one indexed, or a release branch behind the indexed
+ *       tip. The mismatch is established: `isStale` is `true` and
+ *       `commitsBehind` stays 0 (there is no forward count to report).
+ *     - `rev-list` could not answer at all, but HEAD resolved and is not the
+ *       indexed commit: 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. This arm keeps the
+ *       historical fail-open `isStale: false` (see below).
+ * - `unknown`  — the probe could not establish the relationship: no readable
+ *   HEAD, a timeout, no recorded commit, or malformed count output.
+ *
+ * `isStale` and `commitsBehind` keep their historical fail-open values
+ * (`false` / `0`) whenever the check could not fully answer — every `unknown`,
+ * and the `rev-list`-failure arm of `diverged` — so no existing consumer
+ * changes behaviour there unless it reads `status`. The other arm of
+ * `diverged` (the confirmed rollback) is a successful, computed
+ * answer rather than a failure, so `isStale` reflects it (`true`) instead.
  */
 export type StalenessStatus = 'current' | 'behind' | 'diverged' | 'unknown';
 export interface StalenessInfo {

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

@@ -2413,6 +2413,7 @@ export class LocalBackend {
         // regardless of whether OTHER tables succeeded — previously a real error
         // on N-1 of N tables while one succeeded left zero diagnostic trail.
         const ftsQueryErrors = bm25SearchResult?.nonBenignErrors;
+        const ftsMissingIndexes = bm25SearchResult?.missingIndexes;
         if (ftsQueryErrors) {
             // tri-review NEW-5: these strings are already classified non-benign by
             // classifyFtsQueryError — do NOT route them through logQueryError,
@@ -2847,12 +2848,11 @@ export class LocalBackend {
                 branch: repo.branch,
                 indexedAt: this.lastObservedPoolState.get(repo.lbugPath)?.indexedAt ?? repo.indexedAt,
             };
-            // tri-review NEW-1: every table failing for a REAL error (timeout,
-            // connection reset) is not a missing-index condition — `ftsDegradedWarning`'s
-            // "run --repair-fts" headline won't fix it. Route to a dedicated message
-            // instead of burying the real cause as a trailing suffix on bad advice.
+            // Real errors (timeout, connection reset) need their own diagnosis.
+            // When some indexes are also missing, preserve both causes and append
+            // their repair guidance below even though no FTS query succeeded.
             warnings.push(ftsQueryErrors
-                ? ftsQueryFailedWarning({ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] })
+                ? ftsQueryFailedWarning({ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] }, !!ftsMissingIndexes?.length)
                 : ftsDegradedWarning(warningContext, ftsDisabledReason));
         }
         else if (ftsQueryErrors) {
@@ -2863,6 +2863,10 @@ export class LocalBackend {
             // that convention instead of only logging server-side.
             warnings.push(`FTS keyword search partially failed — ${ftsQueryErrors.length} of the configured indexes hit a query error and were skipped; results may be missing matches from those node types (see server logs).`);
         }
+        if (ftsMissingIndexes?.length && (ftsUsed || ftsQueryErrors)) {
+            warnings.push(`FTS keyword search is incomplete: missing configured indexes (${ftsMissingIndexes.join(', ')}). ` +
+                'Results may be missing matches from those node types. Run `gitnexus analyze --repair-fts`.');
+        }
         // #2331: a CJK query against a server process resolving
         // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
         // matches with no other signal — this is the only place an agent driving
@@ -2979,7 +2983,7 @@ export class LocalBackend {
         // #2767: a partial FTS failure (some tables ok, one or more real errors)
         // is as much a "results may be incomplete" signal as enrichmentDegraded —
         // flag it the same way rather than only via the warning string.
-        const ftsPartial = ftsUsed && !!ftsQueryErrors;
+        const ftsPartial = ftsUsed && (!!ftsQueryErrors || !!ftsMissingIndexes?.length);
         return {
             processes,
             process_symbols,
@@ -3023,6 +3027,7 @@ export class LocalBackend {
         const bm25Results = ftsResponse?.results ?? [];
         const ftsUsed = ftsResponse?.ftsAvailable ?? false;
         const nonBenignErrors = ftsResponse?.nonBenignErrors;
+        const missingIndexes = ftsResponse?.missingIndexes;
         const results = [];
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;
@@ -3087,7 +3092,12 @@ export class LocalBackend {
                 });
             }
         }
-        return { results, ftsUsed, ...(nonBenignErrors && { nonBenignErrors }) };
+        return {
+            results,
+            ftsUsed,
+            ...(nonBenignErrors && { nonBenignErrors }),
+            ...(missingIndexes && { missingIndexes }),
+        };
     }
     /**
      * Keyword-only indexes are the default. Do not put this on `query.warning`

package/dist/mcp/resources.js

@@ -281,7 +281,7 @@ async function getContextResource(backend, repoName) {
     const incompleteReasons = getIndexIncompleteReasons(freshMeta);
     // Check staleness using the current on-disk lastCommit (not the cached handle)
     const repoPath = repo.repoPath;
-    const lastCommit = freshMeta?.lastCommit ?? repo.lastCommit ?? 'HEAD';
+    const lastCommit = freshMeta?.lastCommit ?? repo.lastCommit ?? '';
     const staleness = repoPath
         ? checkStaleness(repoPath, lastCommit)
         : { isStale: false, commitsBehind: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.67",
+  "version": "1.6.13-rc.69",
   "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",