gitnexus 1.6.7 → 1.6.8-rc.10

package/dist/server/analyze-worker-ipc.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON-safe projection of `AnalyzeResult` for the analyze-worker → parent IPC
+ * boundary (#2112 boundary audit; #2135).
+ *
+ * The forked analyze worker (`analyze-worker.ts`) reports completion to the
+ * parent over `child_process` IPC, which uses Node's DEFAULT `'json'`
+ * serialization — `api.ts` forks the worker with no `serialization:` option, so
+ * the channel runs `JSON.stringify`/`JSON.parse`, NOT V8 structured clone.
+ *
+ * `AnalyzeResult.pipelineResult` is populated on every successful analysis
+ * (`run-analyze.ts`) and carries `pipelineResult.graph` — the live
+ * `KnowledgeGraph` closure object. Sending the raw result across this channel is
+ * wrong three ways:
+ *   1. Waste — the graph's `nodes`/`relationships` getters force-materialize the
+ *      ENTIRE graph into two arrays, then JSON-stringify them, on every analyze.
+ *      On a large repo (the #2112 scenario) that is a multi-hundred-MB
+ *      stringify+parse whose result is immediately discarded.
+ *   2. Silent corruption — the graph's methods are own function properties;
+ *      `JSON.stringify` drops them with no error, so a `pipelineResult.graph`
+ *      that survived the wire is a data-only husk whose `forEachNode(...)` throws
+ *      "is not a function" far from the cause.
+ *   3. Conditional crash — a BigInt or circular reference anywhere in the
+ *      payload makes `process.send` throw `TypeError` synchronously; the throw is
+ *      caught in the worker and re-sent as `{type:'error'}`, turning a
+ *      SUCCESSFUL analysis (DB already written) into a reported FAILURE. This is
+ *      the #2112 failure family on the server path, and — unlike the parse-worker
+ *      result boundary — it has no clone-safety net.
+ *
+ * The parent (`api.ts`) reads only `result.repoName`; `pipelineResult`'s real
+ * consumers (CLI skill generation) call `runFullAnalysis` in-process and never
+ * cross this fork. So the worker sends an explicit allowlist of the scalar
+ * fields, JSON-safe by construction.
+ */
+import type { AnalyzeResult } from '../core/run-analyze.js';
+/**
+ * The JSON-safe subset of `AnalyzeResult` that crosses the analyze-worker IPC
+ * boundary. A `Pick` allowlist — NOT `Omit<…, 'pipelineResult'>`. With `Pick`
+ * the allowlist IS the type, so the projection is exhaustive by construction:
+ * `projectAnalyzeResultForIpc`'s return literal must name exactly these keys
+ * (omitting one is a compile error), and a new field added to `AnalyzeResult`
+ * is simply absent from the wire until it is *deliberately* added here. `Omit`
+ * couldn't give that guarantee — it kept every other field, including OPTIONAL
+ * ones (e.g. `isPrimaryBranch?`), so an optional non-serializable field could be
+ * advertised by the type yet silently dropped by the runtime allowlist.
+ *
+ * `isPrimaryBranch` is intentionally excluded: the parent (`api.ts`) reads only
+ * `repoName`, and nothing consumes `isPrimaryBranch` across this fork (its CLI
+ * consumer calls `runFullAnalysis` in-process). Add a field here only when a
+ * server-side IPC consumer actually needs it — and only if it is JSON-safe.
+ */
+export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped'>;
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export declare function projectAnalyzeResultForIpc(result: AnalyzeResult): AnalyzeResultIpc;

package/dist/server/analyze-worker-ipc.js

@@ -0,0 +1,16 @@
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export function projectAnalyzeResultForIpc(result) {
+    return {
+        repoName: result.repoName,
+        repoPath: result.repoPath,
+        stats: result.stats,
+        alreadyUpToDate: result.alreadyUpToDate,
+        ftsRepairedOnly: result.ftsRepairedOnly,
+        ftsSkipped: result.ftsSkipped,
+    };
+}

package/dist/server/analyze-worker.js

@@ -11,6 +11,7 @@
  *   Child -> Parent: { type: 'error', message: string }
  */
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 function send(msg) {
     process.send?.(msg);
@@ -48,7 +49,12 @@ process.on('message', async (msg) => {
                 send({ type: 'progress', phase: 'log', percent: -1, message });
             },
         });
-        send({ type: 'complete', result });
+        // Send a JSON-safe projection, NOT the raw result: the IPC channel is
+        // default-JSON serialization and `result.pipelineResult` carries the live
+        // KnowledgeGraph (wasteful to materialize, silently corrupted by JSON, and
+        // a BigInt/circular value would throw and mis-report this success as a
+        // failure). See analyze-worker-ipc.ts.
+        send({ type: 'complete', result: projectAnalyzeResultForIpc(result) });
     }
     catch (err) {
         send({ type: 'error', message: err?.message || 'Analysis failed' });

package/dist/storage/branch-index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Branch-index primitives (#2106).
+ *
+ * Extracted from `repo-manager.ts` to keep the multi-branch slug/placement
+ * logic in one focused module. `getStoragePaths`, `loadMeta`, and the registry
+ * I/O stay in `repo-manager.ts`; this module imports the two it needs at
+ * call-time only (no module-load cross-calls), so the repo-manager ⇄
+ * branch-index import cycle is ESM-safe. `repo-manager.ts` re-exports these so
+ * existing import sites keep working unchanged.
+ */
+import { type RepoMeta } from './repo-manager.js';
+/**
+ * Per-branch index summary nested under a registry entry (#2106). Records
+ * non-primary branches indexed for the same repo path so `list`, `status`, and
+ * `list_repos` can surface them without a second registry entry.
+ */
+export interface BranchSummary {
+    /** Git branch name this sub-index represents. */
+    branch: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RepoMeta['stats'];
+}
+/** Branch-index sub-directory name, relative to the flat `.gitnexus` storage. */
+export declare const BRANCHES_DIR = "branches";
+/**
+ * Filesystem-safe slug for a git branch ref (#2106).
+ *
+ * `sanitizeRepoName` alone is lossy — it maps `/`→`_`, so `feature/x` and
+ * `feature_x` would collide into the same directory. We append a short sha256
+ * of the RAW ref (mirroring `assignRepoId`'s digest fallback) so two distinct
+ * refs can never share a branch directory, while keeping the human prefix
+ * readable.
+ */
+export declare const branchSlug: (rawRef: string) => string;
+/**
+ * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
+ * or a per-branch sub-directory (#2106 KTD2).
+ *
+ * Returns `{}` for the flat/primary placement (byte-identical layout) or
+ * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
+ * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
+ * different checked-out branch then auto-routes to its own sub-directory so it
+ * never overwrites the primary index.
+ *
+ * `label` is the resolved index-branch (explicit `--branch`, else the
+ * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
+ * folder, or CI checkout — always maps to the flat slot.
+ */
+export declare const resolveBranchPlacement: (repoPath: string, label: string | null) => Promise<{
+    branch?: string;
+}>;

package/dist/storage/branch-index.js

@@ -0,0 +1,65 @@
+/**
+ * Branch-index primitives (#2106).
+ *
+ * Extracted from `repo-manager.ts` to keep the multi-branch slug/placement
+ * logic in one focused module. `getStoragePaths`, `loadMeta`, and the registry
+ * I/O stay in `repo-manager.ts`; this module imports the two it needs at
+ * call-time only (no module-load cross-calls), so the repo-manager ⇄
+ * branch-index import cycle is ESM-safe. `repo-manager.ts` re-exports these so
+ * existing import sites keep working unchanged.
+ */
+import { createHash } from 'crypto';
+import { sanitizeRepoName } from './git.js';
+import { getStoragePaths, loadMeta } from './repo-manager.js';
+/** Branch-index sub-directory name, relative to the flat `.gitnexus` storage. */
+export const BRANCHES_DIR = 'branches';
+/**
+ * Filesystem-safe slug for a git branch ref (#2106).
+ *
+ * `sanitizeRepoName` alone is lossy — it maps `/`→`_`, so `feature/x` and
+ * `feature_x` would collide into the same directory. We append a short sha256
+ * of the RAW ref (mirroring `assignRepoId`'s digest fallback) so two distinct
+ * refs can never share a branch directory, while keeping the human prefix
+ * readable.
+ */
+export const branchSlug = (rawRef) => {
+    const safe = sanitizeRepoName(rawRef);
+    const hash = createHash('sha256').update(rawRef).digest('hex').slice(0, 8);
+    return `${safe}-${hash}`;
+};
+/**
+ * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
+ * or a per-branch sub-directory (#2106 KTD2).
+ *
+ * Returns `{}` for the flat/primary placement (byte-identical layout) or
+ * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
+ * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
+ * different checked-out branch then auto-routes to its own sub-directory so it
+ * never overwrites the primary index.
+ *
+ * `label` is the resolved index-branch (explicit `--branch`, else the
+ * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
+ * folder, or CI checkout — always maps to the flat slot.
+ */
+export const resolveBranchPlacement = async (repoPath, label) => {
+    // Detached HEAD / non-git / no label → flat (CI-safe, byte-identical).
+    if (!label)
+        return {};
+    const { storagePath } = getStoragePaths(repoPath);
+    const flatMeta = await loadMeta(storagePath);
+    // The flat slot's owner is authoritative ONLY when it is a non-empty string.
+    // A corrupt/hand-edited meta (empty string, or a non-string value that slips
+    // past JSON typing) must not be trusted to route the real primary into a
+    // sub-directory (#2106 review R5).
+    const owner = flatMeta && typeof flatMeta.branch === 'string' && flatMeta.branch.length > 0
+        ? flatMeta.branch
+        : undefined;
+    // Fresh repo (no flat index) or legacy/unstamped flat index (no recorded
+    // owner): the current label claims/adopts the flat slot. The legacy case
+    // preserves today's overwrite-in-place behavior until the slot is stamped.
+    if (!owner)
+        return {};
+    // Flat slot is owned. Same branch → flat; otherwise this branch gets its own
+    // sub-directory.
+    return owner === label ? {} : { branch: label };
+};

package/dist/storage/git.d.ts

@@ -118,6 +118,17 @@ export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
  * git is unavailable, so callers can fall back to a configured/default branch.
  */
 export declare const getDefaultBranch: (repoPath: string) => string | null;
+/**
+ * Name of the currently checked-out branch, or `null` when HEAD is detached
+ * (CI checkouts, `git checkout <sha>`), the directory is not a git worktree, or
+ * git is unavailable.
+ *
+ * `git rev-parse --abbrev-ref HEAD` prints the literal `HEAD` for a detached
+ * checkout. We map that (and empty output) to `null` so callers fall back to the
+ * flat/default index rather than ever creating a branch literally named
+ * "HEAD" (#2106).
+ */
+export declare const getCurrentBranch: (repoPath: string) => string | null;
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/git.js

@@ -295,6 +295,34 @@ export const getDefaultBranch = (repoPath) => {
         return null;
     }
 };
+/**
+ * Name of the currently checked-out branch, or `null` when HEAD is detached
+ * (CI checkouts, `git checkout <sha>`), the directory is not a git worktree, or
+ * git is unavailable.
+ *
+ * `git rev-parse --abbrev-ref HEAD` prints the literal `HEAD` for a detached
+ * checkout. We map that (and empty output) to `null` so callers fall back to the
+ * flat/default index rather than ever creating a branch literally named
+ * "HEAD" (#2106).
+ */
+export const getCurrentBranch = (repoPath) => {
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd: repoPath,
+            // Suppress stderr -- see getCurrentCommit comment and #1172.
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        })
+            .toString()
+            .trim();
+        if (!branch || branch === 'HEAD')
+            return null;
+        return branch;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/parse-cache.js

@@ -149,6 +149,9 @@ export const slimParseWorkerResultsForCache = (chunkResults) => {
             assignments: [],
             constructorBindings: [],
             parsedFiles: [],
+            // #2112: a clone-safety skip list is per-run telemetry, not graph data —
+            // replay ignores it. Drop it so it doesn't bloat the cached shard.
+            skippedPaths: [],
         });
     }
     return slim;

package/dist/storage/repo-manager.d.ts

@@ -5,6 +5,9 @@
  * Also maintains a global registry at ~/.gitnexus/registry.json
  * so the MCP server can discover indexed repos from any cwd.
  */
+import { branchSlug, resolveBranchPlacement, type BranchSummary } from './branch-index.js';
+export { branchSlug, resolveBranchPlacement };
+export type { BranchSummary };
 /**
  * Normalise a repo path for registry comparison across platforms
  * (#664 review feedback from @evander-wang).
@@ -83,6 +86,23 @@ export interface RepoMeta {
         /** Number of files in the writable set, for diagnostic logs. */
         toWriteCount: number;
     };
+    /**
+     * Name of the git branch this index represents (#2106). Absent for the
+     * default/legacy single-branch case so the flat `meta.json` stays
+     * byte-identical to pre-multi-branch output. When present in the FLAT
+     * `meta.json`, it records which branch "owns" the flat slot (the first
+     * branch indexed); per-branch indexes under `branches/<slug>/` always carry
+     * their own `branch`.
+     */
+    branch?: string;
+    /**
+     * The parse-cache chunk keys this branch's index needs (#2106 R6). The
+     * parse-cache and durable parsedfile store live ONCE at the repo root and are
+     * shared across branches; recording each branch's live chunk keys lets the
+     * prune step union them so re-analyzing one branch doesn't evict another
+     * branch's still-live shards. Additive/optional; absent in legacy metas.
+     */
+    cacheKeys?: string[];
 }
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
@@ -107,15 +127,33 @@ export interface RegistryEntry {
     /** See {@link RepoMeta.remoteUrl}. Mirrored from meta at register time. */
     remoteUrl?: string;
     stats?: RepoMeta['stats'];
+    /**
+     * Branch name owning the flat/primary index (#2106). Mirrors the flat
+     * `meta.branch`. Absent for legacy single-branch entries and non-git repos —
+     * additive and backward compatible.
+     */
+    branch?: string;
+    /**
+     * Non-primary branch indexes for this same path (#2106). Absent when only the
+     * primary branch is indexed, preserving the one-entry-per-path model and the
+     * legacy registry shape.
+     */
+    branches?: BranchSummary[];
 }
 /**
  * Get the .gitnexus storage path for a repository
  */
 export declare const getStoragePath: (repoPath: string) => string;
 /**
- * Get paths to key storage files
+ * Get paths to key storage files.
+ *
+ * `storagePath` is ALWAYS the flat `<repo>/.gitnexus` — content-addressed
+ * caches (`parse-cache/`, `parsedfile-store/`) live there and are shared
+ * across branches (#2106 KTD7). When `branch` is provided, only `lbugPath` and
+ * `metaPath` are scoped under `branches/<slug>/`; the flat call (no `branch`)
+ * returns byte-identical paths to the pre-multi-branch behavior.
  */
-export declare const getStoragePaths: (repoPath: string) => {
+export declare const getStoragePaths: (repoPath: string, branch?: string) => {
     storagePath: string;
     lbugPath: string;
     metaPath: string;
@@ -213,6 +251,14 @@ export interface RegisterRepoOptions {
      * re-run the full pipeline.
      */
     allowDuplicateName?: boolean;
+    /**
+     * Non-primary branch this run indexed (#2106). When set, the branch's
+     * summary is upserted into the entry's `branches[]` and the primary
+     * top-level fields are left untouched. When `undefined`, this is a
+     * primary/flat run that refreshes the top-level fields (and preserves any
+     * existing branch summaries).
+     */
+    branch?: string;
 }
 /**
  * Thrown by {@link registerRepo} when a requested name is already in
@@ -262,6 +308,15 @@ export declare const registerRepo: (repoPath: string, meta: RepoMeta, opts?: Reg
  * Called after `gitnexus clean`.
  */
 export declare const unregisterRepo: (repoPath: string) => Promise<void>;
+/**
+ * Remove a single non-primary branch's summary from a repo's registry entry
+ * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
+ * matching `branches[]` summary was found and removed; `false` otherwise (so
+ * the CLI can report "no such indexed branch" without crashing). The top-level
+ * primary entry is left intact; an empty `branches[]` is dropped to keep the
+ * registry shape legacy-clean.
+ */
+export declare const removeBranchIndex: (repoPath: string, branch: string) => Promise<boolean>;
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,

package/dist/storage/repo-manager.js

@@ -11,6 +11,10 @@ import path from 'path';
 import os from 'os';
 import { getInferredRepoName, resolveRepoIdentityRoot } from './git.js';
 import { logger } from '../core/logger.js';
+import { branchSlug, BRANCHES_DIR, resolveBranchPlacement, } from './branch-index.js';
+// Re-export the #2106 branch primitives (extracted to branch-index.ts, R10) so
+// existing `repo-manager` import sites and tests keep working unchanged.
+export { branchSlug, resolveBranchPlacement };
 /**
  * Normalise a repo path for registry comparison across platforms
  * (#664 review feedback from @evander-wang).
@@ -64,14 +68,21 @@ export const getStoragePath = (repoPath) => {
     return path.join(path.resolve(repoPath), GITNEXUS_DIR);
 };
 /**
- * Get paths to key storage files
+ * Get paths to key storage files.
+ *
+ * `storagePath` is ALWAYS the flat `<repo>/.gitnexus` — content-addressed
+ * caches (`parse-cache/`, `parsedfile-store/`) live there and are shared
+ * across branches (#2106 KTD7). When `branch` is provided, only `lbugPath` and
+ * `metaPath` are scoped under `branches/<slug>/`; the flat call (no `branch`)
+ * returns byte-identical paths to the pre-multi-branch behavior.
  */
-export const getStoragePaths = (repoPath) => {
+export const getStoragePaths = (repoPath, branch) => {
     const storagePath = getStoragePath(repoPath);
+    const baseDir = branch ? path.join(storagePath, BRANCHES_DIR, branchSlug(branch)) : storagePath;
     return {
         storagePath,
-        lbugPath: path.join(storagePath, 'lbug'),
-        metaPath: path.join(storagePath, 'meta.json'),
+        lbugPath: path.join(baseDir, 'lbug'),
+        metaPath: path.join(baseDir, 'meta.json'),
     };
 };
 /**
@@ -310,7 +321,13 @@ export const readRegistry = async () => {
 const writeRegistry = async (entries) => {
     const dir = getGlobalDir();
     await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(getGlobalRegistryPath(), JSON.stringify(entries, null, 2), 'utf-8');
+    // Atomic tmp+rename (mirrors saveMeta): a crash mid-write can never leave a
+    // truncated/half-written registry.json that the next load would treat as
+    // empty and silently drop every registered repo (#2106 R9).
+    const target = getGlobalRegistryPath();
+    const tmp = `${target}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(entries, null, 2), 'utf-8');
+    await fs.rename(tmp, target);
 };
 /**
  * Thrown by {@link registerRepo} when a requested name is already in
@@ -466,22 +483,89 @@ export const registerRepo = async (repoPath, meta, opts) => {
             throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
         }
     }
-    const entry = {
-        name,
-        path: resolved,
-        storagePath,
-        indexedAt: meta.indexedAt,
-        lastCommit: meta.lastCommit,
-        remoteUrl: meta.remoteUrl,
-        stats: meta.stats,
-    };
-    if (existingIdx >= 0) {
-        entries[existingIdx] = entry;
+    // This run's branch summary (non-primary runs only); hoisted so the
+    // re-read-before-write merge below can re-apply it against a fresh snapshot.
+    const summary = opts?.branch
+        ? {
+            branch: opts.branch,
+            indexedAt: meta.indexedAt,
+            lastCommit: meta.lastCommit,
+            stats: meta.stats,
+        }
+        : null;
+    let entry;
+    if (summary) {
+        // Non-primary branch run (#2106): keep the primary's top-level fields and
+        // upsert this branch into branches[]. One entry per path is preserved.
+        // When the registry entry is missing (lost/rebuilt registry.json), rebuild
+        // the primary top-level from the FLAT meta.json rather than this branch's
+        // meta, so `--branch <primary>` can still resolve (#2106 review).
+        const flatMeta = existing ? null : await loadMeta(storagePath);
+        const base = existing ?? {
+            name,
+            path: resolved,
+            storagePath,
+            indexedAt: flatMeta?.indexedAt ?? meta.indexedAt,
+            lastCommit: flatMeta?.lastCommit ?? meta.lastCommit,
+            remoteUrl: flatMeta?.remoteUrl ?? meta.remoteUrl,
+            stats: flatMeta?.stats ?? meta.stats,
+            ...(flatMeta?.branch ? { branch: flatMeta.branch } : {}),
+        };
+        const branches = (base.branches ?? []).filter((b) => b.branch !== summary.branch);
+        branches.push(summary);
+        entry = { ...base, name, branches };
     }
     else {
-        entries.push(entry);
+        // Primary/flat run: refresh top-level fields, preserve any branch summaries
+        // already recorded for this path so a primary re-analyze does not drop them.
+        entry = {
+            name,
+            path: resolved,
+            storagePath,
+            indexedAt: meta.indexedAt,
+            lastCommit: meta.lastCommit,
+            remoteUrl: meta.remoteUrl,
+            stats: meta.stats,
+            ...(meta.branch ? { branch: meta.branch } : {}),
+            ...(existing?.branches ? { branches: existing.branches } : {}),
+        };
+    }
+    // Re-read immediately before writing to narrow the lost-update window (#2106
+    // R9): re-derive THIS run's delta against the FRESHEST snapshot so a
+    // concurrent change to the OTHER axis (a branch upsert vs a primary refresh)
+    // survives instead of being clobbered by a stale entry-time view.
+    const fresh = await readRegistry();
+    const freshIdx = fresh.findIndex((e) => {
+        const a = canonicalizePath(e.path);
+        return process.platform === 'win32'
+            ? a.toLowerCase() === canonicalInput.toLowerCase()
+            : a === canonicalInput;
+    });
+    const freshExisting = freshIdx >= 0 ? fresh[freshIdx] : null;
+    let merged;
+    if (summary) {
+        // Branch run: keep the FRESH top-level + branches, just upsert our summary.
+        const base = freshExisting ?? entry;
+        const branches = (base.branches ?? []).filter((b) => b.branch !== summary.branch);
+        branches.push(summary);
+        merged = { ...base, name, branches };
     }
-    await writeRegistry(entries);
+    else {
+        // Primary run: apply our refreshed top-level, but defer to the FRESH
+        // branches[] (a concurrent branch upsert or `clean --branch` wins).
+        merged = { ...entry };
+        if (freshExisting?.branches)
+            merged.branches = freshExisting.branches;
+        else
+            delete merged.branches;
+    }
+    if (freshIdx >= 0) {
+        fresh[freshIdx] = merged;
+    }
+    else {
+        fresh.push(merged);
+    }
+    await writeRegistry(fresh);
     return name;
 };
 /**
@@ -500,6 +584,36 @@ export const unregisterRepo = async (repoPath) => {
     const filtered = entries.filter((e) => !matches(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
+/**
+ * Remove a single non-primary branch's summary from a repo's registry entry
+ * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
+ * matching `branches[]` summary was found and removed; `false` otherwise (so
+ * the CLI can report "no such indexed branch" without crashing). The top-level
+ * primary entry is left intact; an empty `branches[]` is dropped to keep the
+ * registry shape legacy-clean.
+ */
+export const removeBranchIndex = async (repoPath, branch) => {
+    const resolved = canonicalizePath(repoPath);
+    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    const entries = await readRegistry();
+    const idx = entries.findIndex((e) => matches(canonicalizePath(e.path), resolved));
+    if (idx < 0)
+        return false;
+    const entry = entries[idx];
+    const before = entry.branches?.length ?? 0;
+    if (!entry.branches || before === 0)
+        return false;
+    const remaining = entry.branches.filter((b) => b.branch !== branch);
+    if (remaining.length === before)
+        return false; // branch not recorded
+    if (remaining.length > 0)
+        entry.branches = remaining;
+    else
+        delete entry.branches;
+    entries[idx] = entry;
+    await writeRegistry(entries);
+    return true;
+};
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -91,10 +91,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
   return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }
 
+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners validate hook output, so normal, non-error skip paths must stay
+ * silent unless the operator explicitly asks for diagnostics via GITNEXUS_DEBUG.
+ * See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
   const output = (stderr || '').trim();
   const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
   if (debug && output.length > 0) {
     // Emit the FULL discarded prefix (everything before the marker, or all of
     // it when no marker is present) so suppressed diagnostics — LadybugDB lock
@@ -258,8 +268,14 @@ function buildAfterToolContext(input) {
     if (/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) {
       const hint = buildStaleIndexHint(gitNexusDir, cwd);
       if (hint) {
-        process.stderr.write(`${hint}\n`);
+        // The hint always reaches the agent via additionalContext (parts). Mirror
+        // it to stderr (for terminal users) only under GITNEXUS_DEBUG, so strict
+        // hook runners see no unexpected output on this normal path (#1913). The
+        // claude hook never mirrored this to stderr — this aligns the two adapters.
         parts.push(hint);
+        if (isDebugEnabled()) {
+          process.stderr.write(`${hint}\n`);
+        }
       }
     }
   }
@@ -269,7 +285,11 @@ function buildAfterToolContext(input) {
 
 function runAugment(gitNexusDir, cwd, pattern) {
   if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    // Normal skip path: the MCP server owns the DB. Stay silent for strict
+    // hook runners (issue #1913); surface the reason only under GITNEXUS_DEBUG.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    }
     return '';
   }
   const release = acquireHookSlot(gitNexusDir);
@@ -338,7 +358,7 @@ function main() {
     const handler = handlers[input.hook_event_name || ''];
     if (handler) handler(input);
   } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
       console.error('GitNexus antigravity hook error:', (err.message || '').slice(0, 200));
     }
   }