gitnexus 1.6.12-rc.38 → 1.6.12-rc.39

package/dist/cli/analyze-watch.js

@@ -4,6 +4,7 @@ import fs from 'node:fs/promises';
 import { watch } from 'chokidar';
 import { createWatchIgnorePredicate } from '../config/ignore-service.js';
 import { analyzeFailureMayHaveMutatedLiveIndex, runFullAnalysis, } from '../core/run-analyze.js';
+import { isIndexLockGuardTimeout } from '../storage/index-lock.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { GITNEXUS_DIR } from '../storage/repo-meta.js';
 import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
@@ -173,6 +174,9 @@ class WatchControlReloadError extends Error {
     }
 }
 export function shouldStopAfterWatchRefreshFailure(error, paths) {
+    if (isIndexLockGuardTimeout(error)) {
+        return true;
+    }
     return (paths.length > 0 &&
         !(error instanceof WatchControlReloadError) &&
         analyzeFailureMayHaveMutatedLiveIndex(error));
@@ -397,8 +401,13 @@ export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap,
                     const detail = paths.length > 0 ? ` (${paths.length} queued path(s))` : '';
                     if (shouldStopAfterWatchRefreshFailure(error, paths)) {
                         fatalRefreshError = error;
+                        const guardTimeout = isIndexLockGuardTimeout(error);
                         cliError(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
-                            'Watch mode is stopping because the live index may have been updated in place.');
+                            (guardTimeout
+                                ? 'Watch mode is stopping because the acquisition guard needs quiesced recovery; see RUNBOOK.md.'
+                                : 'Watch mode is stopping because the live index may have been updated in place.'), guardTimeout
+                            ? { recoveryHint: 'index-lock-guard-recovery', guardPath: error.guardPath }
+                            : undefined);
                         stopWatching();
                         return;
                     }

package/dist/cli/analyze.js

@@ -20,7 +20,7 @@ import { causeChain } from '../lib/utils.js';
 import { getOsPageSize, isLbugCheckpointIoError, isLbugCheckpointBusyError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch, selfCommitContextFiles, snapshotSelfCommitSafety, } from '../storage/git.js';
-import { IndexLockTimeoutError } from '../storage/index-lock.js';
+import { IndexLockTimeoutError, isIndexLockGuardTimeout } from '../storage/index-lock.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getRuntimeFingerprint } from '../core/platform/capabilities.js';
@@ -1377,6 +1377,14 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         // refreshed by the holder — this is a clean, expected condition, not a
         // crash, so render the message without a stack trace.
         if (err instanceof IndexLockTimeoutError) {
+            if (isIndexLockGuardTimeout(err)) {
+                cliError(err.message, {
+                    recoveryHint: 'index-lock-guard-recovery',
+                    guardPath: err.guardPath,
+                });
+                process.exitCode = 1;
+                return;
+            }
             cliError(`  Another gitnexus analyze (pid ${err.holder.pid} on ${err.holder.hostname}) is ` +
                 `already refreshing this index and did not finish within the wait window.\n` +
                 `  The on-disk index is being updated by that run. Retry later, or raise\n` +

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid' | 'index-lock-timeout' | 'undeclared-relation-pair';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid' | 'index-lock-timeout' | 'index-lock-guard-recovery' | 'undeclared-relation-pair';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/embeddings-sync.js

@@ -2,7 +2,7 @@ import { lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { cliInfo } from './cli-message.js';
 import { getGitRoot } from '../storage/git.js';
-import { acquireIndexLock } from '../storage/index-lock.js';
+import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
 import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js';
 import { closeLbug, executeQuery, executeWithReusedStatement, fetchExistingEmbeddingHashes, initLbug, } from '../core/lbug/lbug-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
@@ -19,6 +19,7 @@ export const embeddingsSyncCommand = async (inputPath) => {
     const metaDir = path.dirname(metaPath);
     const lock = await acquireIndexLock(metaDir);
     try {
+        requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`);
         const meta = await loadMeta(metaDir);
         if (!meta)
             throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);

package/dist/core/group/group-lock.js

@@ -30,7 +30,9 @@
  * distinct ways it can fail to be protected; all three throw
  * {@link GroupSyncLockError}:
  *
- *   1. TIMEOUT — the holder is still alive when the ceiling elapses.
+ *   1. TIMEOUT — a live holder still held the lock when the ceiling
+ *      elapsed, or an unrecoverable acquisition/reclaim guard leftover
+ *      exhausted the guard wait (see RUNBOOK.md).
  *   2. LOCK-FREE DEGRADATION — `acquireIndexLock` answers a read-only or
  *      permission-denied filesystem with a no-op handle that is byte-identical
  *      to a real one at the API boundary. That is a deliberate tolerance for
@@ -69,7 +71,7 @@
  * `GITNEXUS_INDEX_LOCK_BACKEND=file` is what covers that deployment.
  */
 import path from 'node:path';
-import { acquireIndexLock, IndexLockTimeoutError, } from '../../storage/index-lock.js';
+import { acquireIndexLock, IndexLockTimeoutError, isIndexLockGuardTimeout, } from '../../storage/index-lock.js';
 import { logger } from '../logger.js';
 /** Lock-directory name inside the group directory. Never the group dir itself. */
 export const GROUP_SYNC_LOCK_DIRNAME = 'sync-lock';
@@ -107,7 +109,7 @@ export class GroupSyncLockError extends Error {
 export const withGroupSyncLock = async (groupDir, operation) => {
     let handle;
     // The wrapper times the acquisition itself. `IndexLockTimeoutError` carries
-    // `holder` and `holderKnown` and nothing else — the elapsed wait exists only
+    // holder/guard identity but no elapsed-time field — the elapsed wait exists only
     // inside its inherited message string, so the figure has to be measured here
     // to be reported without that message. `Date.now()` matches how the primitive
     // measures its own wait.
@@ -128,6 +130,11 @@ export const withGroupSyncLock = async (groupDir, operation) => {
         // socket backend the holder is not identifiable at all. Re-word it around
         // what IS known: which group, which operation, and how long we waited.
         if (err instanceof IndexLockTimeoutError) {
+            if (isIndexLockGuardTimeout(err)) {
+                throw new GroupSyncLockError('timeout', groupDir, `Could not acquire the sync lock for group "${path.basename(groupDir)}" ` +
+                    `(${getGroupSyncLockDir(groupDir)}). ${err.message} ` +
+                    `Nothing was written and this group was not synced.`, err);
+            }
             throw new GroupSyncLockError('timeout', groupDir, `Timed out after ${Date.now() - acquireStartedAt}ms waiting for the sync lock on ` +
                 `group "${path.basename(groupDir)}" (${getGroupSyncLockDir(groupDir)}). ` +
                 // `holderKnown` is false on the socket backend and on the file

package/dist/core/run-analyze.js

@@ -16,7 +16,7 @@ import fs from 'fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { retryRename } from '../storage/fs-atomic.js';
-import { acquireIndexLock } from '../storage/index-lock.js';
+import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
 import { invalidateNodeWorkspacePackages } from './ingestion/import-resolvers/node-workspace-packages.js';
 import { logNameFallbackSummary, summarizeNameFallback, countCallsByLanguage, } from './ingestion/scope-resolution/name-fallback-summary.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
@@ -609,6 +609,7 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     let writeTarget = await resolveWriteTarget(repoPath, options);
     let lock = await acquireIndexLock(writeTarget.metaDir, acquireOpts);
     try {
+        requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${writeTarget.metaDir}; refusing an unlocked analysis.`);
         // #2658 review H2: acquireIndexLock can wait up to the timeout ceiling,
         // during which git HEAD/branch — and thus the resolved write slot — may
         // change (a commit lands, a branch is switched, or another writer adopts the
@@ -633,6 +634,7 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
             lock.release();
             writeTarget = fresh;
             lock = await acquireIndexLock(fresh.metaDir, acquireOpts);
+            requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${fresh.metaDir}; refusing an unlocked analysis.`);
             if (attempt === MAX_RELOCK - 1) {
                 log('Index write target still moving after repeated re-acquire; proceeding on this lock.');
             }

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

@@ -1,7 +1,7 @@
 import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
 // Value import (instanceof): index-lock is a lightweight storage primitive
 // (node:fs/net/crypto only), so this does NOT pull in run-analyze/repo-manager.
-import { IndexLockTimeoutError } from '../storage/index-lock.js';
+import { IndexLockTimeoutError, isIndexLockGuardTimeout } from '../storage/index-lock.js';
 /**
  * Run the analysis and report the outcome to the parent over IPC. Reports at most
  * one terminal message (`complete` or `error`) — and none if a cancellation
@@ -39,9 +39,15 @@ export async function runWorkerAnalysis(repoPath, options, deps, runnerIdentityA
         // #2658 review M2: a lock-wait timeout is transient contention (another
         // analyze held the single-writer lock), not a broken build — tag it so the
         // parent can surface a retry signal instead of an opaque hard failure.
+        // An orphan guard needs quiesced recovery, not automatic retries.
         terminal =
             err instanceof IndexLockTimeoutError
-                ? { type: 'error', message, code: 'index-lock-timeout', retryable: true }
+                ? {
+                    type: 'error',
+                    message,
+                    code: 'index-lock-timeout',
+                    retryable: !isIndexLockGuardTimeout(err),
+                }
                 : { type: 'error', message };
     }
     // P3 (#2264): only report if a SIGTERM cancellation hasn't already claimed the

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

@@ -52,12 +52,17 @@ export interface ErrorMessage {
     /**
      * Machine-readable failure code for a parent that wants to branch instead of
      * only surfacing the string. `index-lock-timeout` (#2658 review M2) means
-     * another analyze held the single-writer lock past the wait ceiling — a
-     * transient, retryable condition, not a broken build. Absent for a generic
-     * failure.
+     * acquisition waited past a wait ceiling. Ordinary lock contention is
+     * transient (`retryable: true`). An orphan acquisition/reclaim guard
+     * (`IndexLockTimeoutError.guardPath` set) is not — retries re-hit the 30s
+     * cap and need quiesced recovery (RUNBOOK.md), so `retryable` is false.
+     * Absent for a generic failure.
      */
     code?: 'index-lock-timeout';
-    /** True when the failure is expected to clear on retry (e.g. lock contention). */
+    /**
+     * True when the failure is expected to clear on retry (e.g. lock contention).
+     * False when `code` is `index-lock-timeout` because of guard contention.
+     */
     retryable?: boolean;
 }
 /** Child → parent IPC messages. Shared with the parent-side launcher. */

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

@@ -1,8 +1,9 @@
 declare const LOCK_RECORD_VERSION: 1;
 /**
- * On-disk lock record. `token` proves ownership on release/steal; `startTime`
- * (Linux only) defends against pid reuse; `invocationId` is a human-traceable
- * id distinct from the security-irrelevant `token`.
+ * On-disk lock record. `token` proves ownership on release and guard/workload
+ * verification; `startTime` (Linux only) defends against pid reuse;
+ * `invocationId` is a human-traceable id distinct from the security-irrelevant
+ * `token`.
  */
 export interface LockRecord {
     v: typeof LOCK_RECORD_VERSION;
@@ -50,7 +51,9 @@ export interface AcquireOptions {
      * would otherwise block acquisition forever. Timing out is safe — it stops
      * *waiting*, never *steals* a possibly-live holder — and names the holder so
      * the caller can retry. Override (including to unbounded, value ≤ 0) via
-     * GITNEXUS_INDEX_LOCK_TIMEOUT_MS.
+     * GITNEXUS_INDEX_LOCK_TIMEOUT_MS. File acquisition/reclaim guard contention
+     * is separately capped at 30s, or the remaining timeout if shorter; an
+     * orphan guard is never automatically taken over.
      */
     timeoutMs?: number;
     /** Base poll interval (ms); jittered. Default 250. */
@@ -68,15 +71,19 @@ export declare class IndexLockTimeoutError extends Error {
      * pid when this is false.
      */
     readonly holderKnown: boolean;
-    constructor(holder: LockRecord, waitedMs: number, holderKnown?: boolean);
+    /** Present only for acquisition/reclaim guard contention, requiring quiesced recovery. */
+    readonly guardPath?: string;
+    constructor(holder: LockRecord, waitedMs: number, holderKnown?: boolean, guardPath?: string);
 }
+export declare const isIndexLockGuardTimeout: (error: unknown) => error is IndexLockTimeoutError & {
+    guardPath: string;
+};
+/** Writers must refuse a handle that does not own the lock. */
+export declare const requireExclusiveIndexLock: (handle: IndexLockHandle, message: string) => void;
 /**
- * Filesystem-create error codes we tolerate by proceeding lock-free: a
- * read-only mount (EROFS) or a denied create (EACCES/EPERM). Such a filesystem
- * rejects every index WRITE in the same directory too, so no concurrent writer
- * can exist and the lock is moot — an already-indexed repo on a `:ro` mount
- * must still reach its `alreadyUpToDate` fast path (#2658). A genuinely-needed
- * write fails later exactly as it would have without the lock.
+ * Filesystem-create errors eligible for a read-only, non-owning handle when
+ * neither lock nor guard exists. Denied creation does NOT prove other writers
+ * lack access (ACLs may differ). Callers that write must reject lockFree handles.
  */
 export declare const LOCK_UNWRITABLE_CODES: ReadonlySet<string>;
 export declare const isLockUnwritableCode: (code: string | undefined) => boolean;

package/dist/storage/index-lock.js

@@ -33,25 +33,28 @@
  *  - **file** (`O_EXCL` pidfile) — the portable fallback for macOS/BSD (no
  *    abstract sockets; filesystem sockets don't release cleanly on death) and
  *    for any environment where the socket backend can't bind. It uses pid-
- *    liveness staleness, an atomic rename-steal reclaim, bounded malformed-file
- *    handling, read-only tolerance, and a finite wait timeout (a reused pid can
- *    masquerade as live where process start-time isn't verifiable, so waiting is
- *    bounded rather than a hang). Its stale-takeover has an irreducible narrow
- *    race — inherent to file-based advisory locks — which is precisely why the
- *    socket backend is preferred; only a kernel primitive closes it.
+ *    liveness staleness, a non-stealable acquisition/reclaim guard, bounded
+ *    malformed-file handling, read-only tolerance, and a finite wait timeout (a
+ *    reused pid can masquerade as live where process start-time isn't verifiable, so waiting is
+ *    bounded rather than a hang). Every file acquisition participates in the
+ *    guard, even for an empty slot. An orphan guard fails closed and requires
+ *    quiesced manual recovery (RUNBOOK.md); socket locks avoid that tradeoff.
+ *    Requires reliable local-filesystem O_EXCL and cooperating upgraded writers.
  *
  * Scope: cross-process, same logical index dir. The file backend never steals a
  * foreign-host lock (pid liveness is meaningless across hosts); the socket
  * backend is single-host by nature. The motivating case (local hook-driven
  * re-index) is single-host. See AcquireOptions.timeoutMs for the wait ceiling.
  */
-import { openSync, writeSync, closeSync, readFileSync, unlinkSync, renameSync, existsSync, mkdirSync, readdirSync, realpathSync, } from 'node:fs';
+import { openSync, writeSync, closeSync, readFileSync, unlinkSync, mkdirSync, readdirSync, realpathSync, lstatSync, } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import os from 'node:os';
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { isProcessAlive } from '../utils/process-identity.js';
 const LOCK_FILENAME = 'analyze.lock';
 const LOCK_RECORD_VERSION = 1;
+const lockGuardPath = (lockPath) => `${lockPath}.guard`;
 /** Base poll interval while waiting for a live holder; jittered per attempt. */
 const DEFAULT_POLL_MS = 250;
 /** How often to re-emit the "still waiting for pid N" diagnostic. */
@@ -64,12 +67,13 @@ const DIAGNOSTIC_INTERVAL_MS = 15_000;
  * GITNEXUS_INDEX_LOCK_TIMEOUT_MS (or set it ≤ 0 for unbounded).
  */
 const DEFAULT_TIMEOUT_MS = 600_000;
+/** Never wait indefinitely for a guard, even with an unbounded workload wait. */
+const GUARD_TIMEOUT_MS = 30_000;
 /**
  * How long a lock file must stay unreadable (empty/partial JSON) before we
- * treat it as a crash orphan and reclaim it. Tolerates the microsecond
- * create→write→close window of a *live* owner (see acquireIndexLock), so we
- * never steal a lock that is a poll-interval away from being written. Scaled
- * off the poll interval, floored at 1s.
+ * treat it as a crash orphan and reclaim it. This grace preserves legacy
+ * orphan handling; the guard, NOT elapsed time, excludes incomplete live
+ * creations. Scaled off the poll interval, floored at 1s.
  */
 const malformedGraceMs = (pollMs) => Math.max(1000, pollMs * 2);
 export class IndexLockTimeoutError extends Error {
@@ -82,18 +86,38 @@ export class IndexLockTimeoutError extends Error {
      * pid when this is false.
      */
     holderKnown;
-    constructor(holder, waitedMs, holderKnown = true) {
-        super(holderKnown
-            ? `Timed out after ${waitedMs}ms waiting for another gitnexus analyze ` +
-                `(pid ${holder.pid} on ${holder.hostname}, invocation ${holder.invocationId}) ` +
-                `to release the index lock.`
-            : `Timed out after ${waitedMs}ms waiting for another gitnexus analyze ` +
-                `(holder identity unknown) to release the index lock.`);
+    /** Present only for acquisition/reclaim guard contention, requiring quiesced recovery. */
+    guardPath;
+    constructor(holder, waitedMs, holderKnown = true, guardPath) {
+        super(formatIndexLockTimeoutMessage(holder, waitedMs, holderKnown, guardPath));
         this.name = 'IndexLockTimeoutError';
         this.holder = holder;
         this.holderKnown = holderKnown;
+        this.guardPath = guardPath;
     }
 }
+export const isIndexLockGuardTimeout = (error) => error instanceof IndexLockTimeoutError && error.guardPath !== undefined;
+/** Writers must refuse a handle that does not own the lock. */
+export const requireExclusiveIndexLock = (handle, message) => {
+    if (handle.lockFree)
+        throw new Error(message);
+};
+const formatIndexLockTimeoutMessage = (holder, waitedMs, holderKnown, guardPath) => {
+    if (guardPath !== undefined) {
+        return (`Timed out after ${waitedMs}ms waiting for acquisition/reclaim guard ${guardPath}. ` +
+            `Quiesce all relevant writers and prevent restart before manual recovery. ` +
+            `Never remove the guard while writers may run; see RUNBOOK.md for quiesced recovery.`);
+    }
+    if (holderKnown) {
+        return (`Timed out after ${waitedMs}ms waiting for another gitnexus analyze ` +
+            `(pid ${holder.pid} on ${holder.hostname}, invocation ${holder.invocationId}) ` +
+            `to release the index lock.`);
+    }
+    return (`Timed out after ${waitedMs}ms waiting for another gitnexus analyze ` +
+        `(holder identity unknown) to release the index lock.`);
+};
+const unverifiedGuardError = (guardPath) => new Error(`Cannot verify acquisition/reclaim guard ownership: ${guardPath}. ` +
+    'Acquisition refused; see RUNBOOK.md for quiesced recovery.');
 const HOSTNAME = os.hostname();
 /** Linux: field 22 of /proc/<pid>/stat (starttime). null elsewhere / on error. */
 const readProcStartTime = (pid) => {
@@ -114,16 +138,6 @@ const readProcStartTime = (pid) => {
         return null;
     }
 };
-/** true if the pid exists (signal 0). EPERM means it exists but isn't ours. */
-const pidAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-};
 const buildRecord = () => ({
     v: LOCK_RECORD_VERSION,
     pid: process.pid,
@@ -134,8 +148,16 @@ const buildRecord = () => ({
     acquiredAt: new Date().toISOString(),
 });
 const readRecord = (lockPath) => {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err; // An IO/permission failure is not evidence of a malformed orphan.
+    }
     try {
-        const raw = readFileSync(lockPath, 'utf8');
         const parsed = JSON.parse(raw);
         // `typeof NaN === 'number'`, so a bare number check lets NaN/0/-1/Infinity/
         // fractional pids reach process.kill (#2658 review L4): a garbled or crafted
@@ -145,11 +167,12 @@ const readRecord = (lockPath) => {
             return null;
         if (typeof parsed.token !== 'string')
             return null;
+        // Preserve the existing ownership format: unknown versions or missing
+        // ancillary metadata must not turn a live/foreign holder into an orphan.
         return parsed;
     }
     catch {
-        // Missing (won the race, file gone) or malformed/half-written → treat as
-        // "no readable holder"; the caller retries the O_EXCL create.
+        // Malformed/half-written; only reclaim under the guard after the grace.
         return null;
     }
 };
@@ -165,73 +188,13 @@ const readRecord = (lockPath) => {
 const isStale = (holder) => {
     if (holder.hostname !== HOSTNAME)
         return false;
-    if (!pidAlive(holder.pid))
+    if (!isProcessAlive(holder.pid))
         return true;
     const now = readProcStartTime(holder.pid);
     if (holder.startTime && now && holder.startTime !== now)
         return true; // pid reused
     return false;
 };
-/**
- * Reclaim a lock file we judged reclaimable — a dead holder (`expected` = its
- * record) or a malformed/unreadable crash-orphan (`expected` = null) — moving
- * the exact inode aside in ONE `rename` syscall to a token-unique name so two
- * waiters reclaiming the same orphan can't both win (the loser's rename ENOENTs).
- *
- * CRITICAL (#2658 review): the reclaim must not act on a STALE judgment. The
- * staleness decision (`isStale` / malformed-grace) happened a few syscalls ago;
- * a live writer may have O_EXCL-created its own lock at `lockPath` since. Blindly
- * renaming that live lock aside would delete it and admit a SECOND writer — the
- * exact double-writer this lock exists to prevent (reproduced: ~18%/round under
- * 4-way reclaim contention on the file backend). So:
- *   1. re-read `lockPath` immediately BEFORE the rename and confirm it still holds
- *      exactly what we judged (same token, or still-unreadable) — shrinking the
- *      window to the single gap between this read and the rename;
- *   2. after the rename, confirm what we ACTUALLY moved matches the judgment; if a
- *      live lock slipped into that residual gap, RESTORE it (rename back) so its
- *      holder is never displaced, and lose the reclaim.
- * A concurrent creator whose fresh lock the restore overwrites is caught by the
- * acquire loop's post-write read-back verify (see acquireViaFile), so it backs
- * off rather than proceeding as a second writer.
- *
- * Returns true if we won the reclaim (caller retries the create), false if we
- * lost the race or the judgment went stale (caller re-loops and re-reads).
- */
-const matchesJudgment = (record, expected) => expected === null ? record === null : record?.token === expected.token;
-const stealLock = (lockPath, me, expected) => {
-    // (1) Re-verify the judgment still holds right before we move anything.
-    if (!matchesJudgment(readRecord(lockPath), expected))
-        return false;
-    if (expected === null && !existsSync(lockPath))
-        return false; // malformed → but now vanished
-    const aside = `${lockPath}.dead.${me.token}`;
-    try {
-        renameSync(lockPath, aside);
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return false; // another stealer won
-        throw err;
-    }
-    // (2) Confirm what we moved is what we judged; if a live lock slipped into the
-    // read→rename gap, put it back — a live holder must never be displaced.
-    if (!matchesJudgment(readRecord(aside), expected)) {
-        try {
-            renameSync(aside, lockPath); // restore; an overwritten concurrent creator's read-back backs it off
-        }
-        catch {
-            /* slot re-taken between our move and restore — leave it; we lost the reclaim */
-        }
-        return false;
-    }
-    try {
-        unlinkSync(aside); // uniquely ours by token → safe; best-effort
-    }
-    catch {
-        /* leftover .dead.<token> is inert (not analyze.lock, not swept) — harmless */
-    }
-    return true;
-};
 /**
  * Placeholder holder for an {@link IndexLockTimeoutError} thrown while the lock
  * file exists but no valid record can be read (malformed/partial), or it keeps
@@ -248,13 +211,68 @@ const unknownHolder = () => ({
     invocationId: '<unreadable>',
     acquiredAt: '',
 });
+/** Remaining wait before the next guard-create poll, or throws the matching timeout. */
+const remainingGuardCreateWaitMs = (args) => {
+    const workloadDeadline = args.startedAt + args.timeoutMs;
+    const guardDeadline = args.guardWaitSince + GUARD_TIMEOUT_MS;
+    const deadline = Math.min(workloadDeadline, guardDeadline, args.permissionDeadline);
+    if (args.now < deadline)
+        return deadline - args.now;
+    if (args.permissionError && args.now >= args.permissionDeadline)
+        throw args.permissionError;
+    if (args.code === 'EPERM')
+        throw args.err;
+    if (args.now >= guardDeadline) {
+        throw new IndexLockTimeoutError(unknownHolder(), args.now - args.startedAt, false, args.guardPath);
+    }
+    const remembered = args.lastLiveHolder ?? unknownHolder();
+    throw new IndexLockTimeoutError(remembered, args.now - args.startedAt, args.lastLiveHolder !== null);
+};
+/** Drop this attempt's guard. A throw here discards the pending handle. */
+const releaseAcquisitionGuard = (guardPath, me, createdMain, lockPath) => {
+    try {
+        const guardRecord = readRecord(guardPath);
+        if (guardRecord && guardRecord.token !== me.token) {
+            throw unverifiedGuardError(guardPath);
+        }
+        if (guardRecord?.token === me.token) {
+            // Must complete before returning a workload handle or polling.
+            unlinkSync(guardPath);
+            return;
+        }
+        try {
+            lstatSync(guardPath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw unverifiedGuardError(guardPath);
+            }
+            throw err;
+        }
+        // Exists but unreadable: this process created the name via O_EXCL.
+        // Drop it so a failed metadata write cannot leave a permanent orphan,
+        // then refuse this attempt.
+        unlinkSync(guardPath);
+        throw unverifiedGuardError(guardPath);
+    }
+    catch (guardError) {
+        // Roll back only the token-exact record this attempt created.
+        if (createdMain) {
+            try {
+                if (readRecord(lockPath)?.token === me.token)
+                    unlinkSync(lockPath);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([guardError, cleanupError], `Guard and workload-lock cleanup failed: ${guardPath}. Acquisition refused; see RUNBOOK.md for quiesced recovery.`);
+            }
+        }
+        throw guardError;
+    }
+};
 /**
- * Filesystem-create error codes we tolerate by proceeding lock-free: a
- * read-only mount (EROFS) or a denied create (EACCES/EPERM). Such a filesystem
- * rejects every index WRITE in the same directory too, so no concurrent writer
- * can exist and the lock is moot — an already-indexed repo on a `:ro` mount
- * must still reach its `alreadyUpToDate` fast path (#2658). A genuinely-needed
- * write fails later exactly as it would have without the lock.
+ * Filesystem-create errors eligible for a read-only, non-owning handle when
+ * neither lock nor guard exists. Denied creation does NOT prove other writers
+ * lack access (ACLs may differ). Callers that write must reject lockFree handles.
  */
 export const LOCK_UNWRITABLE_CODES = new Set(['EROFS', 'EACCES', 'EPERM']);
 export const isLockUnwritableCode = (code) => code !== undefined && LOCK_UNWRITABLE_CODES.has(code);
@@ -267,6 +285,22 @@ const noopHandle = (record) => ({
     lockFree: true,
     release: () => { },
 });
+const deniedCreateHandle = (lockPath, record, error) => {
+    // Do not turn an existing (even malformed/unreadable) owner into permission
+    // to proceed. lstat also sees dangling links; only ENOENT proves absence.
+    for (const candidate of [lockPath, lockGuardPath(lockPath)]) {
+        try {
+            lstatSync(candidate);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            throw err;
+        }
+        throw error;
+    }
+    return noopHandle(record);
+};
 /**
  * Delete orphaned build/staging artifacts left in the lock directory by a
  * crashed prior writer. Safe precisely because we hold the exclusive lock: no
@@ -326,36 +360,31 @@ const resolveTimeoutMs = (opt) => {
             const n = Number(env);
             return Number.isFinite(n) ? n : DEFAULT_TIMEOUT_MS;
         })();
+    // Explicit NaN is a number, so it used to skip the env finite-check and
+    // poison every deadline (`startedAt + NaN`). Match the env fallback.
+    if (Number.isNaN(raw))
+        return DEFAULT_TIMEOUT_MS;
     return raw <= 0 ? Number.POSITIVE_INFINITY : raw;
 };
-/**
- * Acquire the exclusive write lock for `lockDir` (the resolved index slot
- * directory, e.g. `<repo>/.gitnexus` or `<repo>/.gitnexus/branches/<slug>`).
- *
- * Blocks until the lock is held (waiting only on live holders, stealing dead
- * ones immediately), then sweeps orphaned staging files under the lock and
- * returns a handle. Rejects with `IndexLockTimeoutError` if `timeoutMs` is
- * exceeded while a live holder still holds the lock.
- */
 /**
  * File-based (O_EXCL pidfile) backend. The portable fallback used on platforms
  * without the socket backend (macOS/BSD) or when the OS socket lock is
- * unavailable. Carries the pid-liveness staleness, atomic rename-steal reclaim,
- * bounded malformed-file handling, and read-only tolerance. Its stale-takeover
- * has an irreducible (narrow) race — see the module header — which is why the
- * socket backend is preferred where available.
+ * unavailable. All inspection/reclaim/create/verify operations are serialized
+ * by a sibling O_EXCL guard. No waiter ever removes a guard, regardless of age,
+ * pid liveness, or malformed metadata. See RUNBOOK.md for orphan recovery.
  */
 const acquireViaFile = async (lockDir, me, opts) => {
+    const lockPath = path.join(lockDir, LOCK_FILENAME);
     try {
         mkdirSync(lockDir, { recursive: true });
     }
     catch (err) {
-        // Read-only / denied filesystem → proceed lock-free (see LOCK_UNWRITABLE_CODES).
+        // Read-only / denied mkdir → lockFree only when neither lock nor guard exists.
         if (isLockUnwritableCode(err.code))
-            return noopHandle(me);
+            return deniedCreateHandle(lockPath, me, err);
         throw err;
     }
-    const lockPath = path.join(lockDir, LOCK_FILENAME);
+    const guardPath = lockGuardPath(lockPath);
     const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
     const timeoutMs = resolveTimeoutMs(opts.timeoutMs);
     const startedAt = Date.now();
@@ -364,63 +393,176 @@ const acquireViaFile = async (lockDir, me, opts) => {
     // When the lock file exists but has no readable record, the timestamp we
     // first observed it unreadable — used to reclaim a crash-orphan after a grace.
     let malformedSince = null;
+    let guardWaitSince = null;
+    let permissionWaitSince = null;
+    let permissionError;
+    // Last live workload holder observed while we held the inspect guard. Used
+    // when the overall wait budget expires during a brief peer inspect (EEXIST)
+    // so we do not mislabel ordinary contention as an orphan guard.
+    let lastLiveHolder = null;
     for (;;) {
+        const permissionDeadline = permissionWaitSince === null
+            ? Number.POSITIVE_INFINITY
+            : permissionWaitSince + GUARD_TIMEOUT_MS;
+        if (Date.now() >= Math.min(startedAt + timeoutMs, permissionDeadline) && permissionError) {
+            throw permissionError;
+        }
+        let guardFd;
+        try {
+            guardFd = openSync(guardPath, 'wx');
+        }
+        catch (err) {
+            const code = err.code;
+            // Windows can report EPERM while an unlinked guard is delete-pending.
+            // Retry under the same bounded budget, never interpret it as ownership.
+            if (code === 'EEXIST' || code === 'EPERM') {
+                const now = Date.now();
+                guardWaitSince ??= now;
+                const remainingMs = remainingGuardCreateWaitMs({
+                    now,
+                    startedAt,
+                    timeoutMs,
+                    guardWaitSince,
+                    permissionDeadline,
+                    permissionError,
+                    code,
+                    err,
+                    guardPath,
+                    lastLiveHolder,
+                });
+                await sleep(jitteredDelay(pollMs, remainingMs, 0));
+                continue;
+            }
+            if (isLockUnwritableCode(code))
+                return deniedCreateHandle(lockPath, me, err);
+            throw err;
+        }
+        guardWaitSince = null;
+        // Metadata is diagnostic. Cleanup unlinks our token-exact record, or a
+        // self-created unreadable leftover (then refuses this attempt). A foreign
+        // token is never removed.
+        let holder = null;
+        let createdMain = false;
         try {
-            // O_WRONLY | O_CREAT | O_EXCL — the atomic arbiter of ownership.
-            const fd = openSync(lockPath, 'wx');
             try {
-                writeSync(fd, JSON.stringify(me));
+                writeSync(guardFd, JSON.stringify(me));
             }
             finally {
-                closeSync(fd);
+                closeSync(guardFd);
             }
-            // Read-back verify (#2658 review L5): if this process stalled (a >graceMs
-            // GC pause) between the O_EXCL create of the *empty* file and the write
-            // above, a waiter could have reclaimed the empty file (renamed it aside)
-            // and O_EXCL-created its own lock at `lockPath`. Our write then landed on
-            // the renamed-aside inode, not `lockPath`. Confirm `lockPath` still carries
-            // our token before claiming ownership; if it was stolen, contend normally.
-            const confirmed = readRecord(lockPath);
-            if (!confirmed || confirmed.token !== me.token)
-                continue;
-            return {
-                record: me,
-                release: () => {
-                    const current = readRecord(lockPath);
-                    if (current && current.token !== me.token)
-                        return; // no longer ours
+            holder = readRecord(lockPath);
+            let tryCreate = false;
+            if (holder) {
+                malformedSince = null;
+                if (isStale(holder)) {
+                    opts.log?.(`Reclaiming stale index lock from dead analyze (pid ${holder.pid}, ` +
+                        `invocation ${holder.invocationId}).`);
+                    unlinkSync(lockPath);
+                    tryCreate = true;
+                    holder = null;
+                }
+            }
+            else {
+                tryCreate = true;
+            }
+            if (tryCreate) {
+                let fd;
+                try {
+                    fd = openSync(lockPath, 'wx');
+                    createdMain = true;
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code === 'EEXIST') {
+                        // Exclusive create is the presence check — do not existsSync first.
+                        const current = readRecord(lockPath);
+                        if (current === null) {
+                            malformedSince ??= Date.now();
+                            if (Date.now() - malformedSince >= malformedGraceMs(pollMs)) {
+                                opts.log?.('Reclaiming a malformed/partial index lock file (no readable owner record).');
+                                unlinkSync(lockPath);
+                                malformedSince = null;
+                            }
+                        }
+                        else {
+                            holder = current;
+                        }
+                    }
+                    else if (code === 'EPERM') {
+                        throw err;
+                    }
+                    else if (isLockUnwritableCode(code)) {
+                        return deniedCreateHandle(lockPath, me, err);
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                if (createdMain && fd !== undefined) {
                     try {
-                        unlinkSync(lockPath);
+                        writeSync(fd, JSON.stringify(me));
                     }
-                    catch {
-                        /* already gone */
+                    finally {
+                        closeSync(fd);
                     }
-                },
-            };
-        }
-        catch (err) {
-            const code = err.code;
-            if (code === 'EEXIST') {
-                // fall through to holder inspection / wait / reclaim below
+                    if (readRecord(lockPath)?.token !== me.token) {
+                        throw new Error(`Index lock verification failed: ${lockPath}`);
+                    }
+                    let released = false;
+                    return {
+                        record: me,
+                        release: () => {
+                            if (released)
+                                return;
+                            released = true;
+                            // No async boundary: a cooperating contender cannot replace a live
+                            // owner's record before this one-shot unlink. Unknown is not ours.
+                            try {
+                                if (readRecord(lockPath)?.token !== me.token)
+                                    return;
+                                unlinkSync(lockPath);
+                            }
+                            catch {
+                                /* best-effort on exit; never retry against a successor */
+                            }
+                        },
+                    };
+                }
             }
-            else if (isLockUnwritableCode(code)) {
-                return noopHandle(me); // read-only / denied → proceed lock-free
+            permissionWaitSince = null;
+            permissionError = undefined;
+        }
+        catch (error) {
+            if (!createdMain && error.code === 'EPERM') {
+                // A releasing owner may leave the main file delete-pending on Windows.
+                // Release our guard in finally and retry; never reclaim an unreadable file.
+                permissionWaitSince ??= Date.now();
+                permissionError = error;
+                holder = null;
+                if (Date.now() >= Math.min(startedAt + timeoutMs, permissionWaitSince + GUARD_TIMEOUT_MS)) {
+                    throw error;
+                }
             }
             else {
-                throw err;
+                if (createdMain) {
+                    try {
+                        if (readRecord(lockPath)?.token === me.token)
+                            unlinkSync(lockPath);
+                    }
+                    catch (cleanupError) {
+                        throw new AggregateError([error, cleanupError], `Workload-lock cleanup failed: ${lockPath}. Acquisition refused; see RUNBOOK.md for quiesced recovery.`);
+                    }
+                }
+                throw error;
             }
         }
-        const holder = readRecord(lockPath);
+        finally {
+            releaseAcquisitionGuard(guardPath, me, createdMain, lockPath);
+        }
         const waited = Date.now() - startedAt;
         if (holder) {
-            malformedSince = null;
-            if (isStale(holder)) {
-                opts.log?.(`Reclaiming stale index lock from dead analyze (pid ${holder.pid}, ` +
-                    `invocation ${holder.invocationId}).`);
-                stealLock(lockPath, me, holder); // reclaim ONLY this dead record; live locks are never stolen
-                continue;
-            }
             // Live holder → wait.
+            lastLiveHolder = holder;
             if (!announcedWait) {
                 announcedWait = true;
                 opts.onWaitStart?.(holder);
@@ -438,30 +580,12 @@ const acquireViaFile = async (lockDir, me, opts) => {
             await sleep(jitteredDelay(pollMs, timeoutMs, waited));
             continue;
         }
-        // holder === null: the lock file is either gone (vanished between the failed
-        // create and our read) or present-but-unreadable (a crash between the
-        // O_EXCL create and the record write, or a partial write). NEVER hot-loop
-        // here — both branches are bounded by sleep + timeout.
-        if (!existsSync(lockPath)) {
-            malformedSince = null; // genuinely vanished → the next create likely wins
-            if (waited >= timeoutMs)
-                throw new IndexLockTimeoutError(unknownHolder(), waited, false);
-            await sleep(jitteredDelay(pollMs, timeoutMs, waited));
-            continue;
-        }
-        // Malformed orphan present. Reclaim only after a grace, so a live owner's
-        // microsecond create→write window is never mistaken for a crash.
-        if (malformedSince === null)
-            malformedSince = Date.now();
-        if (Date.now() - malformedSince >= malformedGraceMs(pollMs)) {
-            opts.log?.('Reclaiming a malformed/partial index lock file (no readable owner record).');
-            stealLock(lockPath, me, null); // reclaim ONLY while still unreadable; a live lock written since is left
-            malformedSince = null;
-            continue;
-        }
         if (waited >= timeoutMs)
             throw new IndexLockTimeoutError(unknownHolder(), waited, false);
-        await sleep(jitteredDelay(pollMs, timeoutMs, waited));
+        const waitCeiling = Math.min(timeoutMs, permissionWaitSince === null
+            ? Number.POSITIVE_INFINITY
+            : permissionWaitSince + GUARD_TIMEOUT_MS - startedAt);
+        await sleep(jitteredDelay(pollMs, waitCeiling, waited));
     }
 };
 /** Signals that the OS socket backend can't be used here (e.g. abstract
@@ -648,10 +772,10 @@ export const acquireIndexLock = async (lockDir, opts = {}) => {
     else {
         handle = await acquireViaFile(lockDir, me, opts);
     }
-    // Reclaim crashed-build staging orphans while we hold the lock. Best-effort:
-    // a read-only mount (no orphans reachable) just no-ops.
+    // Without ownership, a staging file may belong to an active writer.
     try {
-        sweepStagingArtifacts(lockDir, opts.log);
+        if (!handle.lockFree)
+            sweepStagingArtifacts(lockDir, opts.log);
     }
     catch {
         /* best-effort */

package/dist/storage/repo-manager.js

@@ -21,7 +21,7 @@ import { stripWindowsLongPathPrefix } from '../lib/utils.js';
 import { writeFileAtomic } from './fs-atomic.js';
 import { getGlobalDir } from './global-dir.js';
 import { logger } from '../core/logger.js';
-import { acquireIndexLock, IndexLockTimeoutError } from './index-lock.js';
+import { acquireIndexLock, IndexLockTimeoutError, requireExclusiveIndexLock, } from './index-lock.js';
 import { branchSlug, BRANCHES_DIR, resolveBranchPlacement, } from './branch-index.js';
 import { GITNEXUS_DIR, INDEX_METADATA_FILE, LEGACY_METADATA_FILE, getStoragePath, isMissingFilesystemError, loadMeta, tryReadMetaFile, } from './repo-meta.js';
 // Re-export the #2106 branch primitives (extracted to branch-index.ts, R10) so
@@ -471,7 +471,8 @@ const REGISTRY_LOCK_TIMEOUT_MS = 5_000;
  * The registry is shared by every indexed repository, so per-index locks do
  * not protect this file. Reuse the cross-platform index lock primitive with a
  * registry-private lock namespace; the handle is kernel-owned on supported
- * platforms and crash-reclaimable by the existing fallback.
+ * platforms. The file fallback reclaims dead workload holders; an orphan
+ * acquisition guard requires quiesced recovery (RUNBOOK.md).
  *
  * On timeout the transaction fails closed: continuing unlocked would reintroduce
  * the lost-update race this lock exists to prevent and can silently discard a
@@ -495,6 +496,7 @@ const withRegistryLock = async (operation) => {
         throw err;
     }
     try {
+        requireExclusiveIndexLock(lock, 'Cannot acquire the global registry lock; refusing an unlocked registry transaction.');
         return await operation();
     }
     finally {

package/package.json

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