@ngockhoale/ukit 3.0.2 → 3.0.4

package/scripts/index/build-index.mjs

@@ -1,36 +1,102 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../src/index/buildIndex.js';
-
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
-
-const summary = await buildCodeIndex({ rootDir });
-await buildDerivedIndexArtifacts(rootDir);
-
-console.log('[index:build] completed');
-console.log(`root: ${rootDir}`);
-console.log(`files: ${summary.fileCount}`);
-console.log(`symbols: ${summary.symbolCount}`);
-console.log(`imports: ${summary.importCount}`);
-console.log(`tests-map: ${summary.testsMapCount}`);
-console.log(`hotspots: ${summary.hotspotCount}`);
-console.log(`parsed: ${summary.parsedCodeFileCount}`);
-console.log(`reused: ${summary.reusedCodeFileCount}`);
-console.log(`indexDir: ${summary.indexDir}`);
-
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
+import {
+  buildCodeIndex,
+  buildDerivedIndexArtifacts,
+  inspectIndexStaleness,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
+} from '../../src/index/buildIndex.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: remainingArgs } = extractFlagValue(args, '--root');
+  const unexpected = remainingArgs.filter((arg) => arg.startsWith('--'));
+  if (unexpected.length > 0) {
+    throw new Error(`unexpected argument: ${unexpected[0]}`);
+  }
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+
+  // One enumeration serves both the readability check and the build: the
+  // snapshot is handed to buildCodeIndex, which reuses it instead of
+  // rediscovering the repository.
+  const { snapshot } = await inspectIndexStaleness({ rootDir, maxAgeMs: 0 });
+  const unreadable = await collectUnreadableFiles(rootDir, snapshot?.files ?? []);
+  for (const filePath of unreadable) {
+    console.error(`[index:build] skipped unreadable file: ${filePath}`);
   }
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
+  const summary = await buildCodeIndex({ rootDir, discoverySnapshot: snapshot });
+  await buildDerivedIndexArtifacts(rootDir);
+
+  console.log('[index:build] completed');
+  console.log(`root: ${rootDir}`);
+  console.log(`files: ${summary.fileCount}`);
+  console.log(`symbols: ${summary.symbolCount}`);
+  console.log(`imports: ${summary.importCount}`);
+  console.log(`tests-map: ${summary.testsMapCount}`);
+  console.log(`hotspots: ${summary.hotspotCount}`);
+  console.log(`parsed: ${summary.parsedCodeFileCount}`);
+  console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (unreadable.length > 0) {
+    console.log(`skipped-unreadable: ${unreadable.length}`);
   }
+  console.log(`indexDir: ${summary.indexDir}`);
+}
+
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
+    }
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
+
+    nextArgs.push(arg);
+  }
+
+  return { value, args: nextArgs };
+}
 
-  return null;
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
 }

package/scripts/index/query-index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import {
@@ -7,28 +8,40 @@ import {
 import {
   buildCodeIndex,
   buildDerivedIndexArtifacts,
+  inspectIndexStaleness,
   isIndexStale,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 import { parseIndexArgs, QUERY_FLAG_DEFINITIONS } from '../../src/cli/commands/indexArgs.js';
 
-const args = process.argv.slice(2);
-const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
-const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
-const changedFiles = changedArg
-  ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
-  : [];
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
+  const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
+  const changedFiles = changedArg
+    ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+
+  const { tokens, flags } = parseIndexArgs(remainingArgs, QUERY_FLAG_DEFINITIONS);
+  const query = tokens.join(' ').trim();
+  if (!query) {
+    console.error('Usage: yarn index:query -- "<error|symbol|path>" [--limit N] [--changed fileA,fileB]');
+    process.exitCode = 1;
+    return;
+  }
 
-const { tokens, flags } = parseIndexArgs(remainingArgs, QUERY_FLAG_DEFINITIONS);
-const query = tokens.join(' ').trim();
-if (!query) {
-  console.error('Usage: yarn index:query -- "<error|symbol|path>" [--limit N] [--changed fileA,fileB]');
-  process.exitCode = 1;
-} else {
   const stale = await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
   if (stale) {
-    await buildCodeIndex({ rootDir });
+    // One enumeration serves the readability check and the rebuild.
+    const { snapshot } = await inspectIndexStaleness({ rootDir, maxAgeMs: 0 });
+    const unreadable = await collectUnreadableFiles(rootDir, snapshot?.files ?? []);
+    for (const filePath of unreadable) {
+      console.error(`[index:query] skipped unreadable file: ${filePath}`);
+    }
+    await buildCodeIndex({ rootDir, discoverySnapshot: snapshot });
     await buildDerivedIndexArtifacts(rootDir);
   }
 
@@ -59,6 +72,20 @@ if (!query) {
   }
 }
 
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
+    }
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
 function extractFlagValue(argv, flag) {
   let value = null;
   const nextArgs = [];
@@ -92,3 +119,10 @@ function extractFlagValue(argv, flag) {
 
   return { value, args: nextArgs };
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/scripts/index/refresh-index.mjs

@@ -5,46 +5,63 @@ import path from 'node:path';
 import {
   buildCodeIndex,
   inspectIndexStaleness,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
+  const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
+  const force = remainingArgs.includes('--force');
+  const unexpected = remainingArgs.filter((arg) => arg !== '--force');
+  if (unexpected.length > 0) {
+    throw new Error(`unexpected argument: ${unexpected[0]}`);
+  }
 
-const changedArg = readFlagValue(args, '--changed');
-const changedFiles = changedArg
-  ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
-  : [];
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+  const hintedFiles = changedArg
+    ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
 
-const force = readBooleanFlag(args, '--force');
-const lastRefreshMs = await getLastRefreshTime(rootDir);
+  // Hints that exist but cannot be read would be silently dropped by the parse
+  // worker; surface them and keep them out of the merge set. ENOENT hints are
+  // kept — a deleted file is a legitimate removal hint.
+  const { readable: changedFiles, unreadable: unreadableHints } = await partitionReadableHints(rootDir, hintedFiles);
+  for (const filePath of unreadableHints) {
+    console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
+  }
 
-if (changedFiles.length > 0 && !force) {
-  // Hints carry the change set, so no staleness enumeration is needed:
-  // buildCodeIndex merges the hinted paths into the existing artifacts and
-  // falls back to the bounded full discovery path on its own when the hints
-  // are unsafe or the previous artifacts cannot be merged (TASK-023).
-  const summary = await buildCodeIndex({ rootDir, changedFiles });
+  const lastRefreshMs = await getLastRefreshTime(rootDir);
 
-  console.log('[index:refresh] completed');
-  console.log(`mode: ${summary.mode}`);
-  if (lastRefreshMs !== null) {
-    console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
-  }
-  console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  console.log(`root: ${rootDir}`);
-  console.log(`files: ${summary.fileCount}`);
-  console.log(`parsed: ${summary.parsedCodeFileCount}`);
-  console.log(`reused: ${summary.reusedCodeFileCount}`);
-  if (summary.removedFiles.length > 0) {
-    console.log(`removed: ${summary.removedFiles.length}`);
+  if (changedFiles.length > 0 && !force) {
+    // Hints carry the change set, so no staleness enumeration is needed:
+    // buildCodeIndex merges the hinted paths into the existing artifacts and
+    // falls back to the bounded full discovery path on its own when the hints
+    // are unsafe or the previous artifacts cannot be merged (TASK-023).
+    const summary = await buildCodeIndex({ rootDir, changedFiles });
+
+    console.log('[index:refresh] completed');
+    console.log(`mode: ${summary.mode}`);
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    console.log(`root: ${rootDir}`);
+    console.log(`files: ${summary.fileCount}`);
+    console.log(`parsed: ${summary.parsedCodeFileCount}`);
+    console.log(`reused: ${summary.reusedCodeFileCount}`);
+    if (summary.removedFiles.length > 0) {
+      console.log(`removed: ${summary.removedFiles.length}`);
+    }
+    console.log(`indexDir: ${summary.indexDir}`);
+    return;
   }
-  console.log(`indexDir: ${summary.indexDir}`);
-} else {
-  const staleness = force
-    ? null
-    : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+
+  // One enumeration serves the staleness check, the readability check, and the
+  // build: the snapshot is handed to buildCodeIndex, which reuses it.
+  const staleness = await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
   const stale = force || staleness.stale;
 
   if (!stale) {
@@ -56,45 +73,101 @@ if (changedFiles.length > 0 && !force) {
       console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
     }
     console.log(`root: ${rootDir}`);
-  } else {
-    // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
-    const summary = await buildCodeIndex({
-      rootDir,
-      discoverySnapshot: staleness ? staleness.snapshot : null,
-    });
+    return;
+  }
 
-    console.log('[index:refresh] completed');
-    console.log(`mode: ${summary.mode}`);
-    if (lastRefreshMs !== null) {
-      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+  const unreadable = await collectUnreadableFiles(rootDir, staleness.snapshot?.files ?? []);
+  for (const filePath of unreadable) {
+    console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
+  }
+
+  const summary = await buildCodeIndex({
+    rootDir,
+    discoverySnapshot: staleness.snapshot,
+  });
+
+  console.log('[index:refresh] completed');
+  console.log(`mode: ${summary.mode}`);
+  if (lastRefreshMs !== null) {
+    console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+  }
+  if (changedFiles.length > 0) {
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  }
+  console.log(`root: ${rootDir}`);
+  console.log(`files: ${summary.fileCount}`);
+  console.log(`parsed: ${summary.parsedCodeFileCount}`);
+  console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (unreadable.length > 0) {
+    console.log(`skipped-unreadable: ${unreadable.length}`);
+  }
+  console.log(`indexDir: ${summary.indexDir}`);
+}
+
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
     }
-    if (changedFiles.length > 0) {
-      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
+async function partitionReadableHints(rootDir, hints) {
+  const readable = [];
+  const unreadable = [];
+  for (const hint of hints) {
+    try {
+      await fs.access(path.resolve(rootDir, hint), fs.constants.R_OK);
+      readable.push(hint);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        readable.push(hint); // deleted file — a legitimate removal hint
+      } else {
+        unreadable.push(hint);
+      }
     }
-    console.log(`root: ${rootDir}`);
-    console.log(`files: ${summary.fileCount}`);
-    console.log(`parsed: ${summary.parsedCodeFileCount}`);
-    console.log(`reused: ${summary.reusedCodeFileCount}`);
-    console.log(`indexDir: ${summary.indexDir}`);
   }
+  return { readable, unreadable };
 }
 
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
-  }
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
-  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
 
-  return null;
-}
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
 
-function readBooleanFlag(argv, flag) {
-  return argv.includes(flag);
+    nextArgs.push(arg);
+  }
+
+  return { value, args: nextArgs };
 }
 
 async function getLastRefreshTime(rootDir) {
@@ -113,3 +186,10 @@ async function getLastRefreshTime(rootDir) {
     return null;
   }
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/scripts/perf/audit-perf.mjs

@@ -53,6 +53,12 @@ const CLUSTER_GAP_MS = 1500;
 // is a finding in its own right, not merely a term inside a chain total.
 const HOTSPOT_P50_MS = 50;
 
+// TASK-010: every spawned child carries an explicit timeout + killSignal — a
+// wedged hook script or git child must fail the benchmark sample, not hang the
+// audit forever (same class as BUG-C22-20/21). UKIT_PERF_SPAWN_TIMEOUT_MS
+// overrides the budget for tests.
+const SPAWN_TIMEOUT_MS = Number(process.env.UKIT_PERF_SPAWN_TIMEOUT_MS) || 60 * 1000; // 1 min
+
 // A hook row costs the wrapper `bash`, its `node` runtime, and the advisory
 // telemetry `node --finish` child armed by hook-telemetry.sh.
 const PROCESSES_PER_HOOK_ROW = 3;
@@ -420,7 +426,7 @@ function benchSpawn(file, args, iterations, env) {
   const samples = [];
   for (let i = 0; i < iterations; i += 1) {
     const start = process.hrtime.bigint();
-    spawnSync(file, args, { env, input: '{}', stdio: ['pipe', 'ignore', 'ignore'] });
+    spawnSync(file, args, { env, input: '{}', stdio: ['pipe', 'ignore', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' });
     samples.push(Number(process.hrtime.bigint() - start) / 1e6);
   }
   return summarise(samples);
@@ -560,7 +566,7 @@ function recentHotPathAdditions(root, sinceDays) {
         '.claude/hooks',
         '.claude/ukit/runtime',
       ],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' },
     );
     const commits = [];
     let current = null;

package/scripts/skill/audit-skill.mjs

@@ -1,32 +1,54 @@
 #!/usr/bin/env node
 import { initSkillAudit, recordAuditEntry, statusSkillAudit } from '../../src/skill/auditSkill.js';
 
-const [command, skillName] = process.argv.slice(2);
-const rootDir = process.cwd();
+const USAGE = 'Usage: yarn skill:audit <init|status|record> <skill-name>';
 
-if (!command || !skillName) {
-  console.error('Usage: yarn skill:audit <init|status|record> <skill-name>');
-  process.exitCode = 1;
-} else if (command === 'init') {
-  const result = await initSkillAudit({ rootDir, skillName });
-  console.log(`[skill:audit init] ${skillName}`);
-  console.log(`dir: ${result.auditDir}`);
-  console.log(`copied: ${result.copied.join(', ') || 'none'}`);
-  console.log(`skipped (already present): ${result.skipped.join(', ') || 'none'}`);
-} else if (command === 'status') {
-  const result = await statusSkillAudit({ rootDir, skillName });
-  console.log(`[skill:audit status] ${skillName}`);
-  console.log(`entries: ${result.entryCount}`);
-  console.log(`latest: ${result.latest ? JSON.stringify(result.latest) : 'none'}`);
-  console.log(`open rationalizations: ${result.openRationalizations.length}`);
-} else if (command === 'record') {
-  const stdinRaw = await readStdin();
-  const entry = JSON.parse(stdinRaw);
-  const record = await recordAuditEntry({ rootDir, skillName, entry });
-  console.log(`[skill:audit record] ${skillName}`);
-  console.log(JSON.stringify(record, null, 2));
-} else {
-  console.error(`Unknown command: ${command}. Usage: yarn skill:audit <init|status|record> <skill-name>`);
+async function main() {
+  const [command, skillName, ...extra] = process.argv.slice(2);
+  const rootDir = process.cwd();
+
+  if (!command || !skillName) {
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  if (extra.length > 0) {
+    throw new Error(`unexpected argument: ${extra[0]}. ${USAGE}`);
+  }
+
+  if (command === 'init') {
+    const result = await initSkillAudit({ rootDir, skillName });
+    console.log(`[skill:audit init] ${skillName}`);
+    console.log(`dir: ${result.auditDir}`);
+    console.log(`copied: ${result.copied.join(', ') || 'none'}`);
+    console.log(`skipped (already present): ${result.skipped.join(', ') || 'none'}`);
+    return;
+  }
+
+  if (command === 'status') {
+    const result = await statusSkillAudit({ rootDir, skillName });
+    console.log(`[skill:audit status] ${skillName}`);
+    console.log(`entries: ${result.entryCount}`);
+    console.log(`latest: ${result.latest ? JSON.stringify(result.latest) : 'none'}`);
+    console.log(`open rationalizations: ${result.openRationalizations.length}`);
+    return;
+  }
+
+  if (command === 'record') {
+    const stdinRaw = await readStdin();
+    let entry;
+    try {
+      entry = JSON.parse(stdinRaw);
+    } catch (error) {
+      throw new Error(`skill:audit record expects a JSON entry on stdin: ${error.message}`);
+    }
+    const record = await recordAuditEntry({ rootDir, skillName, entry });
+    console.log(`[skill:audit record] ${skillName}`);
+    console.log(JSON.stringify(record, null, 2));
+    return;
+  }
+
+  console.error(`Unknown command: ${command}. ${USAGE}`);
   process.exitCode = 1;
 }
 
@@ -37,3 +59,10 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString('utf8');
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/src/bug/triageBug.js

@@ -2,6 +2,7 @@ import { queryCodeIndex } from '../index/queryIndex.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { detectPackageManager } from '../core/packageManager.js';
+import { readJsonIfExists } from '../core/fileOps.js';
 import { inferRelatedTestsFromArtifacts, loadRelatedTestArtifacts } from '../index/relatedTests.js';
 
 const DEEP_KEYWORDS = ['race', 'flaky', 'intermittent', 'timeout', 'deadlock'];
@@ -28,10 +29,9 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
   const directRecommendedTestFile = prioritizedResults
     .flatMap((item) => item.tests ?? [])
     .find(Boolean);
-  const shouldLoadRelatedArtifacts = Boolean(topResult) || !directRecommendedTestFile;
-  const relatedArtifacts = shouldLoadRelatedArtifacts
-    ? await loadRelatedTestArtifacts({ rootDir })
-    : null;
+  // `Boolean(topResult) || !directRecommendedTestFile` is always true (no
+  // topResult ⇒ no tests ⇒ no direct file), so artifacts load unconditionally.
+  const relatedArtifacts = await loadRelatedTestArtifacts({ rootDir });
   const inferredRecommendedTests = directRecommendedTestFile
     ? []
     : inferRelatedTestsFromArtifacts({
@@ -70,9 +70,12 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
     ],
   };
 }
-
 async function buildTestCommand(rootDir, testFile) {
-  const packageManager = await detectPackageManager(rootDir);
+  // Pass the parsed package.json so a declared `packageManager` field wins over
+  // lockfile/npm defaults — detectPackageManager(rootDir) alone ignored it.
+  const packageJson = await readJsonIfExists(path.join(rootDir, 'package.json')).catch(() => null);
+  const packageManager = await detectPackageManager(rootDir, packageJson);
+
 
   if (packageManager === 'pnpm') {
     return `pnpm test ${testFile}`;

package/src/cli/adapters.js

@@ -105,6 +105,12 @@ export function resolveOptionalToolKeys(toolsArg) {
 
   const normalized = toolsArg.trim().toLowerCase();
 
+  if (!normalized) {
+    // `--tools=` / `--tools ""` used to fall through to an empty selection —
+    // silently deselecting every optional adapter. Treat it as a missing value.
+    throw new Error(`Missing value for --tools. Use --tools=${TOOLS_FLAG_HELP}`);
+  }
+
   if (normalized === 'all') {
     return [...DEFAULT_OPTIONAL_TOOL_KEYS];
   }

package/src/cli/commands/code.js

@@ -12,8 +12,14 @@ const SUBCOMMANDS = new Set(['peek', 'search', 'context', 'impact']);
 function extractFlag(args, flag) {
   const index = args.indexOf(flag);
   if (index < 0) return { value: null, rest: args };
+  const value = args[index + 1];
+  // A missing value — or the next flag swallowed as the value — used to pass
+  // silently (e.g. `--mode --budget 5` set mode='--budget' and dropped --budget).
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
   return {
-    value: args[index + 1] ?? null,
+    value,
     rest: [...args.slice(0, index), ...args.slice(index + 2)],
   };
 }