Address PR review feedback round 4 (#2543)

- hook-db-lock-probe: an fd-directory read error other than ENOENT or
  ENOTDIR on an identified server candidate now fails closed ('timeout')
  instead of reporting not-owned (EMFILE/ENFILE/ENOMEM/EINTR)
- hook-db-lock-probe: resolve GITNEXUS_HOOK_TIMEOUT_PATH to an absolute
  path before validating and caching it, so callers that spawn with a
  request cwd can still execute the guard
- hook-db-lock-probe: document the chunked cmdline read's actual stop
  conditions (all 3 copies)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Gergo Magyar 2026-09-24 10:56:35 +00:00
parent 4cb2b80c82
commit 7bdbb924cc
4 changed files with 140 additions and 68 deletions

View file

@ -179,7 +179,13 @@ function resolveUnixGuardTimeout() {
const trimmed = fromEnv ? String(fromEnv).trim() : '';
if (trimmed === 'disabled') return unixGuardTimeoutCache;
const candidates = [];
if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
// Resolve the override against THIS process's cwd — the directory the
// existsSync check and the self-test run in — so the cached/returned path is
// always absolute. The adapters spawn the wrapper with a different `cwd`
// (the tool request's), where a relative value would resolve elsewhere
// (ENOENT), and a slashless name would switch to a PATH lookup.
const override = trimmed ? path.resolve(trimmed) : '';
if (override && fs.existsSync(override)) candidates.push(override);
for (const builtin of [
'/usr/bin/timeout',
'/bin/timeout',
@ -398,8 +404,10 @@ const CMDLINE_TIMEOUT = Symbol('gitnexus.cmdline.timeout');
// Bounded /proc/<pid>/cmdline read for Phase 1. openSync+readSync (not
// readFileSync) so a D-state holder cannot stall the hook on a huge or
// never-EOF argv: we read at most `cap` bytes and stop. cmdline separates argv
// with NULs; convert to spaces for isGitNexusServerCommand.
// never-EOF argv: we read in `cap`-sized chunks and stop as soon as the text
// holds both server tokens, at EOF, at PROC_CMDLINE_CEIL, or when the scan
// budget runs out (see below). cmdline separates argv with NULs; convert to
// spaces for isGitNexusServerCommand.
//
// Owner-miss guard for the 4 KB cap: the `gitnexus` token usually sits in the
// first path component while the `mcp`/`serve` mode token is the LAST argv, so
@ -594,17 +602,24 @@ function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
);
return 'timeout';
}
// Any other shape (ENOTDIR — fd path is not a directory at all, so this
// is not a plausible live-procfs owner — and the long tail) is treated as
// "this candidate is not an owner": move to the next candidate instead of
// the old blanket 'owned'. If no other candidate owns the lbug the scan
// ends not-owned (dispatcher fail-open) — acceptable because ENOTDIR means
// the fd entry is structurally not a real /proc/<pid>/fd.
if (code === 'ENOTDIR') {
// The fd path is not a directory at all, so this is structurally not a
// real /proc/<pid>/fd — not a plausible live owner. Move on.
debugLog(
`fd dir not a directory for candidate pid ${pidStr} (ENOTDIR); ` +
`treating candidate as non-owner -> continue`,
);
continue;
}
// Any other error (EMFILE, ENFILE, ENOMEM, EINTR, no code, …) says nothing
// about whether this already-identified server candidate holds the lbug.
// Only ENOENT/ENOTDIR above establish non-ownership; everything else is
// inconclusive and fails closed via 'timeout', same as EACCES/EIO.
debugLog(
`fd dir not a readable directory for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); treating candidate as non-owner -> continue`,
`fd dir read failed for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); probe inconclusive -> fail-closed (timeout)`,
);
continue;
return 'timeout';
}
for (const fd of fds) {
if (outOfBudget()) return 'timeout';
@ -723,16 +738,12 @@ module.exports = {
// name is pinned by a source-contract test.
linuxProcScanFindGitNexusServer,
// #2163 follow-up: the hook adapters wrap the augment CLI in the same
// guard. Returns a self-tested wrapper path — the built-in candidates are
// always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
// exact string that passed the self-test. Same string is also the same
// RESOLUTION for absolute paths and for slashless names (PATH lookup is
// cwd-independent); a slash-containing RELATIVE override, however, is
// existsSync-checked and self-tested against this process's cwd while the
// adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
// a value can pass here yet ENOENT at the augment call site — set the
// override to an absolute path. Returns null when the wrapper is
// disabled/unavailable. Never call on win32 (see its JSDoc).
// guard. Returns a self-tested, always-ABSOLUTE wrapper path: the built-in
// candidates are absolute, and a GITNEXUS_HOOK_TIMEOUT_PATH override is
// path.resolve()d against this process's cwd before its existsSync check
// and self-test, so the adapters can spawn it under any `cwd` option.
// Returns null when the wrapper is disabled/unavailable. Never call on
// win32 (see its JSDoc).
resolveUnixGuardTimeout,
// Exported for white-box unit tests of the numeric-env parsing (#2183 review):
// Number()-not-parseInt so "16e3" reads as 16000, plus the empty/whitespace

View file

@ -179,7 +179,13 @@ function resolveUnixGuardTimeout() {
const trimmed = fromEnv ? String(fromEnv).trim() : '';
if (trimmed === 'disabled') return unixGuardTimeoutCache;
const candidates = [];
if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
// Resolve the override against THIS process's cwd — the directory the
// existsSync check and the self-test run in — so the cached/returned path is
// always absolute. The adapters spawn the wrapper with a different `cwd`
// (the tool request's), where a relative value would resolve elsewhere
// (ENOENT), and a slashless name would switch to a PATH lookup.
const override = trimmed ? path.resolve(trimmed) : '';
if (override && fs.existsSync(override)) candidates.push(override);
for (const builtin of [
'/usr/bin/timeout',
'/bin/timeout',
@ -398,8 +404,10 @@ const CMDLINE_TIMEOUT = Symbol('gitnexus.cmdline.timeout');
// Bounded /proc/<pid>/cmdline read for Phase 1. openSync+readSync (not
// readFileSync) so a D-state holder cannot stall the hook on a huge or
// never-EOF argv: we read at most `cap` bytes and stop. cmdline separates argv
// with NULs; convert to spaces for isGitNexusServerCommand.
// never-EOF argv: we read in `cap`-sized chunks and stop as soon as the text
// holds both server tokens, at EOF, at PROC_CMDLINE_CEIL, or when the scan
// budget runs out (see below). cmdline separates argv with NULs; convert to
// spaces for isGitNexusServerCommand.
//
// Owner-miss guard for the 4 KB cap: the `gitnexus` token usually sits in the
// first path component while the `mcp`/`serve` mode token is the LAST argv, so
@ -594,17 +602,24 @@ function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
);
return 'timeout';
}
// Any other shape (ENOTDIR — fd path is not a directory at all, so this
// is not a plausible live-procfs owner — and the long tail) is treated as
// "this candidate is not an owner": move to the next candidate instead of
// the old blanket 'owned'. If no other candidate owns the lbug the scan
// ends not-owned (dispatcher fail-open) — acceptable because ENOTDIR means
// the fd entry is structurally not a real /proc/<pid>/fd.
if (code === 'ENOTDIR') {
// The fd path is not a directory at all, so this is structurally not a
// real /proc/<pid>/fd — not a plausible live owner. Move on.
debugLog(
`fd dir not a directory for candidate pid ${pidStr} (ENOTDIR); ` +
`treating candidate as non-owner -> continue`,
);
continue;
}
// Any other error (EMFILE, ENFILE, ENOMEM, EINTR, no code, …) says nothing
// about whether this already-identified server candidate holds the lbug.
// Only ENOENT/ENOTDIR above establish non-ownership; everything else is
// inconclusive and fails closed via 'timeout', same as EACCES/EIO.
debugLog(
`fd dir not a readable directory for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); treating candidate as non-owner -> continue`,
`fd dir read failed for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); probe inconclusive -> fail-closed (timeout)`,
);
continue;
return 'timeout';
}
for (const fd of fds) {
if (outOfBudget()) return 'timeout';
@ -723,16 +738,12 @@ module.exports = {
// name is pinned by a source-contract test.
linuxProcScanFindGitNexusServer,
// #2163 follow-up: the hook adapters wrap the augment CLI in the same
// guard. Returns a self-tested wrapper path — the built-in candidates are
// always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
// exact string that passed the self-test. Same string is also the same
// RESOLUTION for absolute paths and for slashless names (PATH lookup is
// cwd-independent); a slash-containing RELATIVE override, however, is
// existsSync-checked and self-tested against this process's cwd while the
// adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
// a value can pass here yet ENOENT at the augment call site — set the
// override to an absolute path. Returns null when the wrapper is
// disabled/unavailable. Never call on win32 (see its JSDoc).
// guard. Returns a self-tested, always-ABSOLUTE wrapper path: the built-in
// candidates are absolute, and a GITNEXUS_HOOK_TIMEOUT_PATH override is
// path.resolve()d against this process's cwd before its existsSync check
// and self-test, so the adapters can spawn it under any `cwd` option.
// Returns null when the wrapper is disabled/unavailable. Never call on
// win32 (see its JSDoc).
resolveUnixGuardTimeout,
// Exported for white-box unit tests of the numeric-env parsing (#2183 review):
// Number()-not-parseInt so "16e3" reads as 16000, plus the empty/whitespace

View file

@ -179,7 +179,13 @@ function resolveUnixGuardTimeout() {
const trimmed = fromEnv ? String(fromEnv).trim() : '';
if (trimmed === 'disabled') return unixGuardTimeoutCache;
const candidates = [];
if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
// Resolve the override against THIS process's cwd — the directory the
// existsSync check and the self-test run in — so the cached/returned path is
// always absolute. The adapters spawn the wrapper with a different `cwd`
// (the tool request's), where a relative value would resolve elsewhere
// (ENOENT), and a slashless name would switch to a PATH lookup.
const override = trimmed ? path.resolve(trimmed) : '';
if (override && fs.existsSync(override)) candidates.push(override);
for (const builtin of [
'/usr/bin/timeout',
'/bin/timeout',
@ -398,8 +404,10 @@ const CMDLINE_TIMEOUT = Symbol('gitnexus.cmdline.timeout');
// Bounded /proc/<pid>/cmdline read for Phase 1. openSync+readSync (not
// readFileSync) so a D-state holder cannot stall the hook on a huge or
// never-EOF argv: we read at most `cap` bytes and stop. cmdline separates argv
// with NULs; convert to spaces for isGitNexusServerCommand.
// never-EOF argv: we read in `cap`-sized chunks and stop as soon as the text
// holds both server tokens, at EOF, at PROC_CMDLINE_CEIL, or when the scan
// budget runs out (see below). cmdline separates argv with NULs; convert to
// spaces for isGitNexusServerCommand.
//
// Owner-miss guard for the 4 KB cap: the `gitnexus` token usually sits in the
// first path component while the `mcp`/`serve` mode token is the LAST argv, so
@ -594,17 +602,24 @@ function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
);
return 'timeout';
}
// Any other shape (ENOTDIR — fd path is not a directory at all, so this
// is not a plausible live-procfs owner — and the long tail) is treated as
// "this candidate is not an owner": move to the next candidate instead of
// the old blanket 'owned'. If no other candidate owns the lbug the scan
// ends not-owned (dispatcher fail-open) — acceptable because ENOTDIR means
// the fd entry is structurally not a real /proc/<pid>/fd.
if (code === 'ENOTDIR') {
// The fd path is not a directory at all, so this is structurally not a
// real /proc/<pid>/fd — not a plausible live owner. Move on.
debugLog(
`fd dir not a directory for candidate pid ${pidStr} (ENOTDIR); ` +
`treating candidate as non-owner -> continue`,
);
continue;
}
// Any other error (EMFILE, ENFILE, ENOMEM, EINTR, no code, …) says nothing
// about whether this already-identified server candidate holds the lbug.
// Only ENOENT/ENOTDIR above establish non-ownership; everything else is
// inconclusive and fails closed via 'timeout', same as EACCES/EIO.
debugLog(
`fd dir not a readable directory for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); treating candidate as non-owner -> continue`,
`fd dir read failed for candidate pid ${pidStr} ` +
`(${code || 'unknown'}); probe inconclusive -> fail-closed (timeout)`,
);
continue;
return 'timeout';
}
for (const fd of fds) {
if (outOfBudget()) return 'timeout';
@ -723,16 +738,12 @@ module.exports = {
// name is pinned by a source-contract test.
linuxProcScanFindGitNexusServer,
// #2163 follow-up: the hook adapters wrap the augment CLI in the same
// guard. Returns a self-tested wrapper path — the built-in candidates are
// always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
// exact string that passed the self-test. Same string is also the same
// RESOLUTION for absolute paths and for slashless names (PATH lookup is
// cwd-independent); a slash-containing RELATIVE override, however, is
// existsSync-checked and self-tested against this process's cwd while the
// adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
// a value can pass here yet ENOENT at the augment call site — set the
// override to an absolute path. Returns null when the wrapper is
// disabled/unavailable. Never call on win32 (see its JSDoc).
// guard. Returns a self-tested, always-ABSOLUTE wrapper path: the built-in
// candidates are absolute, and a GITNEXUS_HOOK_TIMEOUT_PATH override is
// path.resolve()d against this process's cwd before its existsSync check
// and self-test, so the adapters can spawn it under any `cwd` option.
// Returns null when the wrapper is disabled/unavailable. Never call on
// win32 (see its JSDoc).
resolveUnixGuardTimeout,
// Exported for white-box unit tests of the numeric-env parsing (#2183 review):
// Number()-not-parseInt so "16e3" reads as 16000, plus the empty/whitespace

View file

@ -17,7 +17,7 @@ import { createRequire } from 'node:module';
import fs from 'fs';
import os from 'os';
import path from 'path';
import { spawn } from 'child_process';
import { spawn, spawnSync } from 'child_process';
import { createFakeProcRoot, type FakeProcEntry } from '../utils/hook-test-helpers.js';
const PROBE_PATH = path.resolve(__dirname, '..', '..', 'hooks', 'claude', 'hook-db-lock-probe.cjs');
@ -151,6 +151,38 @@ describe('hook binary override trimming (white-box, #2543 review)', () => {
// GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS="" resolve to Number("")===0 => budget 0 =>
// immediate fail-CLOSED timeout (augment permanently skipped). The added
// `&& String(raw).trim()` guard keeps ''/whitespace on the 1200 default.
// GITNEXUS_HOOK_TIMEOUT_PATH relative override (#2543 review): the adapters
// spawn the returned wrapper with the tool request's `cwd`, so the probe must
// hand back an ABSOLUTE path resolved against the directory its existsSync
// check and self-test ran in. The resolution is memoized per module instance,
// so each case runs in a fresh `node` child whose cwd holds a self-testing
// guard script (`-k <k> <budget> cmd…` -> exec cmd…).
describe.skipIf(process.platform === 'win32')(
'GITNEXUS_HOOK_TIMEOUT_PATH relative override resolves to absolute (#2543 review)',
() => {
it.each(['./fake-guard', 'fake-guard'])('override %s -> path.resolve(value)', (value) => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-probe-relguard-'));
cleanups.push(() => fs.rmSync(dir, { recursive: true, force: true }));
fs.writeFileSync(path.join(dir, 'fake-guard'), '#!/bin/sh\nshift 3\nexec "$@"\n', {
mode: 0o755,
});
const script =
`const p=require(${JSON.stringify(PROBE_PATH)});` +
`process.stdout.write(JSON.stringify({cwd:process.cwd(),guard:p.resolveUnixGuardTimeout()}));`;
const child = spawnSync(process.execPath, ['-e', script], {
cwd: dir,
encoding: 'utf-8',
env: { ...process.env, GITNEXUS_HOOK_TIMEOUT_PATH: value },
timeout: 15000,
});
expect(child.status).toBe(0);
const out = JSON.parse(child.stdout) as { cwd: string; guard: string | null };
expect(out.guard).toBe(path.resolve(out.cwd, value));
expect(path.isAbsolute(out.guard ?? '')).toBe(true);
});
},
);
describe('numeric env parsing (white-box, #2183 review)', () => {
const budget = probe.resolveLinuxProcBudgetMs as () => number;
const cmdlineMax = probe.getCmdlineMaxBytes as () => number;
@ -620,7 +652,8 @@ describe.skipIf(!isLinux)('Linux cmdline-first DB-owner scan (#2180)', () => {
// not lock. F1 splits the failure shapes:
// - EACCES / EPERM -> 'timeout' (unverifiable; fail-closed HONESTLY)
// - EIO / ESTALE -> 'timeout' (transient I/O; fail-closed)
// - ENOTDIR / other -> continue (not a real fd dir; treat as non-owner)
// - ENOTDIR -> continue (not a real fd dir; treat as non-owner)
// - any other errno -> 'timeout' (EMFILE/ENFILE/ENOMEM/…: inconclusive)
// The dispatcher collapses owned+timeout to boolean true, so these assert the
// exported tri-state verdict directly — a boolean check could not tell the F1
// fix from the old bug.
@ -677,6 +710,12 @@ describe.skipIf(!isLinux)('Linux cmdline-first DB-owner scan (#2180)', () => {
{ code: 'EIO', expected: 'timeout' },
{ code: 'ESTALE', expected: 'timeout' },
{ code: 'ENOTDIR', expected: 'not-owned' },
// Resource/interruption failures say nothing about ownership of an
// already-identified server candidate: fail closed, never not-owned.
{ code: 'EMFILE', expected: 'timeout' },
{ code: 'ENFILE', expected: 'timeout' },
{ code: 'ENOMEM', expected: 'timeout' },
{ code: 'EINTR', expected: 'timeout' },
] as const) {
it(`candidate fd readdir ${code} → verdict ${expected} (uid-agnostic spy)`, () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-probe-fderr-'));