gitnexus 1.6.12-rc.11 → 1.6.12-rc.13

package/dist/cli/analyze-config.d.ts

@@ -41,8 +41,8 @@ export declare class GitNexusRcError extends Error {
 }
 /**
  * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
- * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
- * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ * trimmed name or throws {@link GitNexusRcError}. Rules live in
+ * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
  */
 export declare function validateBranchName(value: string, source: string): string;
 /**

package/dist/cli/analyze-config.js

@@ -30,11 +30,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readRepoControlFile } from '../config/repo-control-file.js';
+import { InvalidBranchError, validateBranchName as validateBranchNameCore, } from '../core/git-ref.js';
 export const GITNEXUS_RC_FILENAME = '.gitnexusrc';
 /** Final fallback when no branch is configured or detectable. */
 export const DEFAULT_BRANCH_FALLBACK = 'main';
-/** Git refs longer than this are almost certainly a mistake / injection attempt. */
-const BRANCH_MAX_LENGTH = 255;
 /**
  * Thrown for any `.gitnexusrc` problem (missing-file is NOT an error — it
  * returns `undefined`). The message is user-facing and names the file so the
@@ -126,41 +125,19 @@ const assertNoHiddenChars = (value, source) => {
 };
 /**
  * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
- * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
- * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ * trimmed name or throws {@link GitNexusRcError}. Rules live in
+ * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
  */
 export function validateBranchName(value, source) {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        throw new GitNexusRcError(`${source}: branch name must not be empty.`);
-    }
-    if (trimmed.length > BRANCH_MAX_LENGTH) {
-        throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
-    }
-    assertNoHiddenChars(trimmed, source);
-    if (/\s/.test(trimmed)) {
-        throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
-    }
-    // git ref-name rules (subset): reject characters git itself forbids in refs.
-    if (/[~^:?*[\\]/.test(trimmed)) {
-        throw new GitNexusRcError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
-    }
-    if (trimmed.startsWith('-')) {
-        throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
-    }
-    if (trimmed.includes('..')) {
-        throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
+    try {
+        return validateBranchNameCore(value, source);
     }
-    // Git permits a backtick in a ref, but the branch is embedded inside a
-    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
-    // example, where a backtick would close the span early and let the rest of
-    // the template render as instruction text. Reject it at this single
-    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
-    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
-    if (trimmed.includes('`')) {
-        throw new GitNexusRcError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    catch (err) {
+        if (err instanceof InvalidBranchError) {
+            throw new GitNexusRcError(err.message);
+        }
+        throw err;
     }
-    return trimmed;
 }
 /**
  * Best-effort validation for an auto-detected branch (from git). Never throws —

package/dist/core/auto-sync/starter.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { acquireFileLock, FileLockBusyError } from '../../storage/file-lock.js';
 import { getGlobalDir } from '../../storage/repo-manager.js';
-import { isProcessAlive, readProcessStartTime } from '../../utils/process-identity.js';
+import { isProcessAlive, readProcessStartTimeCached } from '../../utils/process-identity.js';
 import { loadAutoSyncConfig } from './config.js';
 import { runAutoSyncOnce } from './runner.js';
 import { getAutoSyncMutexPath, getAutoSyncWatchDir } from './state.js';
@@ -488,7 +488,7 @@ function resolveWatchDeps(deps = {}) {
                     return undefined;
                 }
             }),
-        readProcessStartTime: deps.readProcessStartTime ?? readProcessStartTime,
+        readProcessStartTime: deps.readProcessStartTime ?? readProcessStartTimeCached,
         sleep: deps.sleep ??
             ((ms) => new Promise((resolve) => {
                 setTimeout(resolve, ms);

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

@@ -0,0 +1,22 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export declare class InvalidBranchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export declare function validateBranchName(value: string, source: string): string;

package/dist/core/git-ref.js

@@ -0,0 +1,114 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export class InvalidBranchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidBranchError';
+    }
+}
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name and would otherwise
+ * let a committed config or HTTP body smuggle invisible controls into
+ * generated AGENTS.md / CLAUDE.md content.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new InvalidBranchError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new InvalidBranchError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new InvalidBranchError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "-".`);
+    }
+    // Force-refspec prefix (`git fetch origin +main` / `+refs/heads/main:…`).
+    // Rejected here so neither the CLI nor HTTP can pass a force-update refspec
+    // through as a "branch" (#3199 review, defense in depth).
+    if (trimmed.startsWith('+')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "+".`);
+    }
+    // The symbolic ref HEAD (case-sensitive). A repo can have a branch named
+    // `head`; git itself treats only `HEAD` as the current-commit alias.
+    if (trimmed === 'HEAD') {
+        throw new InvalidBranchError(`${source}: branch name must not be "HEAD".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "..".`);
+    }
+    // The remaining `git check-ref-format` rules. Without these the validator
+    // accepted refs git itself refuses (`feature.lock`, `/feature`, `feature/`,
+    // `feature//next`, `@`, `.hidden`), so the failure surfaced later from the
+    // git subprocess instead of here. No real branch can violate them — git
+    // could not have created one — so nothing that works today starts failing.
+    if (trimmed.endsWith('.lock') || trimmed.split('/').some((part) => part.endsWith('.lock'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with ".lock".`);
+    }
+    if (trimmed.startsWith('/') || trimmed.endsWith('/')) {
+        throw new InvalidBranchError(`${source}: branch name must not start or end with "/".`);
+    }
+    if (trimmed.includes('//')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain consecutive slashes.`);
+    }
+    if (trimmed === '@') {
+        throw new InvalidBranchError(`${source}: branch name must not be the single character "@".`);
+    }
+    if (trimmed.includes('@{')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "@{".`);
+    }
+    if (trimmed.endsWith('.') || trimmed.split('/').some((part) => part.startsWith('.'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with "." or have a path component starting with ".".`);
+    }
+    // Git permits a backtick in a ref, but the branch is embedded inside a
+    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
+    // example, where a backtick would close the span early and let the rest of
+    // the template render as instruction text. Reject it at this single
+    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
+    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    }
+    return trimmed;
+}

package/dist/server/analyze-job.d.ts

@@ -53,6 +53,13 @@ export interface AnalyzeJob {
     repoUrl?: string;
     repoPath?: string;
     repoName?: string;
+    /**
+     * Index-branch selector this job was started with, part of the job's dedup
+     * identity. A repo is not "the same repo" for reuse purposes when a different
+     * branch was asked for — reusing across branches would hand the caller a 202
+     * for a job indexing something else.
+     */
+    branch?: string;
     progress: AnalyzeJobProgress;
     error?: string;
     /** Set only when a terminal `failed` job still persisted usable work. */
@@ -70,10 +77,21 @@ export declare class JobManager {
     private emitter;
     private cleanupTimer;
     constructor();
-    /** Create a new job, or return existing active job for the same repo. */
+    /**
+     * Create a new job, or return the existing active job for the same repo AND
+     * the same branch.
+     *
+     * Branch is part of the identity deliberately. Deduping on repo alone would
+     * return the in-flight job for branch A to a caller that asked for branch B,
+     * and that caller would read the resulting 202/`complete` as "B is indexed"
+     * — the same silent wrong-branch outcome that made `branch` worth honoring in
+     * the first place. Falling through instead lets the single-slot guard below
+     * reject the request outright, which is a truthful answer.
+     */
     createJob(params: {
         repoUrl?: string;
         repoPath?: string;
+        branch?: string;
     }): AnalyzeJob;
     getJob(id: string): AnalyzeJob | undefined;
     /** Return a snapshot of all tracked jobs for inspection. */

package/dist/server/analyze-job.js

@@ -34,14 +34,24 @@ export class JobManager {
     constructor() {
         this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
     }
-    /** Create a new job, or return existing active job for the same repo. */
+    /**
+     * Create a new job, or return the existing active job for the same repo AND
+     * the same branch.
+     *
+     * Branch is part of the identity deliberately. Deduping on repo alone would
+     * return the in-flight job for branch A to a caller that asked for branch B,
+     * and that caller would read the resulting 202/`complete` as "B is indexed"
+     * — the same silent wrong-branch outcome that made `branch` worth honoring in
+     * the first place. Falling through instead lets the single-slot guard below
+     * reject the request outright, which is a truthful answer.
+     */
     createJob(params) {
-        // Dedup: return existing active job for the same repo (by URL or path)
+        // Dedup: return existing active job for the same repo (by URL or path) and branch
         for (const job of this.jobs.values()) {
             if (!this.isTerminal(job.status)) {
                 const isSameRepo = (params.repoUrl && job.repoUrl === params.repoUrl) ||
                     (params.repoPath && job.repoPath === params.repoPath);
-                if (isSameRepo) {
+                if (isSameRepo && job.branch === params.branch) {
                     return job;
                 }
             }
@@ -57,6 +67,7 @@ export class JobManager {
             status: 'queued',
             repoUrl: params.repoUrl,
             repoPath: params.repoPath,
+            branch: params.branch,
             progress: { phase: 'queued', percent: 0, message: 'Waiting to start...' },
             startedAt: Date.now(),
             retryCount: 0,

package/dist/server/analyze-launch.d.ts

@@ -31,6 +31,20 @@ export interface LaunchOptions {
     springActuatorPath?: string;
     asyncApiSpecPath?: string;
     registryName?: string;
+    /**
+     * Index-branch selector, forwarded to `AnalyzeOptions.branch`.
+     *
+     * Setting it does not by itself mean a `branches/<slug>/` sub-directory:
+     * `resolveBranchPlacement` (storage/branch-index.ts) keeps the run on the flat
+     * slot when that slot has no recorded owner, or when its owner already IS this
+     * label. Only a label that differs from the flat slot's owner gets its own
+     * sub-directory.
+     *
+     * The caller is responsible for having the branch checked out —
+     * `resolveWriteTarget` in core refuses a label that disagrees with the working
+     * tree, which is what keeps one branch's content out of another's slot (#2106).
+     */
+    branch?: string;
 }
 export declare function createLaunchAnalysisWorker(deps: LaunchDeps): (job: {
     id: string;

package/dist/server/analyze-launch.js

@@ -15,6 +15,7 @@ import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
 import { canonicalizePath, getStoragePath, INDEX_METADATA_FILE, listRegisteredRepos, registryPathEquals, } from '../storage/repo-manager.js';
+import { BRANCHES_DIR, branchSlug } from '../storage/branch-index.js';
 import { logger } from '../core/logger.js';
 import { autoHeapCapMb } from '../core/ingestion/utils/effective-ram.js';
 import { isTerminalJobStatus } from './analyze-job.js';
@@ -32,17 +33,6 @@ const MAX_WORKER_RETRIES = 2;
  */
 const FINALIZE_SETTLE_TIMEOUT_MS = 60_000;
 const FINALIZE_SETTLE_POLL_MS = 200;
-/**
- * Resolve once the analyzed repo's index is settled at `storagePath`: the
- * LadybugDB file and metadata both exist AND were (re)written by THIS job
- * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
- * the previous index in place while it works), and no transient WAL/shadow/
- * checkpoint sidecars remain (the worker's native close has finished).
- *
- * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
- * than failing a job whose analysis genuinely succeeded — e.g. a no-op
- * non-force analyze legitimately rewrites nothing.
- */
 /**
  * Look up the analyzed repo's registered storage path. The request's
  * user-provided path is used only as a comparison key; the filesystem probes
@@ -56,7 +46,36 @@ const registeredStoragePath = async (targetPath) => {
     const entry = entries.find((e) => registryPathEquals(canonicalizePath(e.path), target));
     return entry?.storagePath ?? null;
 };
-const waitForSettledIndex = async (targetPath, jobStartMs) => {
+/**
+ * Resolve the directory this run's index actually landed in.
+ *
+ * `registerRepo` always records the FLAT `.gitnexus` as `entry.storagePath`,
+ * but a pinned `--branch` run whose label differs from the flat slot's owner
+ * writes `lbug`/`gitnexus.json` under `branches/<slug>/` instead. Probing the
+ * flat path for such a run watches files it never rewrote, so the gate below
+ * would spin to its timeout on a perfectly successful analysis (#3199 review).
+ *
+ * `isPrimaryBranch` is the worker's own report of `!placement.branch`, so this
+ * follows the placement core actually chose rather than recomputing it here
+ * (the flat slot's recorded owner can be adopted mid-run, which would make a
+ * recomputation race the thing it is trying to observe).
+ */
+const settleDirFor = (registryStoragePath, branch, isPrimaryBranch) => branch && isPrimaryBranch === false
+    ? path.join(registryStoragePath, BRANCHES_DIR, branchSlug(branch))
+    : registryStoragePath;
+/**
+ * Resolve once the analyzed repo's index is settled at `storagePath`: the
+ * LadybugDB file and metadata both exist AND were (re)written by THIS job
+ * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
+ * the previous index in place while it works), and no transient WAL/shadow/
+ * checkpoint sidecars remain (the worker's native close has finished).
+ *
+ * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
+ * than failing a job whose analysis genuinely succeeded. The `alreadyUpToDate`
+ * fast path never rewrites `lbug` (see `run-analyze.ts`) and skips this wait
+ * at the `complete` handler so it does not hold the analyze slot for 60s.
+ */
+const waitForSettledIndex = async (targetPath, jobStartMs, branch, isPrimaryBranch) => {
     const settled = (storagePath) => {
         try {
             const lbugStat = statSync(path.join(storagePath, 'lbug'));
@@ -74,7 +93,7 @@ const waitForSettledIndex = async (targetPath, jobStartMs) => {
         // Re-resolved each round: the worker registers the repo as part of the
         // finalization this gate is waiting out.
         const storagePath = await registeredStoragePath(targetPath);
-        if (storagePath && settled(storagePath))
+        if (storagePath && settled(settleDirFor(storagePath, branch, isPrimaryBranch)))
             return;
         if (Date.now() > deadline) {
             logger.warn({ targetPath }, 'analyze finalization not visible after timeout; completing job anyway');
@@ -121,6 +140,13 @@ export function createLaunchAnalysisWorker(deps) {
             });
             // Capture stderr for crash diagnostics
             let stderrChunks = '';
+            // A terminal IPC message (`complete`/`error`) means the worker finished
+            // and is now winding down — it calls process.exit(0) ~500ms later. The
+            // job is deliberately still non-terminal at that point because the
+            // finalization gate is running, so without this flag the exit handler
+            // below reads that clean exit as a crash and retries a SUCCESSFUL
+            // analysis, three times, before failing it (#3199 review).
+            let terminalIpcSeen = false;
             child.stderr?.on('data', (chunk) => {
                 stderrChunks += chunk.toString();
                 if (stderrChunks.length > 4096)
@@ -134,6 +160,8 @@ export function createLaunchAnalysisWorker(deps) {
                 const current = jobManager.getJob(job.id);
                 if (!current || isTerminalJobStatus(current.status))
                     return;
+                if (msg.type === 'complete' || msg.type === 'error')
+                    terminalIpcSeen = true;
                 if (msg.type === 'progress') {
                     jobManager.updateJob(job.id, {
                         status: 'analyzing',
@@ -151,7 +179,16 @@ export function createLaunchAnalysisWorker(deps) {
                     // below true in practice: the repo is actually queryable when the
                     // client receives the SSE complete event, and an index this run knows
                     // to be incomplete is never published at all.
-                    waitForSettledIndex(targetPath, jobStartMs)
+                    //
+                    // alreadyUpToDate never opens LadybugDB and never rewrites `lbug`
+                    // (run-analyze.ts early-return; CLI notes the same). The mtime gate
+                    // would spin the full 60s and hold the single global analyze slot.
+                    // ftsRepairedOnly DOES rewrite `lbug` (initLbug + createSearchFTSIndexes)
+                    // so it still waits.
+                    const settle = msg.result.alreadyUpToDate
+                        ? Promise.resolve()
+                        : waitForSettledIndex(targetPath, jobStartMs, opts.branch, msg.result.isPrimaryBranch);
+                    settle
                         .then(() => closeDbHandle())
                         .catch(() => { }) // best-effort: eviction failure must not fail the job
                         .then(() => {
@@ -243,6 +280,13 @@ export function createLaunchAnalysisWorker(deps) {
                 const j = jobManager.getJob(job.id);
                 if (!j || isTerminalJobStatus(j.status))
                     return;
+                // The worker already reported a terminal outcome; this exit is it
+                // winding down, not dying. The job is still non-terminal only because
+                // the finalization gate above has not resolved yet, and that gate owns
+                // the outcome — retrying here would fork a second worker over a
+                // finished, successful analysis.
+                if (terminalIpcSeen)
+                    return;
                 // Worker crashed — attempt retry if under the limit
                 if (j.retryCount < MAX_WORKER_RETRIES) {
                     j.retryCount++;
@@ -283,6 +327,7 @@ export function createLaunchAnalysisWorker(deps) {
                     ...(opts.springActuatorPath ? { springActuatorPath: opts.springActuatorPath } : {}),
                     ...(opts.asyncApiSpecPath ? { asyncApiSpecPath: opts.asyncApiSpecPath } : {}),
                     ...(opts.registryName ? { registryName: opts.registryName } : {}),
+                    ...(opts.branch ? { branch: opts.branch } : {}),
                 },
             });
         };

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

@@ -43,12 +43,13 @@ import type { AnalyzeResult } from '../core/run-analyze.js';
  * 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.
+ * `isPrimaryBranch` IS on the wire, under exactly the rule this comment used to
+ * cite for excluding it: a server-side consumer now needs it. `analyze-launch.ts`
+ * settles the index the run actually wrote, and only the worker knows whether
+ * core chose the flat slot or a `branches/<slug>/` sub-slot. It is a boolean, so
+ * it is JSON-safe by construction.
  */
-export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped' | 'graphWriteCollapsed'>;
+export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped' | 'graphWriteCollapsed' | 'isPrimaryBranch'>;
 /**
  * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
  * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not

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

@@ -16,5 +16,9 @@ export function projectAnalyzeResultForIpc(result) {
         // outcome the CLI does; without it the worker reports a clean `complete`
         // for a run whose edges are mostly missing.
         graphWriteCollapsed: result.graphWriteCollapsed,
+        // Tells the parent which slot this run wrote — the flat `.gitnexus` or a
+        // `branches/<slug>/` sub-slot — so its finalization gate watches the files
+        // this job actually rewrote (#3199 review).
+        isPrimaryBranch: result.isPrimaryBranch,
     };
 }

package/dist/server/api.js

@@ -29,8 +29,12 @@ import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } f
 import { assertString, BadRequestError, createRouteLimiter } from './validation.js';
 import { parseGrepQuery, GREP_TIME_BUDGET_MS } from './grep-params.js';
 import { runGrepScanInWorker } from './grep-scan.js';
-import { extractWebRepoName, getCloneDir, cloneOrPull, warnIfInsecureAzureConfig, GITHUB_TOKEN_HOSTS, } from './git-clone.js';
+import { analyzeCloneOptions, extractWebRepoName, getCloneDir, cloneOrPull, warnIfInsecureAzureConfig, GITHUB_TOKEN_HOSTS, } from './git-clone.js';
 import { createAnalyzeUploadHandler } from './analyze-upload.js';
+// Shared with the CLI's `--branch` (via the analyze-config wrapper) so both
+// entry points accept the same refs. Imported from core — not cli/ — so
+// createServer does not close a cycle with cli/serve.ts.
+import { InvalidBranchError, validateBranchName } from '../core/git-ref.js';
 import { assertServeAuthForPublicOrigin, createPublicOriginMatcher, createWriteOriginGuard, logOriginPolicy, PUBLIC_ORIGIN_ENV, resolveTrustProxy, TRUST_PROXY_ENV, warnIfRateLimitKeysCollapse, } from './middleware.js';
 import { createLaunchAnalysisWorker } from './analyze-launch.js';
 import { UPLOAD_ROOT } from './upload-paths.js';
@@ -1264,7 +1268,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     // POST /api/analyze — start a new analysis job
     app.post('/api/analyze', createRouteLimiter({ limit: 10 }), requireTrustedOrigin, async (req, res) => {
         try {
-            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, springActuatorPath, asyncApiSpecPath, token: repoToken, } = req.body;
+            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, springActuatorPath, asyncApiSpecPath, token: repoToken, branch: repoBranch, } = req.body;
             // Input type validation
             if (repoUrl !== undefined && typeof repoUrl !== 'string') {
                 res.status(400).json({ error: '"url" must be a string' });
@@ -1288,6 +1292,27 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
                 return;
             }
+            // Branch: optional index-branch selector, validated with the same rules
+            // as the CLI's `--branch` so both entry points accept the same refs.
+            // Rejecting here (rather than letting the clone fail) keeps a malformed
+            // ref from ever reaching `git`.
+            if (repoBranch !== undefined && typeof repoBranch !== 'string') {
+                res.status(400).json({ error: '"branch" must be a string' });
+                return;
+            }
+            let analyzeBranch;
+            if (repoBranch !== undefined) {
+                try {
+                    analyzeBranch = validateBranchName(repoBranch, '"branch"');
+                }
+                catch (err) {
+                    if (err instanceof InvalidBranchError) {
+                        res.status(400).json({ error: err.message });
+                        return;
+                    }
+                    throw err;
+                }
+            }
             // Token: optional, restricted charset to prevent header smuggling
             // (CRLF), bound length, and bound to github.com (see validateAnalyzeToken).
             const tokenError = validateAnalyzeToken(repoToken, repoUrl);
@@ -1311,7 +1336,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: '"path" must be an absolute path' });
                 return;
             }
-            const job = jobManager.createJob({ repoUrl, repoPath: repoLocalPath });
+            const job = jobManager.createJob({
+                repoUrl,
+                repoPath: repoLocalPath,
+                branch: analyzeBranch,
+            });
             // If job was already running (dedup), just return its id. The token is
             // not part of the dedup identity and is never stored on the job, so a
             // token on THIS request had no effect — the existing job already
@@ -1337,17 +1366,21 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     // Clone if URL provided
                     if (repoUrl && !repoLocalPath) {
                         const repoName = extractWebRepoName(repoUrl);
-                        targetPath = getCloneDir(repoName);
+                        // Branch-pinned runs get their own clone dir, so they never share
+                        // a working tree with the unpinned one (see getCloneDir).
+                        targetPath = getCloneDir(repoName, analyzeBranch);
                         jobManager.updateJob(job.id, {
                             status: 'cloning',
-                            repoName,
+                            // url+branch: same value as registryName (dir basename), not
+                            // the extractWebRepoName stem used only as getCloneDir's first arg.
+                            repoName: analyzeBranch ? path.basename(targetPath) : repoName,
                             progress: { phase: 'cloning', percent: 0, message: `Cloning ${repoUrl}...` },
                         });
                         await cloneOrPull(repoUrl, targetPath, (progress) => {
                             jobManager.updateJob(job.id, {
                                 progress: { phase: progress.phase, percent: 5, message: progress.message },
                             });
-                        }, repoToken ? { token: repoToken } : undefined);
+                        }, analyzeCloneOptions(repoToken, analyzeBranch));
                     }
                     if (!targetPath) {
                         throw new Error('No target path resolved');
@@ -1358,6 +1391,20 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         dropEmbeddings,
                         springActuatorPath,
                         asyncApiSpecPath,
+                        branch: analyzeBranch,
+                        // Both clone dirs share an `origin`, so the name `registerRepo`
+                        // infers from the remote would be identical and the second one
+                        // would fail with RegistryNameCollisionError. Register the pinned
+                        // clone under its directory name instead: unique per branch, and
+                        // it re-derives through getCloneDir for DELETE /api/repo.
+                        //
+                        // Gated on the SAME condition as the clone above: when a caller
+                        // supplies both `url` and `path` nothing is cloned, and renaming
+                        // the operator's own local repo after its directory would be a
+                        // surprise unrelated to branch pinning.
+                        ...(analyzeBranch && repoUrl && !repoLocalPath
+                            ? { registryName: path.basename(targetPath) }
+                            : {}),
                     });
                 }
                 catch (err) {

package/dist/server/git-clone.d.ts

@@ -25,12 +25,25 @@ export declare function extractRepoName(url: string): string;
  * `extractRepoName()` strict for internal/security-sensitive callers.
  */
 export declare function extractWebRepoName(url: string): string;
-/** Get the clone target directory for a repo name. */
-export declare function getCloneDir(repoName: string): string;
+/** Get the clone target directory for a repo name, optionally pinned to a branch. */
+export declare function getCloneDir(repoName: string, branch?: string): string;
 export interface CloneProgress {
     phase: 'cloning' | 'pulling';
     message: string;
 }
+/**
+ * Build the `cloneOrPull` options for an `/api/analyze` request.
+ *
+ * Extracted from the route so the token/branch combination is unit-testable.
+ * Inline, the branch-only case was the one nothing asserted: every existing
+ * test still passed if `branch` were dropped whenever no token was supplied —
+ * i.e. silently cloning the default branch for every public URL, which is the
+ * exact behavior #3198 is about (#3199 review).
+ *
+ * Returns `undefined` rather than `{}` when neither is set, because that is
+ * what `cloneOrPull` treats as "no options" at its own call sites.
+ */
+export declare function analyzeCloneOptions(token?: string, branch?: string): Pick<CloneOrPullOptions, 'token' | 'branch'> | undefined;
 export interface CloneOrPullOptions {
     token?: string;
     allowedCloneRoot?: string;
@@ -119,9 +132,29 @@ export declare function getRemoteOriginUrl(cwd: string, timeoutMs?: number): Pro
 export declare function assertRemoteMatchesRequestedUrl(targetDir: string, requestedUrl: string, timeoutMs?: number): Promise<void>;
 /**
  * Clone or pull a git repository.
- * If targetDir doesn't exist: git clone --depth 1
- * If targetDir exists with .git: git pull --ff-only (after verifying the
- * existing clone's remote.origin matches the requested URL).
+ *
+ * If targetDir doesn't exist: git clone --depth 1, adding `--branch <branch>`
+ * when one is requested.
+ *
+ * If targetDir exists with .git, its remote.origin is verified against the
+ * requested URL first, and then the branch decides the update:
+ *   - no `options.branch`: git pull --ff-only, which updates the current
+ *     branch in place via its configured upstream. Nothing moves, so no
+ *     dirty-tree check applies.
+ *   - a `options.branch` that is ALREADY the current named branch: restore
+ *     GitNexus overlays, then fetch via
+ *     `+refs/heads/<branch>:refs/remotes/origin/<branch>` and
+ *     `checkout -B <branch> origin/<branch>` (shallow clones cannot
+ *     `merge --ff-only` across a 2+ commit move). Never a raw
+ *     `origin <branch>` pull refspec. No porcelain refuse.
+ *   - a detached HEAD whose SHA already matches the requested ref (tag /
+ *     SHA pin): restore overlays only. Do not fetch/merge — a same-named
+ *     branch could otherwise fast-forward the pin past the tag.
+ *   - a `options.branch` that DIFFERS from the current pin: fetch that ref,
+ *     then `checkout -B <branch> origin/<branch>` — so the requested branch,
+ *     not the one already checked out, is what ends up in the working tree.
+ *     This is the switching case, and it refuses a dirty tree unless
+ *     `overwriteLocalChanges` is set.
  *
  * Security:
  *   - targetDir must resolve inside CLONE_ROOT (~/.gitnexus/repos/). The

package/dist/server/git-clone.js

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

package/dist/storage/file-lock.js

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

package/dist/utils/process-identity.d.ts

@@ -1,2 +1,15 @@
 export declare function isProcessAlive(pid: number): boolean;
 export declare function readProcessStartTime(pid: number): string | undefined;
+/**
+ * `readProcessStartTime`, except this process's own start time is probed once.
+ * It cannot change while we are running, and every `acquireFileLock` — plus
+ * each retry attempt and each stale-lock reclaim guard — stamps the owner file
+ * with it. On Windows that probe is a `powershell.exe` spawn and a WMI query,
+ * so a process taking several locks pays it several times for one constant.
+ *
+ * A foreign pid is never cached: that process can exit and its pid can be
+ * reused, which is the very thing the stamp exists to detect. A failed probe
+ * is not cached either — one transient failure would otherwise leave the
+ * process unable to take a lock for its whole lifetime.
+ */
+export declare function readProcessStartTimeCached(pid: number): string | undefined;

package/dist/utils/process-identity.js

@@ -33,3 +33,21 @@ export function readProcessStartTime(pid) {
         return undefined;
     }
 }
+let ownStartTime;
+/**
+ * `readProcessStartTime`, except this process's own start time is probed once.
+ * It cannot change while we are running, and every `acquireFileLock` — plus
+ * each retry attempt and each stale-lock reclaim guard — stamps the owner file
+ * with it. On Windows that probe is a `powershell.exe` spawn and a WMI query,
+ * so a process taking several locks pays it several times for one constant.
+ *
+ * A foreign pid is never cached: that process can exit and its pid can be
+ * reused, which is the very thing the stamp exists to detect. A failed probe
+ * is not cached either — one transient failure would otherwise leave the
+ * process unable to take a lock for its whole lifetime.
+ */
+export function readProcessStartTimeCached(pid) {
+    if (pid !== process.pid)
+        return readProcessStartTime(pid);
+    return (ownStartTime ??= readProcessStartTime(pid));
+}

package/package.json

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