gitnexus 1.6.13-rc.5 → 1.6.13-rc.7

package/dist/cli/ai-context.js

@@ -137,6 +137,7 @@ ${tableBody}`
 This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}.
 
 > Index stale? Run \`${runner} analyze --index-only\` from the project root — it auto-selects an available runner. ${bootstrapNote}
+> On query/context/impact/cypher object results, read staleness.status and branch/lastCommit. Re-analyze only for behind or diverged — current is clone HEAD, not main.
 
 ## Always Do
 

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

@@ -47,17 +47,51 @@ export interface StalenessInfo {
 }
 /** `info.status`, or the answer `isStale` implies for an info built without one. */
 export declare const stalenessStatus: (info: StalenessInfo) => StalenessStatus;
+/**
+ * The ref an index represents, as the resolved repo handle already knows it.
+ * `lastCommit` and `indexedAt` are always recorded on a handle; `branch` is
+ * best-effort — a plain analyze stamps the checked-out branch, but a detached
+ * HEAD, a non-git folder, or a legacy index that never recorded one leaves it
+ * absent (`run-analyze.ts`: `branchLabel ?? existingMeta?.branch`).
+ */
+export interface IndexedRef {
+    branch?: string;
+    lastCommit: string;
+    indexedAt: string;
+}
 /**
  * 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.
+ * Two forms, chosen by whether the caller supplies a {@link IndexedRef}:
+ *
+ * - **Without a ref** — absent for `current`, as before. That is what
+ *   `list_repos` and the `serve` routes emit; they already report the ref
+ *   through their own top-level `branch` / `lastCommit` / `indexedAt` fields
+ *   (#3226), so repeating it inside the payload would duplicate it.
+ * - **With a ref** — emitted for EVERY status, naming the index it describes.
+ *   The hot read tools have nowhere else to put it: `attachToolStaleness` may
+ *   add exactly one key to an arbitrary tool result. Without it `current` is
+ *   indistinguishable between an index of the default branch and one of some
+ *   feature branch, because `current` is a statement about a *ref*, not about
+ *   the repository (#3291).
+ *
+ * `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'>;
+    status: StalenessStatus;
+    /** Ref identity — present only on the ref-carrying (hot read tool) form. */
+    branch?: string;
+    lastCommit?: string;
+    indexedAt?: string;
+    /**
+     * What `commitsBehind` is counted against: the checked-out HEAD of the clone
+     * this index was built from, never the remote or the default branch.
+     */
+    measuredAgainst?: 'HEAD';
     commitsBehind?: number;
     hint?: string;
 }
@@ -66,9 +100,12 @@ export interface StalenessPayload {
  * 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.
+ * reads wants it; the no-ref hot-tool form does not, because a `--skip-git`
+ * folder has no history to measure and would otherwise repeat that on every
+ * response. The ref-carrying form reports it regardless — which index answered
+ * is knowable even when its freshness is not.
  */
 export declare const stalenessPayload: (info: StalenessInfo | undefined, opts?: {
     includeUnknown?: boolean;
+    ref?: IndexedRef;
 }) => StalenessPayload | undefined;

package/dist/core/staleness-status.js

@@ -14,19 +14,37 @@ export const stalenessStatus = (info) => info.status ?? (info.isStale ? 'behind'
  * 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.
+ * reads wants it; the no-ref hot-tool form does not, because a `--skip-git`
+ * folder has no history to measure and would otherwise repeat that on every
+ * response. The ref-carrying form reports it regardless — which index answered
+ * is knowable even when its freshness is not.
  */
 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;
+    // No ref: bit-identical to the pre-#3291 output for every status. This is
+    // what keeps `list_repos` and both `serve` routes byte-stable, and their
+    // exact-match tests passing unmodified.
+    if (!opts.ref) {
+        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 };
+    }
+    const ref = {
+        ...(opts.ref.branch ? { branch: opts.ref.branch } : {}),
+        lastCommit: opts.ref.lastCommit,
+        indexedAt: opts.ref.indexedAt,
+        measuredAgainst: 'HEAD',
+    };
+    if (status === 'current' || status === 'unknown')
+        return { status, ...ref };
     if (status === 'diverged')
-        return { status, ...hint };
-    return { status, commitsBehind: info.commitsBehind, ...hint };
+        return { status, ...ref, ...hint };
+    return { status, ...ref, 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, type StalenessPayload } from '../../core/staleness-status.js';
+import { type IndexedRef, 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 */
@@ -186,7 +186,11 @@ interface RepoHandle {
     lastCommit: string;
     remoteUrl?: string;
     stats?: RegistryEntry['stats'];
-    /** Primary/flat branch name, when known (#2106). */
+    /**
+     * Branch this handle's index describes (#2106/#3291). The flat/workspace
+     * slot keeps the primary checkout name; `applyBranchScope` overwrites it
+     * with the pin when serving a `branches[]` sub-index.
+     */
     branch?: string;
     /** Pinned `--branch` sub-indexes available for this repo, distinct from the flat workspace slot (#2106/#2354). */
     branches?: BranchSummary[];
@@ -263,17 +267,24 @@ export interface ListReposPagination {
     nextOffset?: number;
 }
 /**
- * #2655: attach a non-blocking `staleness` signal to a tool result when the
- * 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.
+ * #2655: attach a non-blocking `staleness` signal to a tool result. 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).
+ * #3291: `ref` names the index the answer came from. Supplying it switches the
+ * payload to the ref-carrying form, which reports every status — including
+ * `current` and `unknown` — because that one added key is the only place a tool
+ * result can say WHICH index answered. Absence used to be the freshness signal
+ * here; it could not distinguish a current index of the default branch from a
+ * current index of some feature branch, since `current` is a statement about a
+ * ref rather than about the repository.
+ *
+ * With no `ref` the pre-#3291 behaviour is unchanged: absent for `current`,
+ * `diverged` attached as a positive finding that the index is not at HEAD, and
+ * `unknown` withheld as noise (#3256). A missing `info` still attaches nothing
+ * either way, which is what keeps a failed freshness probe non-fatal.
  */
-export declare function attachToolStaleness(result: unknown, info: StalenessInfo | undefined): unknown;
+export declare function attachToolStaleness(result: unknown, info: StalenessInfo | undefined, ref?: IndexedRef): unknown;
 export declare class LocalBackend {
     private static readonly TOOL_STALENESS_TTL_MS;
     private repos;
@@ -567,6 +578,12 @@ export declare class LocalBackend {
      * skipping the `git` spawn entirely for results that can't carry it (error
      * envelopes, arrays, non-objects — see {@link canCarryStaleness}) so an
      * error-returning call pays nothing.
+     *
+     * #3291: the ref comes straight off the already-resolved handle, so naming
+     * the index costs no extra I/O — no git spawn, no metadata read, and the
+     * `stalenessForTool` TTL cache is untouched. `branch` is passed through as-is
+     * and is legitimately absent for a detached HEAD or a legacy index; the
+     * always-present `lastCommit` is what identifies the index in that case.
      */
     private withToolStaleness;
     /**

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

@@ -925,18 +925,25 @@ function canCarryStaleness(result) {
         !('staleness' in result));
 }
 /**
- * #2655: attach a non-blocking `staleness` signal to a tool result when the
- * 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.
+ * #2655: attach a non-blocking `staleness` signal to a tool result. 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).
+ * #3291: `ref` names the index the answer came from. Supplying it switches the
+ * payload to the ref-carrying form, which reports every status — including
+ * `current` and `unknown` — because that one added key is the only place a tool
+ * result can say WHICH index answered. Absence used to be the freshness signal
+ * here; it could not distinguish a current index of the default branch from a
+ * current index of some feature branch, since `current` is a statement about a
+ * ref rather than about the repository.
+ *
+ * With no `ref` the pre-#3291 behaviour is unchanged: absent for `current`,
+ * `diverged` attached as a positive finding that the index is not at HEAD, and
+ * `unknown` withheld as noise (#3256). A missing `info` still attaches nothing
+ * either way, which is what keeps a failed freshness probe non-fatal.
  */
-export function attachToolStaleness(result, info) {
-    const staleness = stalenessPayload(info);
+export function attachToolStaleness(result, info, ref) {
+    const staleness = stalenessPayload(info, ref ? { ref } : {});
     if (!staleness || !canCarryStaleness(result)) {
         return result;
     }
@@ -1513,6 +1520,8 @@ export class LocalBackend {
                     indexedAt: summary.indexedAt,
                     lastCommit: summary.lastCommit,
                     stats: summary.stats,
+                    // The handle now represents the pin, not the flat slot (#3291).
+                    branch: summary.branch,
                 };
             }
             // Stale summary (sub-index adopted/deleted): refresh so later calls see
@@ -1994,6 +2003,12 @@ export class LocalBackend {
      * skipping the `git` spawn entirely for results that can't carry it (error
      * envelopes, arrays, non-objects — see {@link canCarryStaleness}) so an
      * error-returning call pays nothing.
+     *
+     * #3291: the ref comes straight off the already-resolved handle, so naming
+     * the index costs no extra I/O — no git spawn, no metadata read, and the
+     * `stalenessForTool` TTL cache is untouched. `branch` is passed through as-is
+     * and is legitimately absent for a detached HEAD or a legacy index; the
+     * always-present `lastCommit` is what identifies the index in that case.
      */
     async withToolStaleness(repo, result) {
         if (!canCarryStaleness(result))
@@ -2001,9 +2016,15 @@ export class LocalBackend {
         // Defensive: `checkStalenessAsync` self-catches today, but a rejection here
         // must never fail the tool — degrade to no-staleness. Paired with the
         // evict-on-reject in `stalenessForTool`, a transient failure also can't
-        // poison the TTL cache entry (#2655 review F1).
+        // poison the TTL cache entry (#2655 review F1). A rejection leaves `info`
+        // undefined, and the builder returns nothing for that even with a ref, so
+        // the degraded path still attaches no field.
         const staleness = await this.stalenessForTool(repo).catch(() => undefined);
-        return attachToolStaleness(result, staleness);
+        return attachToolStaleness(result, staleness, {
+            branch: repo.branch,
+            lastCommit: repo.lastCommit,
+            indexedAt: repo.indexedAt,
+        });
     }
     /**
      * #2655: commits-behind freshness for the hot read tools, deduped per index.

package/dist/mcp/tools.js

@@ -51,6 +51,8 @@ export const PDG_QUERY_MAX_LIMIT = 200;
 export const IMPACT_MAX_DEPTH = 32;
 const CWD_AWARE_REPO_OMISSION = 'Omit when only one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing an unindexed nested Git checkout; otherwise specify it explicitly.';
 const MUTATING_REPO_OMISSION = 'Omit only when one repo is indexed or an MCP default is configured; otherwise mutating tools require an explicit repo.';
+/** Always-on identity+freshness field on query/context/impact/cypher object results (#3291). */
+const HOT_READ_STALENESS_NOTE = "Object results attach `staleness` even when current. Read `staleness.branch`/`lastCommit` for which index answered and `status` for freshness. Re-analyze only for `behind` or `diverged` — `current` is this clone's HEAD, not necessarily the default branch; `unknown` is unmeasurable, not stale. Field is only on object results (not raw-array cypher, error envelopes, or `@group` calls).";
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
@@ -105,7 +107,9 @@ Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank
 
 GROUP MODE: set "repo" to "@<groupName>" to search all member repos in that group (merged via RRF), or "@<groupName>/<groupRepoPath>" to run against a single member (same path keys as in group.yaml). If you use "@<groupName>" only, the member repo defaults to the lexicographically first key in group.yaml "repos". Prefer resources for contracts/status (see migration from legacy group_* tools).
 
-SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). When "repo" starts with "@", only processes whose symbols fall under that prefix are included. For a normal indexed repo name (no leading @), this field is currently ignored by the server.`,
+SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). When "repo" starts with "@", only processes whose symbols fall under that prefix are included. For a normal indexed repo name (no leading @), this field is currently ignored by the server.
+
+${HOT_READ_STALENESS_NOTE}`,
         annotations: QUERY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -212,7 +216,9 @@ TIPS:
 - Community = auto-detected functional area (Leiden algorithm). Properties: heuristicLabel, cohesion, symbolCount, keywords, description, enrichedBy
 - Process = execution flow trace from entry point to terminal. Properties: heuristicLabel, processType, stepCount, communities, entryPointId, terminalId
 - Use heuristicLabel (not label) for human-readable community/process names
-- PDG layers (only when indexed with \`--pdg\`): BasicBlock nodes + CFG / CDG (control dependence, branch sense 'T'|'F' in reason) / REACHING_DEF (def→use, variable in reason) edges, all BasicBlock→BasicBlock. Prefer the \`pdg_query\` tool — it anchors + bounds these for you (raw \`[:CDG*]\`/\`[:REACHING_DEF*]\` path scans are unindexed and unbounded).`,
+- PDG layers (only when indexed with \`--pdg\`): BasicBlock nodes + CFG / CDG (control dependence, branch sense 'T'|'F' in reason) / REACHING_DEF (def→use, variable in reason) edges, all BasicBlock→BasicBlock. Prefer the \`pdg_query\` tool — it anchors + bounds these for you (raw \`[:CDG*]\`/\`[:REACHING_DEF*]\` path scans are unindexed and unbounded).
+
+${HOT_READ_STALENESS_NOTE}`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -264,7 +270,9 @@ REQUIRES RE-INDEX: causes.scopeExtractionFiles, causes.receiverTyping, causes.ex
 
 GROUP MODE: set "repo" to "@<groupName>" to run context in each member repo (aggregated list), or "@<groupName>/<groupRepoPath>" for one member. If you use "@<groupName>" only, the member defaults to the lexicographically first key in group.yaml "repos".
 
-SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", prefix-matches resolved symbol file paths; when a hit is outside the prefix, that member returns an empty payload for the symbol. Ignored for a normal indexed repo name.`,
+SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", prefix-matches resolved symbol file paths; when a hit is outside the prefix, that member returns an empty payload for the symbol. Ignored for a normal indexed repo name.
+
+${HOT_READ_STALENESS_NOTE}`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -473,7 +481,9 @@ Confidence: 1.0 = certain, <0.8 = fuzzy match
 
 GROUP MODE: set "repo" to "@<groupName>" for cross-repo impact anchored at the default member (lexicographically first key in group.yaml "repos"), or "@<groupName>/<groupRepoPath>" to choose the member (same path keys as in group.yaml). Phase-1 walk runs in that member; cross-boundary fan-out uses the group bridge. A cross entry with fanout_status:"not_attempted" proves the declared repository boundary, but its far endpoint has no graph symbol; do not interpret empty by_depth or affected_processes on that entry as a completed zero-impact walk. The fan-out attempts at most 50 neighbour crossings, strongest-confidence first. Any short answer carries truncated:true, truncatedRepos, riskEpistemic:"lower-bound" AND a truncationReason — dropping a crossing can only move risk DOWN, so treat that risk as a floor, never as a verdict. truncated:true does NOT always mean the fan-out ran out of room, so branch on truncationReason: the remedy differs. 'timeout' (the fan-out's wall-clock budget expired) and 'partial' (a neighbour crossing, or the local walk, was cut short) are runtime limits — the same query can return more on a retry or with a larger timeoutMs. 'incomplete-sync' is structural: the group bridge was built by a sync that could not say which repos it read, or that could not read an in-scope repo, so those repos' contracts are absent from EVERY query against this bridge, and truncatedRepos names them even when ZERO crossings to them were attempted. Retrying returns the same floor — run group_sync (\`gitnexus group sync\`) and query again. 'suppressed-stage' is also structural but has a DIFFERENT remedy: the sync was asked to skip a matching stage (\`--exact-only\` / exactOnly), so cross-links that stage would have found are absent BY REQUEST. Re-running the sync unchanged returns the same floor — re-run it WITHOUT that flag. Do not report a repo as broken for this reason; nothing failed to read.
 
-SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", scopes the local impact walk and cross-repo symbol paths to files under that prefix; ignored for a normal indexed repo name.`,
+SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", scopes the local impact walk and cross-repo symbol paths to files under that prefix; ignored for a normal indexed repo name.
+
+${HOT_READ_STALENESS_NOTE}`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',

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

@@ -21,13 +21,18 @@ export interface RepoProjectionSource {
  * 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.
+ * This listing/HTTP helper uses the no-ref form: absent when the index is
+ * current; `unknown` is included via `includeUnknown`. 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.
+ *
+ * Hot read tools (`query`/`context`/`impact`/`cypher`) use the ref-carrying
+ * form: they emit `unknown` (and `current`) with `branch?`/`lastCommit`/
+ * `indexedAt`/`measuredAgainst`.
  *
  * 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.

package/dist/server/repo-projection.js

@@ -14,13 +14,18 @@ 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.
+ * This listing/HTTP helper uses the no-ref form: absent when the index is
+ * current; `unknown` is included via `includeUnknown`. 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.
+ *
+ * Hot read tools (`query`/`context`/`impact`/`cypher`) use the ref-carrying
+ * form: they emit `unknown` (and `current`) with `branch?`/`lastCommit`/
+ * `indexedAt`/`measuredAgainst`.
  *
  * 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.

package/package.json

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

package/skills/gitnexus-debugging.md

@@ -42,6 +42,7 @@ diagnosis.
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> Hot-tool `staleness` names which index answered (`branch`/`lastCommit`) and how fresh it is (`status`). Re-analyze only for `behind` or `diverged` — `current` is identity, `unknown` is unmeasurable.
 
 ## Checklist
 

package/skills/gitnexus-exploring.md

@@ -36,6 +36,7 @@ the bound repository and index freshness alongside your explanation.
 ```
 
 > If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> Hot-tool `staleness` names which index answered (`branch`/`lastCommit`) and how fresh it is (`status`). Re-analyze only for `behind` or `diverged` — `current` is identity, `unknown` is unmeasurable.
 
 ## Checklist
 

package/skills/gitnexus-guide.md

@@ -16,6 +16,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 3. **Follow the skill's workflow and checklist**
 
 > If step 1 warns the index is stale, run `node .gitnexus/run.cjs analyze` in the terminal first.
+> On `query` / `context` / `impact` / `cypher`, read `staleness.status` and `staleness.branch`/`lastCommit` before using the answer. Re-analyze only for `behind` or `diverged`.
 
 ## Skills
 
@@ -81,6 +82,54 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false
 
 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.
 
+### Inline staleness signal (`query` / `context` / `impact` / `cypher`)
+
+These four hot read tools attach a non-blocking `staleness` field to every response, in the shape `{ status, branch?, lastCommit, indexedAt, measuredAgainst, commitsBehind?, hint? }`. It answers two different questions at once: **which index answered** and **how fresh it is**. The identity half is why the field is present even when nothing is wrong — an answer computed from a branch-pinned index is otherwise indistinguishable from one computed from the default branch (#3291):
+
+```jsonc
+{ /* …the tool's normal result… */
+  "staleness": {
+    "status": "current",
+    "branch": "feature/checkout-v2",
+    "lastCommit": "4f2a1c9e8b7d6a5c4e3f2a1b0c9d8e7f6a5b4c3d",
+    "indexedAt": "2026-09-15T07:12:00.000Z",
+    "measuredAgainst": "HEAD"
+  }
+}
+```
+
+`status: "current"` here means *this index is at the HEAD of the clone it was built from* — not that it is current with the default branch. `measuredAgainst` names what `commitsBehind` is counted against: the checked-out HEAD of that clone, never the remote. `branch` is the branch the index represents; it is absent for a detached HEAD, a non-git folder, or a legacy index that never recorded one, so read `lastCommit` when you need an identifier that is always present.
+
+When the index is behind that HEAD, the count and hint ride along:
+
+```jsonc
+{ /* …the tool's normal result… */
+  "staleness": {
+    "status": "behind", "commitsBehind": 3, "branch": "main",
+    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
+    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
+    "hint": "⚠️ Index is 3 commits behind HEAD. Run analyze tool to update."
+  }
+}
+```
+
+`commitsBehind` is present only when git counted the gap. When git could not count it but HEAD still resolves to a commit other than the indexed one — usually because the indexed commit is no longer in the clone's history — the index is provably not at HEAD with no countable gap, so no number is reported:
+
+```jsonc
+{ /* …the tool's normal result… */
+  "staleness": {
+    "status": "diverged", "branch": "main",
+    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
+    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
+    "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."
+  }
+}
+```
+
+So: **read `status` before using `commitsBehind`**, and read `branch`/`lastCommit` before assuming which ref the answer describes. `status: "unknown"` means the freshness check could not run at all (a `--skip-git` folder has no history to measure) — the ref is still reported, because which index answered is knowable even when its freshness is not. The field is only ever added to object results — raw-array `cypher` output and error envelopes are returned unchanged. `@group`-targeted calls do not carry it (multi-repo staleness is ill-defined). Re-run `analyze` only for `behind` or `diverged` — those mean the index is not at this clone's HEAD. `unknown` is unmeasurable, not stale; analyze cannot make it `current` unless git history exists.
+
+`list_repos` and the HTTP repo routes are unchanged: they omit `staleness` entirely for a current index and report the ref through their own top-level `branch` / `lastCommit` / `indexedAt` fields.
+
 ### Taint findings (`explain`)
 
 `explain` returns taint findings recorded by `gitnexus analyze --pdg` — intra-procedural `TAINTED` edges plus cross-function `TAINT_PATH` hops where the interprocedural taint phase found a function-level source→sink chain. Each finding includes a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.

package/skills/gitnexus-impact-analysis.md

@@ -53,6 +53,7 @@ Repository: <name> (<path>)   Worktree: <path>   Index: <commit>, <n> behind HEA
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> Hot-tool `staleness` names which index answered (`branch`/`lastCommit`) and how fresh it is (`status`). Re-analyze only for `behind` or `diverged` — `current` is identity, `unknown` is unmeasurable.
 > If `.gitnexus/run.cjs` is missing, replace `node .gitnexus/run.cjs` with `npx gitnexus` in the fallback commands.
 
 ## Checklist

package/skills/gitnexus-refactoring.md

@@ -46,6 +46,7 @@ checkout and reports nothing changed, which reads as a verified refactor.
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> Hot-tool `staleness` names which index answered (`branch`/`lastCommit`) and how fresh it is (`status`). Re-analyze only for `behind` or `diverged` — `current` is identity, `unknown` is unmeasurable.
 
 ## Checklists