@magnusekdahl/parallix 1.2.1 → 1.3.1

package/lib/commands/coverage-gate.ts

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+
+/**
+ * coverage-gate.js - run parallix tests with Node's built-in coverage support
+ * and enforce a configurable line-coverage threshold (default 90%).
+ *
+ * Usage:
+ *   node parallix/lib/commands/coverage-gate.js [--threshold <pct>] [--dry-run]
+ *
+ * Exit 0 when tests pass and coverage >= threshold.
+ * Exit 1 otherwise.
+ *
+ * Denominator: parallix/index.js plus all nested .js files under parallix/lib
+ * Excludes: parallix/test/*, parallix/prompts/*, parallix/config/*.json,
+ *           coverage output dirs, node_modules, generated/temp files.
+ *
+ * /tmp write inventory (SC-1): every /tmp or os.tmpdir() write location used by
+ * coverage-gate.js and the workflow test infrastructure it runs:
+ *
+ * 1. PER_RUN_SCRATCH array (line 58) — tracks per-process scratch dirs created
+ *    by this process. Each entry is a path returned by fs.mkdtempSync().
+ * 2. Node --experimental-test-coverage scratch (line 146) — Node creates
+ *    coverage-*.json files under NODE_V8_COVERAGE. coverage-gate.js sets
+ *    NODE_V8_COVERAGE to a per-process unique dir via createPerRunScratchDirs()
+ *    (line 176), so Node writes to a unique path, never /tmp/node-coverage-*.
+ * 3. parallix/coverage/ directory (line 153) — created via fs.mkdirSync for
+ *    lcov output; lives under REPO_ROOT, not /tmp.
+ * 4. TEMP_DIR_PREFIXES (lines 26-44) — prefix-based cleanup allowlist used by
+ *    cleanupNewTempDirs() (lines 94-110). Covers dirs created by test files
+ *    under parallix/test/*. These prefixes are intentionally NOT modified per SC-8.
+ * 5. os.tmpdir() default parameter (lines 85, 94) — listTempEntries() and
+ *    cleanupNewTempDirs() accept os.tmpdir() as default root. runTests() passes
+ *    a per-run TMPDIR to the child test process and cleans only that root.
+ * 6. Per-process mkdtempSync dirs (line 113) — createPerRunScratchDirs() creates
+ *    a unique dir via fs.mkdtempSync(path.join(os.tmpdir(), 'node-coverage-'))
+ *    and records it in PER_RUN_SCRATCH for targeted cleanup.
+ * 7. Test files (37 files, ~168 mkdtempSync calls) — all use
+ *    fs.mkdtempSync(path.join(os.tmpdir(), 'prefix-')) pattern; already
+ *    per-process unique. No fixed-path /tmp writes in test files. Generic
+ *    runtime-* dirs are intentionally excluded because runtime-matrix launcher
+ *    tests keep executable probes there while parallel coverage processes run.
+ * 8. /tmp/test-main — not produced by any in-scope code; orphaned 1.1 GB dir
+ *    on disk from manual integration test (pre-existing, outside parallix/ scope).
+ * 9. Prompt templates (review.md, review-verbose.md, act-on-review.md, etc.) —
+ *    /tmp/{{slug}}-*.md patterns are templates, not actual writes.
+ *
+ * Cleanup strategy: per-process inventory (PER_RUN_SCRATCH) + exit/SIGINT/SIGTERM
+ * handlers (lines 131-141) that remove only tracked dirs. No blanket rm -rf.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fmt from '../core/fmt.js';
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SELF_TEST_FILE = 'coverage-gate.test.js';
+const TEMP_DIR_PREFIXES = [
+  'agents-',
+  'sessions-',
+  'review-',
+  'forgejo-',
+  'workflow-',
+  'gatekeeper-',
+  'graphify-',
+  'claude-',
+  'codex-',
+  'gemini-',
+  'opencode-',
+  'startagent-',
+  'test-',
+  'mission-task-',
+  'visualBoard-task-',
+  'backlog-'
+];
+const COVERAGE_INCLUDES = [
+  'index.js',
+  'lib/**/*.js'
+];
+const COVERAGE_EXCLUDES = [
+  'test/**',
+  'prompts/**',
+  'config/*.json',
+  '.workflow/**',
+  'node_modules/**'
+];
+// The full suite regularly exceeds 10 minutes in this repository, especially
+// under cold caches. Keep the gate generous so it can finish without a manual
+// override while still failing on real hangs.
+const DEFAULT_TEST_TIMEOUT_MS = 3_600_000;
+const PER_RUN_SCRATCH: string[] = [];
+let threshold = 90;
+let dryRun = false;
+let lcov = false;
+let cleanupDone = false;
+
+for (let i = 2; i < process.argv.length; i++) {
+  if (process.argv[i] === '--threshold' && process.argv[i + 1]) {
+    threshold = parseFloat(process.argv[i + 1]);
+    i++;
+  } else if (process.argv[i] === '--dry-run') {
+    dryRun = true;
+  } else if (process.argv[i] === '--lcov') {
+    lcov = true;
+  }
+}
+
+function discoverTestFiles() {
+  const testDir = path.join(REPO_ROOT, 'test');
+  if (!fs.existsSync(testDir)) {return [];}
+  return fs.readdirSync(testDir)
+    .filter(file => file.endsWith('.test.js'))
+    .filter(file => file !== SELF_TEST_FILE)
+    .map(file => path.join(testDir, file))
+    .sort();
+}
+
+function listTempEntries(tmpRoot: string = os.tmpdir()) {
+  if (!fs.existsSync(tmpRoot)) {return new Set<string>();}
+  return new Set(fs.readdirSync(tmpRoot));
+}
+
+function shouldCleanTempDir(name: string) {
+  return TEMP_DIR_PREFIXES.some(prefix => name.startsWith(prefix));
+}
+
+function cleanupNewTempDirs(beforeEntries: Set<string>, tmpRoot: string = os.tmpdir()) {
+  if (!fs.existsSync(tmpRoot)) {return;}
+  for (const name of fs.readdirSync(tmpRoot)) {
+    if (beforeEntries.has(name) || !shouldCleanTempDir(name)) {continue;}
+    const fullPath = path.join(tmpRoot, name);
+    let stat = null;
+    try {
+      stat = fs.statSync(fullPath);
+    } catch (_) {
+      continue;
+    }
+    if (!stat.isDirectory()) {continue;}
+    try {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+    } catch (_) {}
+  }
+}
+
+function createPerRunScratchDirs() {
+  const coverageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'node-coverage-'));
+  PER_RUN_SCRATCH.push(coverageDir);
+  return coverageDir;
+}
+
+function createPerRunTmpRoot() {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'coverage-gate-tmp-'));
+  PER_RUN_SCRATCH.push(tmpRoot);
+  return tmpRoot;
+}
+
+function createMockGraphifyBin() {
+  const graphifyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'graphify-'));
+  PER_RUN_SCRATCH.push(graphifyDir);
+  const graphifyBin = path.join(graphifyDir, 'graphify');
+  fs.writeFileSync(graphifyBin, `#!/usr/bin/env bash
+set -euo pipefail
+if [[ "\${1:-}" == "--help" ]]; then
+  echo "mock graphify"
+  exit 0
+fi
+if [[ "\${1:-}" == "update" ]]; then
+  mkdir -p graphify-out
+  echo '{"nodes":[],"edges":[]}' > graphify-out/graph.json
+  echo '# Mock Graph Report' > graphify-out/GRAPH_REPORT.md
+  echo "[mock graphify] update $*"
+  exit 0
+fi
+echo "Unhandled graphify command: $*" >&2
+exit 1
+`, { mode: 0o755 });
+  return graphifyBin;
+}
+
+function cleanupPerRunScratch() {
+  if (cleanupDone) {return;}
+  cleanupDone = true;
+  for (const dir of PER_RUN_SCRATCH) {
+    try {
+      if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    } catch (_) {}
+  }
+  PER_RUN_SCRATCH.length = 0;
+}
+
+function registerExitHandlers() {
+  process.on('exit', cleanupPerRunScratch);
+  process.on('SIGINT', () => {
+    cleanupPerRunScratch();
+    process.exit(130);
+  });
+  process.on('SIGTERM', () => {
+    cleanupPerRunScratch();
+    process.exit(143);
+  });
+}
+
+function resetPerRunScratchState() {
+  PER_RUN_SCRATCH.length = 0;
+  cleanupDone = false;
+}
+
+function buildCoverageArgs(testFiles: string[], coverageThreshold = threshold, useLcov = lcov) {
+  const args = [
+    '--test',
+    '--experimental-test-coverage',
+    `--test-coverage-lines=${coverageThreshold}`,
+    ...COVERAGE_INCLUDES.flatMap(pattern => ['--test-coverage-include', pattern]),
+    ...COVERAGE_EXCLUDES.flatMap(pattern => ['--test-coverage-exclude', pattern]),
+  ];
+
+  if (useLcov) {
+    const coverageDir = path.join(REPO_ROOT, 'coverage');
+    if (!fs.existsSync(coverageDir)) {
+      fs.mkdirSync(coverageDir, { recursive: true });
+    }
+    args.push('--test-reporter=lcov');
+    args.push(`--test-reporter-destination=${path.join(coverageDir, 'lcov.info')}`);
+    args.push('--test-reporter=spec');
+    args.push('--test-reporter-destination=stdout');
+  }
+
+  args.push(...testFiles);
+  return args;
+}
+
+function resolveTestTimeoutMs(env = process.env) {
+  const raw = env.WORKFLOW_COVERAGE_GATE_TIMEOUT_MS;
+  if (raw === undefined || raw === '') {return DEFAULT_TEST_TIMEOUT_MS;}
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TEST_TIMEOUT_MS;
+}
+
+function runTests(testFiles: string[], coverageThreshold = threshold, _spawnSync = spawnSync) {
+  const tmpRoot = createPerRunTmpRoot();
+  const tmpEntriesBefore = listTempEntries(tmpRoot);
+  const nodeCoverageDir = createPerRunScratchDirs();
+  const childEnv = { ...process.env };
+  delete childEnv.NODE_TEST_CONTEXT;
+  delete childEnv.NODE_OPTIONS;
+  childEnv.TMPDIR = tmpRoot;
+  childEnv.NODE_V8_COVERAGE = nodeCoverageDir;
+  childEnv.GRAPHIFY_BIN = createMockGraphifyBin();
+
+  const result = _spawnSync(process.execPath, buildCoverageArgs(testFiles, coverageThreshold), {
+    encoding: 'utf8',
+    cwd: REPO_ROOT,
+    env: childEnv,
+    stdio: ['pipe', 'inherit', 'inherit'],
+    timeout: resolveTestTimeoutMs(),
+  });
+
+  cleanupNewTempDirs(tmpEntriesBefore, tmpRoot);
+  cleanupPerRunScratch();
+
+  if (result.error) {
+    fmt.log.error(`[coverage-gate] failed to spawn test runner: ${result.error.message}`);
+    return 1;
+  }
+
+  if (result.signal) {
+    fmt.log.error(`[coverage-gate] test runner killed by signal ${result.signal}`);
+    return 1;
+  }
+
+  return result.status === null ? 1 : result.status;
+}
+
+function main() {
+  const testFiles = discoverTestFiles();
+  if (testFiles.length === 0) {
+    fmt.log.fail('no parallix test files found under test/');
+    process.exit(1);
+  }
+
+  fmt.log.info(`Found ${testFiles.length} test file(s)`);
+
+  if (dryRun) {
+    fmt.log.info(`DRY-RUN mode — threshold=${threshold}%`);
+    fmt.log.info('Denominator: index.js + lib/**/*.js');
+    fmt.log.info(`Include globs: ${COVERAGE_INCLUDES.join(', ')}`);
+    fmt.log.info(`Exclude globs: ${COVERAGE_EXCLUDES.join(', ')}`);
+    fmt.log.info(`Would run: ${fmt.command(`${process.execPath} ${buildCoverageArgs(testFiles, threshold).join(' ')}`)}`);
+    process.exit(0);
+  }
+
+  registerExitHandlers();
+  process.exit(runTests(testFiles, threshold));
+}
+
+if (typeof require !== 'undefined' && require.main === module) {
+  main();
+}
+
+interface CoverageGateOptions {
+  exitFn?: (code: number) => void;
+}
+
+function run(args: string[], options: CoverageGateOptions = {}) {
+  const exitFn = options.exitFn || process.exit;
+  let threshold_ = 90;
+  let dryRun_ = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--threshold' && args[i + 1]) {
+      threshold_ = parseFloat(args[i + 1]);
+      i++;
+    } else if (args[i] === '--dry-run') {
+      dryRun_ = true;
+    }
+  }
+  const savedThreshold = threshold;
+  const savedDryRun = dryRun;
+  threshold = threshold_;
+  dryRun = dryRun_;
+  try {
+    if (dryRun_) {
+      const testFiles = discoverTestFiles();
+      if (testFiles.length === 0) {
+        if (typeof exitFn === 'function') {exitFn(1);}
+      } else {
+        fmt.log.info(`Found ${testFiles.length} test file(s)`);
+        fmt.log.info(`DRY-RUN mode — threshold=${threshold}%`);
+        fmt.log.info('Denominator: index.js + lib/**/*.js');
+        fmt.log.info(`Include globs: ${COVERAGE_INCLUDES.join(', ')}`);
+        fmt.log.info(`Exclude globs: ${COVERAGE_EXCLUDES.join(', ')}`);
+        fmt.log.info(`Would run: ${fmt.command(`${process.execPath} ${buildCoverageArgs(testFiles, threshold).join(' ')}`)}`);
+        if (typeof exitFn === 'function') {exitFn(0);}
+        else {process.exit(0);}
+      }
+    } else {
+      registerExitHandlers();
+      exitFn(runTests(discoverTestFiles(), threshold));
+    }
+  } finally {
+    threshold = savedThreshold;
+    dryRun = savedDryRun;
+  }
+}
+
+(run as any).buildCoverageArgs = buildCoverageArgs;
+(run as any).cleanupNewTempDirs = cleanupNewTempDirs;
+(run as any).cleanupPerRunScratch = cleanupPerRunScratch;
+(run as any).createPerRunScratchDirs = createPerRunScratchDirs;
+(run as any).COVERAGE_EXCLUDES = COVERAGE_EXCLUDES;
+(run as any).COVERAGE_INCLUDES = COVERAGE_INCLUDES;
+(run as any).DEFAULT_TEST_TIMEOUT_MS = DEFAULT_TEST_TIMEOUT_MS;
+(run as any).discoverTestFiles = discoverTestFiles;
+(run as any).listTempEntries = listTempEntries;
+(run as any).registerExitHandlers = registerExitHandlers;
+(run as any).resetPerRunScratchState = resetPerRunScratchState;
+(run as any).resolveTestTimeoutMs = resolveTestTimeoutMs;
+(run as any).runTests = runTests;
+(run as any).shouldCleanTempDir = shouldCleanTempDir;
+export = run;

package/lib/commands/diff.js

@@ -1,125 +1,146 @@
-const childProcess = require('child_process');
-const path = require('path');
-const { git } = require('../core/git');
-const { getPrimaryBranch, missionBranchName, inferSlug, resolveWorktree } = require('../core/mission-utils');
-const fmt = require('../core/fmt');
-
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_child_process_1 = __importDefault(require("node:child_process"));
+const node_path_1 = __importDefault(require("node:path"));
+const git_js_1 = require("../core/git.js");
+const mission_utils_js_1 = require("../core/mission-utils.js");
+const fmt = __importStar(require("../core/fmt.js"));
 /** @param {string[]} args @param {{gitFn?: Function, spawnSyncFn?: Function, getPrimaryBranchFn?: Function, missionBranchNameFn?: Function, inferSlugFn?: Function, resolveWorktreeFn?: Function, exitFn?: Function, failFn?: Function}} opts */
-async function diff(args, {
-  gitFn = git,
-  spawnSyncFn = childProcess.spawnSync,
-  getPrimaryBranchFn = getPrimaryBranch,
-  missionBranchNameFn = missionBranchName,
-  inferSlugFn = inferSlug,
-  resolveWorktreeFn = resolveWorktree,
-  exitFn = process.exit,
-  failFn = fmt.log.fail,
-} = {}) {
-  /** @param {string} a */
-  const explicitSlug = args.filter(a => !a.startsWith('--'))[0];
-  const slug = inferSlugFn(explicitSlug);
-
-  if (!slug) {
-    failFn('Usage: node parallix diff [<slug>]');
-    exitFn(1);
-    return;
-  }
-
-  const worktree = resolveWorktreeFn(slug);
-  if (!worktree) {
-    failFn(`Mission worktree not found for ${fmt.slug(slug)}. Run this from the mission worktree or create it first.`);
-    exitFn(1);
-    return;
-  }
-
-  let primary;
-  try {
-    primary = getPrimaryBranchFn(worktree);
-  } catch (err) {
-    failFn(/** @type{Error} */(err).message);
-    exitFn(1);
-    return;
-  }
-
-  const branch = missionBranchNameFn(slug);
-  const target = `${primary}..HEAD`;
-
-  // Detect configured diff tool/pager
-  /** @param {string} key */
-  const getGitConfig = (key) => {
-    const result = gitFn(['-C', worktree, 'config', '--get', key]);
-    return result.status === 0 ? result.stdout.trim() : null;
-  };
-
-  /** @param {string} cmd */
-  const isSpecializedTool = (cmd) => {
-    if (!cmd) {return false;}
-    const parts = cmd.split(/\s+/);
-    // Handle cases like "LESS=FRX less" or "/usr/bin/delta"
-    /** @param {string} p */
-    const exePart = parts.find(p => !p.includes('='));
-    if (!exePart) {return false;}
-    const exe = path.basename(exePart).toLowerCase();
-    
-    // Explicitly reject known default pagers
-    if (['less', 'cat', 'more'].includes(exe)) {return false;}
-    
-    // Accept known specialized tools documented in review-tooling.md
-    if (['delta', 'difft', 'diff-so-fancy'].includes(exe)) {return true;}
-    
-    // Fallback: if it's not a known default, and we have a value, treat it as specialized
-    // for now to avoid breaking custom setups like "vimdiff", but we've rejected plain "less".
-    return true;
-  };
-
-  /** @param {childProcess.SpawnSyncReturns<string>} result @param {string} toolName */
-  const handleLaunchResult = (result, toolName) => {
-    if (result.error) {
-      failFn(`Failed to launch ${toolName}: ${result.error.message}`);
-      exitFn(1);
-      return;
+async function diff(args, { gitFn = git_js_1.git, spawnSyncFn = node_child_process_1.default.spawnSync, getPrimaryBranchFn = mission_utils_js_1.getPrimaryBranch, missionBranchNameFn = mission_utils_js_1.missionBranchName, inferSlugFn = mission_utils_js_1.inferSlug, resolveWorktreeFn = mission_utils_js_1.resolveWorktree, exitFn = process.exit, failFn = fmt.log.fail, } = {}) {
+    /** @param {string} a */
+    const explicitSlug = args.filter((a) => !a.startsWith('--'))[0];
+    const slug = inferSlugFn(explicitSlug);
+    if (!slug) {
+        failFn('Usage: node parallix diff [<slug>]');
+        exitFn(1);
+        return;
+    }
+    const worktree = resolveWorktreeFn(slug);
+    if (!worktree) {
+        failFn(`Mission worktree not found for ${fmt.slug(slug)}. Run this from the mission worktree or create it first.`);
+        exitFn(1);
+        return;
     }
-    if (result.signal) {
-      failFn(`${toolName} terminated by signal: ${result.signal}`);
-      exitFn(1);
-      return;
+    let primary;
+    try {
+        primary = getPrimaryBranchFn(worktree);
     }
-    if (result.status === null) {
-      failFn(`${toolName} exited with unknown status.`);
-      exitFn(1);
-      return;
+    catch (err) {
+        failFn(err.message);
+        exitFn(1);
+        return;
     }
-    exitFn(result.status);
-  };
-
-  const diffTool = getGitConfig('diff.tool');
-  if (diffTool) {
-    fmt.log.info(`Launching ${fmt.command('git difftool')} for ${fmt.branch(branch)} (tool: ${fmt.bold(diffTool)})...`);
-    const result = spawnSyncFn('git', ['difftool', '-d', '--no-prompt', target], { cwd: worktree, stdio: 'inherit' });
-    handleLaunchResult(result, 'git difftool');
-    return;
-  }
-
-  const pagerDiff = getGitConfig('pager.diff');
-  if (isSpecializedTool(pagerDiff)) {
-    fmt.log.info(`Launching ${fmt.command('git diff')} for ${fmt.branch(branch)} (pager: ${fmt.bold(pagerDiff)})...`);
-    const result = spawnSyncFn('git', ['diff', target], { cwd: worktree, stdio: 'inherit' });
-    handleLaunchResult(result, 'git diff');
-    return;
-  }
-
-  const corePager = getGitConfig('core.pager');
-  if (isSpecializedTool(corePager)) {
-    fmt.log.info(`Launching ${fmt.command('git diff')} for ${fmt.branch(branch)} (core.pager: ${fmt.bold(corePager)})...`);
-    const result = spawnSyncFn('git', ['diff', target], { cwd: worktree, stdio: 'inherit' });
-    handleLaunchResult(result, 'git diff');
-    return;
-  }
-
-  failFn('No specialized local diff tool (e.g., delta, difftastic) is configured in Git.');
-  fmt.log.info('The workflow diff command requires an explicitly configured diff.tool or a non-default core.pager.');
-  fmt.log.info(`Refer to ${fmt.path('docs/developer-setup/review-tooling.md')} for setup guidance.`);
-  exitFn(1);
+    const branch = missionBranchNameFn(slug);
+    const target = `${primary}..HEAD`;
+    // Detect configured diff tool/pager
+    /** @param {string} key */
+    const getGitConfig = (key) => {
+        const result = gitFn(['-C', worktree, 'config', '--get', key]);
+        return result.status === 0 ? result.stdout.trim() : null;
+    };
+    /** @param {string} cmd */
+    const isSpecializedTool = (cmd) => {
+        if (!cmd) {
+            return false;
+        }
+        const parts = cmd.split(/\s+/);
+        // Handle cases like "LESS=FRX less" or "/usr/bin/delta"
+        /** @param {string} p */
+        const exePart = parts.find((p) => !p.includes('='));
+        if (!exePart) {
+            return false;
+        }
+        const exe = node_path_1.default.basename(exePart).toLowerCase();
+        // Explicitly reject known default pagers
+        if (['less', 'cat', 'more'].includes(exe)) {
+            return false;
+        }
+        // Accept known specialized tools documented in review-tooling.md
+        if (['delta', 'difft', 'diff-so-fancy'].includes(exe)) {
+            return true;
+        }
+        // Fallback: if it's not a known default, and we have a value, treat it as specialized
+        // for now to avoid breaking custom setups like "vimdiff", but we've rejected plain "less".
+        return true;
+    };
+    /** @param {childProcess.SpawnSyncReturns<string>} result @param {string} toolName */
+    const handleLaunchResult = (result, toolName) => {
+        if (result.error) {
+            failFn(`Failed to launch ${toolName}: ${result.error.message}`);
+            exitFn(1);
+            return;
+        }
+        if (result.signal) {
+            failFn(`${toolName} terminated by signal: ${result.signal}`);
+            exitFn(1);
+            return;
+        }
+        if (result.status === null) {
+            failFn(`${toolName} exited with unknown status.`);
+            exitFn(1);
+            return;
+        }
+        exitFn(result.status);
+    };
+    const diffTool = getGitConfig('diff.tool');
+    if (diffTool) {
+        fmt.log.info(`Launching ${fmt.command('git difftool')} for ${fmt.branch(branch)} (tool: ${fmt.bold(diffTool)})...`);
+        const result = spawnSyncFn('git', ['difftool', '-d', '--no-prompt', target], { cwd: worktree, stdio: 'inherit' });
+        handleLaunchResult(result, 'git difftool');
+        return;
+    }
+    const pagerDiff = getGitConfig('pager.diff');
+    if (isSpecializedTool(pagerDiff || '')) {
+        fmt.log.info(`Launching ${fmt.command('git diff')} for ${fmt.branch(branch)} (pager: ${fmt.bold(pagerDiff || "")})...`);
+        const result = spawnSyncFn('git', ['diff', target], { cwd: worktree, stdio: 'inherit' });
+        handleLaunchResult(result, 'git diff');
+        return;
+    }
+    const corePager = getGitConfig('core.pager');
+    if (isSpecializedTool(corePager || '')) {
+        fmt.log.info(`Launching ${fmt.command('git diff')} for ${fmt.branch(branch)} (core.pager: ${fmt.bold(corePager || "")})...`);
+        const result = spawnSyncFn('git', ['diff', target], { cwd: worktree, stdio: 'inherit' });
+        handleLaunchResult(result, 'git diff');
+        return;
+    }
+    failFn('No specialized local diff tool (e.g., delta, difftastic) is configured in Git.');
+    fmt.log.info('The workflow diff command requires an explicitly configured diff.tool or a non-default core.pager.');
+    fmt.log.info(`Refer to ${fmt.path('docs/developer-setup/review-tooling.md')} for setup guidance.`);
+    exitFn(1);
 }
-
 module.exports = diff;