gitnexus 1.6.12-rc.37 → 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/mcp/local/local-backend.js

@@ -55,6 +55,7 @@ import { stalenessPayload, } from '../../core/staleness-status.js';
 import { logger } from '../../core/logger.js';
 import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
+import { foldNumericToolArgumentAliases } from '../tool-arguments.js';
 import { findImportCycles, IMPORT_CYCLE_LIMIT } from '../../core/graph/import-cycles.js';
 import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
 import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
@@ -154,10 +155,8 @@ const TOOL_STRING_ALIASES = {
 function normalizeToolParams(method, params) {
     const input = params && typeof params === 'object' ? params : {};
     const definitions = TOOL_STRING_ALIASES[method];
-    if (!definitions)
-        return { params: input };
     const normalized = { ...input };
-    for (const { canonical, aliases } of definitions) {
+    for (const { canonical, aliases } of definitions ?? []) {
         const keys = [canonical, ...aliases];
         const supplied = [];
         for (const key of keys) {
@@ -191,12 +190,15 @@ function normalizeToolParams(method, params) {
         if (supplied.length > 0)
             normalized[canonical] = supplied[0].value;
     }
+    const folded = foldNumericToolArgumentAliases(method, normalized);
+    if ('error' in folded)
+        return folded;
     if (method === 'impact' &&
-        typeof normalized.target !== 'string' &&
-        (typeof normalized.target_uid !== 'string' || !normalized.target_uid.trim())) {
+        typeof folded.params.target !== 'string' &&
+        (typeof folded.params.target_uid !== 'string' || !folded.params.target_uid.trim())) {
         return { error: 'MCP impact requires target, name, symbol, or target_uid.' };
     }
-    return { params: normalized };
+    return { params: folded.params };
 }
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';

package/dist/mcp/server.js

@@ -20,6 +20,7 @@ import { getResourceDefinitions, getResourceTemplates, readResource } from './re
 import { assertMcpReadOnlyResource, assertMcpReadOnlyToolCall, filterMcpReadOnlyResourceContent, MCP_READ_ONLY_TOOLS, readOnlyResourceTemplateAllowed, resolveMcpReadOnlyMode, toolForReadOnlyMcp, } from './read-only-policy.js';
 import { createMcpRepositoryPolicy, McpRepositoryPolicy, mcpRepositoryPolicyConfigured, } from './repository-policy.js';
 import { applyMcpMaxTokens, resolveMcpMaxTokens, withoutMcpBudgetArg } from './output-budget.js';
+import { assertKnownMcpToolArguments, schemaSourceToolName } from './tool-arguments.js';
 /**
  * Next-step hints appended to tool responses.
  *
@@ -164,6 +165,12 @@ export function createMCPServer(backend, options = {}) {
         try {
             const typedArgs = args;
             assertMcpReadOnlyToolCall(name, typedArgs, readOnly);
+            const schemaSource = schemaSourceToolName(name);
+            const advertisedTool = GITNEXUS_TOOLS.find((tool) => tool.name === schemaSource);
+            if (advertisedTool) {
+                const listed = toolForReadOnlyMcp(repositoryPolicy.toolForMcp(advertisedTool), readOnly);
+                assertKnownMcpToolArguments(name, typedArgs, listed.inputSchema.properties);
+            }
             maxTokens = resolveMcpMaxTokens(name, typedArgs);
             const result = await scopedBackend.callTool(name, withoutMcpBudgetArg(typedArgs));
             const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);

package/dist/mcp/tool-arguments.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP tool-argument contract (#3261).
+ *
+ * `tools/list` advertises `inputSchema`; `tools/call` used to forward any JSON
+ * object. A misspelled or CLI-taught key (`depth` instead of `maxDepth`) then
+ * produced a well-formed answer computed from the server default — no error,
+ * no warning. This module is the single dispatch-time check that the keys a
+ * caller sent are ones the advertised schema (or an unpublished handler alias)
+ * actually reads.
+ */
+/** Legacy MCP names that reuse another tool's advertised schema. */
+export declare const LEGACY_TOOL_SCHEMA_SOURCE: Readonly<Record<string, string>>;
+/**
+ * Keys the handler still reads but that must NOT appear in `inputSchema`
+ * (#2175: advertising `query` makes Claude Code drop the argument).
+ */
+export declare const UNPUBLISHED_TOOL_ARGUMENT_ALIASES: Readonly<Record<string, readonly string[]>>;
+export interface NumericArgumentAlias {
+    canonical: string;
+    aliases: readonly string[];
+}
+/**
+ * Numeric aliases that the backend folds onto the advertised canonical key.
+ * `depth` is the CLI flag name for `maxDepth` on impact and trace.
+ */
+export declare const TOOL_NUMERIC_ARGUMENT_ALIASES: Readonly<Record<string, readonly NumericArgumentAlias[]>>;
+export declare function schemaSourceToolName(toolName: string): string;
+export declare function advertisedToolPropertyNames(toolName: string): string[] | undefined;
+export declare function suggestKnownToolArgument(unknownKey: string, knownKeys: readonly string[]): string | undefined;
+/**
+ * Reject top-level tool arguments that are neither advertised nor an
+ * unpublished handler alias. `advertisedProperties` should be the schema the
+ * caller actually saw (`tools/list` after read-only / repository-policy
+ * scrubbing). When it is omitted, the canonical `GITNEXUS_TOOLS` schema is
+ * used. Tools with no schema (legacy `overview`) are left unchecked.
+ */
+export declare function assertKnownMcpToolArguments(toolName: string, args: Record<string, unknown> | undefined, advertisedProperties?: Record<string, unknown>): void;
+/**
+ * Fold numeric aliases onto their canonical key (e.g. `depth` → `maxDepth`).
+ * Conflicting values error; a single agreed value is written to the canonical
+ * key and the alias keys are removed so every downstream reader sees one name.
+ */
+export declare function foldNumericToolArgumentAliases(toolName: string, params: Record<string, unknown>): {
+    params: Record<string, unknown>;
+} | {
+    error: string;
+};

package/dist/mcp/tool-arguments.js

@@ -0,0 +1,147 @@
+/**
+ * MCP tool-argument contract (#3261).
+ *
+ * `tools/list` advertises `inputSchema`; `tools/call` used to forward any JSON
+ * object. A misspelled or CLI-taught key (`depth` instead of `maxDepth`) then
+ * produced a well-formed answer computed from the server default — no error,
+ * no warning. This module is the single dispatch-time check that the keys a
+ * caller sent are ones the advertised schema (or an unpublished handler alias)
+ * actually reads.
+ */
+import { GITNEXUS_TOOLS } from './tools.js';
+/** Legacy MCP names that reuse another tool's advertised schema. */
+export const LEGACY_TOOL_SCHEMA_SOURCE = {
+    search: 'query',
+    explore: 'context',
+};
+/**
+ * Keys the handler still reads but that must NOT appear in `inputSchema`
+ * (#2175: advertising `query` makes Claude Code drop the argument).
+ */
+export const UNPUBLISHED_TOOL_ARGUMENT_ALIASES = {
+    query: ['query'],
+    cypher: ['query'],
+    // Group-mode context still reads `target` as the symbol name; local
+    // `name` is the advertised key. Advertising `target` would collide with
+    // impact's target vocabulary and is not in tools/list. Legacy `search`
+    // and `explore` inherit via schemaSourceToolName.
+    context: ['target'],
+};
+/**
+ * Numeric aliases that the backend folds onto the advertised canonical key.
+ * `depth` is the CLI flag name for `maxDepth` on impact and trace.
+ */
+export const TOOL_NUMERIC_ARGUMENT_ALIASES = {
+    impact: [{ canonical: 'maxDepth', aliases: ['depth'] }],
+    trace: [{ canonical: 'maxDepth', aliases: ['depth'] }],
+};
+export function schemaSourceToolName(toolName) {
+    return LEGACY_TOOL_SCHEMA_SOURCE[toolName] ?? toolName;
+}
+export function advertisedToolPropertyNames(toolName) {
+    const source = schemaSourceToolName(toolName);
+    const tool = GITNEXUS_TOOLS.find((entry) => entry.name === source);
+    if (!tool)
+        return undefined;
+    return Object.keys(tool.inputSchema.properties);
+}
+function normalizeArgumentKey(key) {
+    return key.toLowerCase().replace(/_/gu, '');
+}
+export function suggestKnownToolArgument(unknownKey, knownKeys) {
+    const needle = normalizeArgumentKey(unknownKey);
+    if (!needle)
+        return undefined;
+    const exact = knownKeys.find((key) => normalizeArgumentKey(key) === needle);
+    if (exact)
+        return exact;
+    const contained = knownKeys.filter((key) => {
+        const normalized = normalizeArgumentKey(key);
+        return normalized.includes(needle) || needle.includes(normalized);
+    });
+    return contained.length === 1 ? contained[0] : undefined;
+}
+function formatUnknownArgumentError(toolName, unknownKeys, advertisedKeys) {
+    const quoted = unknownKeys.map((key) => `"${key}"`).join(', ');
+    const noun = unknownKeys.length === 1 ? 'argument' : 'arguments';
+    const verb = unknownKeys.length === 1 ? 'does' : 'do';
+    const suggestion = unknownKeys.length === 1 ? suggestKnownToolArgument(unknownKeys[0], advertisedKeys) : undefined;
+    if (suggestion) {
+        return `Unknown ${noun} ${quoted} for tool "${toolName}". Did you mean "${suggestion}"?`;
+    }
+    return (`Unknown ${noun} ${quoted} for tool "${toolName}". ` +
+        `The advertised inputSchema ${verb} not include ${unknownKeys.length === 1 ? 'this key' : 'these keys'}.`);
+}
+/**
+ * Reject top-level tool arguments that are neither advertised nor an
+ * unpublished handler alias. `advertisedProperties` should be the schema the
+ * caller actually saw (`tools/list` after read-only / repository-policy
+ * scrubbing). When it is omitted, the canonical `GITNEXUS_TOOLS` schema is
+ * used. Tools with no schema (legacy `overview`) are left unchecked.
+ */
+export function assertKnownMcpToolArguments(toolName, args, advertisedProperties) {
+    if (!args)
+        return;
+    const propertyNames = advertisedProperties !== undefined
+        ? Object.keys(advertisedProperties)
+        : advertisedToolPropertyNames(toolName);
+    if (!propertyNames)
+        return;
+    const unpublished = UNPUBLISHED_TOOL_ARGUMENT_ALIASES[toolName] ??
+        UNPUBLISHED_TOOL_ARGUMENT_ALIASES[schemaSourceToolName(toolName)] ??
+        [];
+    const allowed = new Set([...propertyNames, ...unpublished]);
+    const unknownKeys = Object.keys(args).filter((key) => !allowed.has(key));
+    if (unknownKeys.length === 0)
+        return;
+    throw new Error(formatUnknownArgumentError(toolName, unknownKeys, propertyNames));
+}
+/**
+ * Fold numeric aliases onto their canonical key (e.g. `depth` → `maxDepth`).
+ * Conflicting values error; a single agreed value is written to the canonical
+ * key and the alias keys are removed so every downstream reader sees one name.
+ */
+export function foldNumericToolArgumentAliases(toolName, params) {
+    const definitions = TOOL_NUMERIC_ARGUMENT_ALIASES[toolName];
+    if (!definitions)
+        return { params };
+    const normalized = { ...params };
+    for (const { canonical, aliases } of definitions) {
+        const keys = [canonical, ...aliases];
+        const supplied = [];
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(normalized, key))
+                continue;
+            const value = normalized[key];
+            if (value === undefined)
+                continue;
+            if (typeof value !== 'number') {
+                return { error: `MCP parameter ${toolName}.${key} must be a number.` };
+            }
+            // #2279: some MCP adapters materialize an omitted optional number as 0,
+            // and a coerced missing value arrives as NaN. Treat both sentinels as
+            // absent so they cannot conflict with a real maxDepth or fold onto
+            // `params.maxDepth || 3`. The handlers already map a non-positive or
+            // non-integer maxDepth to their default; erroring here turned that
+            // contract into an error payload instead.
+            if (value === 0 || Number.isNaN(value))
+                continue;
+            supplied.push({ key, value });
+        }
+        const distinctValues = new Set(supplied.map(({ value }) => value));
+        if (distinctValues.size > 1) {
+            return {
+                error: `Conflicting MCP parameters for ${toolName}.${canonical}: ${supplied
+                    .map(({ key }) => key)
+                    .join(', ')} must agree.`,
+            };
+        }
+        // Drop every source key, then write back the single agreed value (if any),
+        // so a sentinel 0/NaN never survives on the canonical key.
+        for (const key of keys)
+            delete normalized[key];
+        if (supplied.length > 0)
+            normalized[canonical] = supplied[0].value;
+    }
+    return { params: normalized };
+}

package/dist/mcp/tools.d.ts

@@ -24,6 +24,7 @@ export interface ToolDefinition {
             minLength?: number;
         }>;
         required: string[];
+        additionalProperties?: false;
     };
 }
 /**

package/dist/mcp/tools.js

@@ -526,6 +526,12 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     minimum: 1,
                     maximum: IMPACT_MAX_DEPTH,
                 },
+                depth: {
+                    type: 'number',
+                    description: 'Compatibility alias for maxDepth (CLI --depth). Values must agree when both are present. Literal 0 is an omitted-value compatibility sentinel.',
+                    minimum: 0,
+                    maximum: IMPACT_MAX_DEPTH,
+                },
                 crossDepth: {
                     type: 'number',
                     description: 'Cross-repository hop depth via contract bridge (default: 1; values above server maximum are clamped)',
@@ -865,6 +871,12 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
                     minimum: 1,
                     maximum: 30,
                 },
+                depth: {
+                    type: 'number',
+                    description: 'Compatibility alias for maxDepth (CLI --depth). Values must agree when both are present. Literal 0 is an omitted-value compatibility sentinel.',
+                    minimum: 0,
+                    maximum: 30,
+                },
                 includeTests: {
                     type: 'boolean',
                     description: 'Include test-file symbols in traversal (default: false)',
@@ -922,6 +934,16 @@ export const REPO_SCOPED_TOOLS = new Set([
     'trace',
 ]);
 for (const tool of GITNEXUS_TOOLS) {
+    // Advertises a closed schema; tools/call still fail-closes on the scrubbed key list.
+    // The unpublished handler aliases in tool-arguments.ts stay off this schema on
+    // purpose (#2175), and closing it strands no caller: every alias has an
+    // advertised counterpart reaching the same handler — `query` → `search_query`
+    // on query, `query` → `statement` on cypher, and `target` → `name` on group
+    // context, which local-backend maps to the group target (the group name comes
+    // from `repo: "@group"`, not from `name`; see test/unit/mcp/group-repo-routing).
+    // A schema-validating client therefore has a valid call for every tool, and
+    // advertising the aliases instead would re-break Claude Code on `query`.
+    tool.inputSchema.additionalProperties = false;
     if (!REPO_SCOPED_TOOLS.has(tool.name))
         continue;
     if (tool.inputSchema.properties.branch)

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/git.js

@@ -903,12 +903,16 @@ export function parseDiffHunksResult(diffOutput) {
     // `+++` after the first `@@` of a file is hunk body (`+` plus source text
     // that itself starts `++ …`), not another file header.
     let inHunk = false;
+    // A deleted file has no new-side coordinates. Its indexed symbols still use
+    // the pre-delete file, so map those hunks with the old-side range instead.
+    let currentFileDeleted = false;
     for (const line of diffOutput.split('\n')) {
         if (line.startsWith(DIFF_GIT_PREFIX)) {
             // Drop the previous file first: an unparsed header must not leave
             // `current` live for a later `@@` / quoted `+++` to steal.
             current = null;
             inHunk = false;
+            currentFileDeleted = false;
             const filePath = filePathFromGitHeader(line);
             if (filePath) {
                 current = { filePath, hunks: [] };
@@ -929,6 +933,9 @@ export function parseDiffHunksResult(diffOutput) {
                 files.push(current);
             }
         }
+        else if (!inHunk && line === '+++ /dev/null') {
+            currentFileDeleted = true;
+        }
         else if (!inHunk && line.startsWith('+++ ')) {
             const filePath = pathFromPlusPlusPlus(line);
             if (!filePath)
@@ -940,10 +947,12 @@ export function parseDiffHunksResult(diffOutput) {
         }
         else if (line.startsWith('@@') && current) {
             inHunk = true;
-            const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+            const match = line.match(/@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
             if (match) {
-                const start = parseInt(match[1], 10);
-                const count = match[2] !== undefined ? parseInt(match[2], 10) : 1;
+                const sideOffset = currentFileDeleted ? 1 : 3;
+                const start = parseInt(match[sideOffset], 10);
+                const rawCount = match[sideOffset + 1];
+                const count = rawCount !== undefined ? parseInt(rawCount, 10) : 1;
                 if (count > 0) {
                     current.hunks.push({ startLine: start, endLine: start + count - 1 });
                 }

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.37",
+  "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",