kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/post-complete/testing.js

@@ -0,0 +1,482 @@
+/**
+ * TESTING — extracted from post-complete.js (D.4 refactor)
+ *
+ * Test suite detection, regression test execution with Cargo lock
+ * contention retry, and regression FIX task creation.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { execTreeSync } = require('../lib/exec-tree');
+const { ROOT, COLLABORATION_API } = require('../utils');
+
+// Dependencies injected from post-complete.js (avoids circular require)
+let _deps = {};
+function initTesting(deps) { _deps = deps; }
+function stripAnsi(s) { return _deps.stripAnsi(s); }
+function sleepSync(ms) { return _deps.sleepSync(ms); }
+
+// ─────────────────────────────────────────
+// Regression Guard constants (PPL-113)
+// ─────────────────────────────────────────
+
+const REGRESSION_TIMEOUT_MS = 120000; // 2 minutes
+// CI=true: vitest/jest run once instead of dropping into watch mode (TASK_2344).
+const REGRESSION_ENV = { ...process.env, CI: 'true' };
+
+// TASK_1150: Cargo lock contention — transient failure detection + retry
+const CARGO_LOCK_CONTENTION_PATTERN = /Blocking waiting for file lock/;
+const CARGO_LOCK_MAX_RETRIES = 2;
+const CARGO_LOCK_BACKOFF_MS = [3000, 6000]; // 3s, then 6s
+
+function isCargoLockContention(output) {
+  return CARGO_LOCK_CONTENTION_PATTERN.test(output);
+}
+
+// ─────────────────────────────────────────
+// TASK_2036: flaky-suite isolation recovery
+// ─────────────────────────────────────────
+// A full `npm test` run can fail with 2 files that pass individually
+// (order/shared-state flakiness in the full suite), which used to
+// auto-open a regression FIX card that had to be cancelled by hand
+// (field report: geo-analyzer TASK_1516, 2026-09-26). Before recording a
+// suite as a real regression, parse the failing test FILE paths out of
+// the runner's own output and rerun just those files, alone, with the
+// same runner. If every one of them passes in isolation, the suite is
+// flaky, not broken — no FIX card.
+
+const ISOLATION_RERUN_MAX_FILES = 10;
+
+/**
+ * Pure parser: extract failing test FILE paths from JS test-runner output.
+ * Supports vitest/jest ("FAIL  <path>" summary lines) and node --test
+ * (top-level, unindented "not ok N - <file>" TAP entries — nested
+ * per-test "not ok" lines are indented and are intentionally not matched).
+ * Returns [] when nothing recognizable is found (never guesses).
+ *
+ * @param {string} output
+ * @returns {string[]} de-duplicated failing file paths, in first-seen order
+ */
+function parseFailingTestFiles(output) {
+  if (!output || typeof output !== 'string') return [];
+
+  const files = [];
+  const seen = new Set();
+  const add = (f) => {
+    if (f && !seen.has(f)) { seen.add(f); files.push(f); }
+  };
+
+  // vitest / jest: " FAIL  <path>" or " FAIL  <path> > <test name>" —
+  // \S+ stops at the first whitespace so the trailing " > test name"
+  // (vitest) is never included.
+  const failLineRe = /^\s*FAIL\s+(\S+)/gm;
+  let m;
+  while ((m = failLineRe.exec(output))) add(m[1]);
+
+  // node --test: top-level (unindented) "not ok N - <file>" TAP entries
+  // whose description itself looks like a test file. Nested per-test
+  // failures are indented under a "# Subtest: <file>" block and are
+  // excluded by the ^ anchor (no leading whitespace) in multiline mode.
+  const nodeTestRe = /^not ok \d+ - (\S+\.(?:test|spec)\.[cm]?[jt]sx?|\S+\.[cm]?[jt]sx?)\s*$/gm;
+  while ((m = nodeTestRe.exec(output))) add(m[1]);
+
+  return files;
+}
+
+/**
+ * Infer which JS test runner produced this suite's output — from the
+ * command first, then output markers. Returns null when unsure (callers
+ * must fall back to today's behaviour rather than guess).
+ * @param {string} cmd
+ * @param {string} output
+ * @returns {'vitest'|'jest'|'node-test'|null}
+ */
+function detectJsRunner(cmd, output) {
+  const c = String(cmd || '').toLowerCase();
+  if (c.includes('vitest')) return 'vitest';
+  if (c.includes('jest')) return 'jest';
+  if (/\bnode\s+(--[\w-]+\s+)*--test\b/.test(cmd || '')) return 'node-test';
+
+  const o = String(output || '');
+  if (/^TAP version 13/m.test(o) || /^not ok \d+ - /m.test(o)) return 'node-test';
+  if (/Failed Tests \d+/.test(o)) return 'vitest';
+  if (/^Test Suites:/m.test(o)) return 'jest';
+  return null;
+}
+
+/**
+ * Build the isolation rerun command for one failing file, same runner.
+ * @returns {string|null}
+ */
+function buildIsolationRerunCmd(runner, file) {
+  const quoted = `"${file}"`;
+  if (runner === 'vitest') return `npx vitest run ${quoted}`;
+  if (runner === 'jest') return `npx jest ${quoted}`;
+  if (runner === 'node-test') return `node --test ${quoted}`;
+  return null;
+}
+
+/**
+ * Rerun each failing file alone (same runner/cwd/timeout) to tell real
+ * regressions apart from full-suite order/shared-state flakiness.
+ *
+ * @param {{cmd: string, cwd: string, label: string}} test
+ * @param {string} output - the failed full-suite run's combined stdout+stderr
+ * @returns {{flaky: true, flakyFiles: string[]}|{flaky: false}|null} null
+ *   means "could not attempt" (unknown runner / nothing parsed / over cap)
+ *   — caller must keep today's failure behaviour unchanged.
+ */
+function attemptFlakyIsolationRecovery(test, output) {
+  const runner = detectJsRunner(test.cmd, output);
+  if (!runner) return null; // unsure which runner — do not guess
+
+  const failingFiles = parseFailingTestFiles(output);
+  if (failingFiles.length === 0) return null; // nothing parsed
+
+  if (failingFiles.length > ISOLATION_RERUN_MAX_FILES) {
+    console.log(`      ⚠️  ${failingFiles.length} failing files exceeds isolation-rerun cap (${ISOLATION_RERUN_MAX_FILES}) — keeping failure verdict`);
+    return null;
+  }
+
+  console.log(`      🔁 Rerunning ${failingFiles.length} failing file(s) in isolation (${runner}) to rule out full-suite flakiness`);
+
+  for (const file of failingFiles) {
+    const rerunCmd = buildIsolationRerunCmd(runner, file);
+    if (!rerunCmd) return null;
+    try {
+      execTreeSync(rerunCmd, {
+        cwd: test.cwd,
+        timeout: REGRESSION_TIMEOUT_MS,
+        env: REGRESSION_ENV,
+      });
+    } catch {
+      // Still fails alone — a real regression, not flakiness.
+      return { flaky: false };
+    }
+  }
+
+  return { flaky: true, flakyFiles: failingFiles };
+}
+
+/**
+ * 偵測專案所有可用的測試套件（Fallback 用）
+ * Agent 未指定 --test-cmd 時，自動偵測並回傳所有找到的測試。
+ *
+ * B13: scope-aware filtering. Rust tests force a full cargo build which on
+ * Windows hits the kuzu cmake build script — slow and intermittently broken
+ * by environment issues unrelated to the task. Skip Rust suites entirely
+ * when scope_paths gives no reason to believe Rust source was touched.
+ * Agents that explicitly need Rust coverage can pass --test-cmd.
+ *
+ * @param {string} projectRoot - 專案根目錄
+ * @param {string[]} [scopePaths] - 任務 scope_paths（用於 selective Rust skip）
+ * @returns {{ cmd: string, cwd: string, label: string }[]}
+ */
+function detectAllTestCommands(projectRoot, scopePaths = []) {
+  const commands = [];
+  const normScopes = (scopePaths || []).map(p => p.replace(/\\/g, '/'));
+  const scopeTouches = (prefix) => normScopes.some(s => s === prefix || s.startsWith(prefix + '/') || prefix.startsWith(s + '/'));
+
+  // 1. Dashboard (dashboard/package.json) — React/TS
+  const dashPkg = path.join(projectRoot, 'dashboard', 'package.json');
+  if (fs.existsSync(dashPkg)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(dashPkg, 'utf8'));
+      const testScript = pkg.scripts?.test;
+      if (testScript && !testScript.includes('echo "Error')) {
+        commands.push({ cmd: 'npm test -- --passWithNoTests', cwd: path.join(projectRoot, 'dashboard'), label: 'dashboard (npm test)' });
+      }
+    } catch { /* skip */ }
+  }
+
+  // 2. Root package.json
+  const rootPkg = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(rootPkg)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(rootPkg, 'utf8'));
+      const testScript = pkg.scripts?.test;
+      if (testScript && !testScript.includes('echo "Error')) {
+        commands.push({ cmd: 'npm test -- --passWithNoTests', cwd: projectRoot, label: 'root (npm test)' });
+      }
+    } catch { /* skip */ }
+  }
+
+  // 3. Rust: dashboard/src-tauri/ — only when scope explicitly touches it.
+  // The cargo build pulls kuzu via cmake which is the dominant source of
+  // false-positive regression failures observed in this project (~every
+  // dispatch reported "src-tauri tests FAILED" with cmake exit 2). Empty
+  // scope_paths means memory-only / smoke / non-source task → skip Rust.
+  // Agents that explicitly need Rust coverage can pass --test-cmd.
+  const tauriCargo = path.join(projectRoot, 'dashboard', 'src-tauri', 'Cargo.toml');
+  if (fs.existsSync(tauriCargo) && scopeTouches('dashboard/src-tauri')) {
+    commands.push({ cmd: 'cargo test --bin kenaz-dashboard', cwd: path.join(projectRoot, 'dashboard', 'src-tauri'), label: 'src-tauri (cargo test)' });
+  }
+
+  // 4. Rust: dashboard/pty-server/ — same selective rule
+  const ptyCargo = path.join(projectRoot, 'dashboard', 'pty-server', 'Cargo.toml');
+  if (fs.existsSync(ptyCargo) && scopeTouches('dashboard/pty-server')) {
+    commands.push({ cmd: 'cargo test', cwd: path.join(projectRoot, 'dashboard', 'pty-server'), label: 'pty-server (cargo test)' });
+  }
+
+  // 5. Python (pytest) — root level
+  const pytestFiles = ['pytest.ini', 'pyproject.toml', 'setup.cfg'];
+  for (const f of pytestFiles) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      try {
+        const content = fs.readFileSync(path.join(projectRoot, f), 'utf8');
+        if (f === 'pytest.ini' || content.includes('[tool.pytest') || content.includes('[pytest]')) {
+          commands.push({ cmd: 'pytest --timeout=60 -x', cwd: projectRoot, label: 'root (pytest)' });
+          break; // 只加一次
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  // 6. kenaz-cortex (Python sub-project)
+  const cortexPytest = path.join(projectRoot, 'kenaz-cortex', 'pytest.ini');
+  const cortexPyproject = path.join(projectRoot, 'kenaz-cortex', 'pyproject.toml');
+  if (fs.existsSync(cortexPytest) || fs.existsSync(cortexPyproject)) {
+    commands.push({ cmd: 'pytest --timeout=60 -x', cwd: path.join(projectRoot, 'kenaz-cortex'), label: 'kenaz-cortex (pytest)' });
+  }
+
+  return commands;
+}
+
+/**
+ * 執行回歸測試（PPL-113 Agent+Script 協作模型）
+ *
+ * 優先使用 Agent 透過 --test-cmd 指定的測試指令；
+ * 若 Agent 未指定，fallback 到 detectAllTestCommands 自動偵測。
+ * 依序執行所有測試套件，記錄每組結果。
+ *
+ * @param {string} projectRoot
+ * @param {string[]} [agentTestCmds] - Agent 指定的測試指令（shell commands）
+ * @returns {{ passed: boolean, skipped: boolean, output: string, results: object[] }}
+ */
+function runRegressionTests(projectRoot, agentTestCmds, scopePaths = []) {
+  let commands = [];
+
+  if (agentTestCmds && agentTestCmds.length > 0) {
+    console.log('   🤖 Using Agent-specified test commands');
+    commands = agentTestCmds.map(cmd => ({ cmd, cwd: projectRoot, label: cmd }));
+  } else {
+    console.log('   🔍 Auto-detecting test suites (fallback)');
+    commands = detectAllTestCommands(projectRoot, scopePaths);
+  }
+
+  if (commands.length === 0) {
+    return { passed: true, skipped: true, output: 'No test configuration detected — skipped', results: [] };
+  }
+
+  console.log(`   📋 ${commands.length} test suite(s) to run`);
+
+  const results = [];
+  let allPassed = true;
+  let combinedOutput = '';
+  let skipVerdict = false;
+  let skipVerdictReason = '';
+
+  for (const test of commands) {
+    console.log(`\n   🧪 [${test.label}]`);
+    console.log(`      cmd: ${test.cmd}`);
+    console.log(`      cwd: ${test.cwd}`);
+
+    try {
+      const output = execTreeSync(test.cmd, {
+        cwd: test.cwd,
+        timeout: REGRESSION_TIMEOUT_MS,
+        env: REGRESSION_ENV,
+      });
+      results.push({ label: test.label, cmd: test.cmd, passed: true, output });
+      combinedOutput += `=== ${test.label} === PASSED ===\n${output}\n`;
+      console.log(`      ✅ Passed`);
+    } catch (e) {
+      const output = (e.stdout || '') + '\n' + (e.stderr || '');
+      const timedOut = !!e.killed;
+
+      // TASK_1150: Cargo lock contention is a transient infrastructure issue — retry.
+      if (!timedOut && isCargoLockContention(output)) {
+        let retryOutput = output;
+        let retryPassed = false;
+        let stillTransient = true;
+
+        for (let attempt = 0; attempt < CARGO_LOCK_MAX_RETRIES; attempt++) {
+          const backoffMs = CARGO_LOCK_BACKOFF_MS[attempt] || 6000;
+          console.log(`      ⏳ Cargo lock contention — retrying in ${backoffMs / 1000}s (attempt ${attempt + 1}/${CARGO_LOCK_MAX_RETRIES})`);
+          sleepSync(backoffMs);
+          try {
+            retryOutput = execTreeSync(test.cmd, {
+              cwd: test.cwd,
+              timeout: REGRESSION_TIMEOUT_MS,
+              env: REGRESSION_ENV,
+            });
+            retryPassed = true;
+            stillTransient = false;
+            break;
+          } catch (retryErr) {
+            retryOutput = (retryErr.stdout || '') + '\n' + (retryErr.stderr || '');
+            if (!isCargoLockContention(retryOutput)) {
+              stillTransient = false;
+              break; // Real failure — stop retrying
+            }
+          }
+        }
+
+        if (retryPassed) {
+          results.push({ label: test.label, cmd: test.cmd, passed: true, output: retryOutput });
+          combinedOutput += `=== ${test.label} === PASSED (cargo lock retry) ===\n${retryOutput}\n`;
+          console.log(`      ✅ Passed (after cargo lock retry)`);
+        } else if (stillTransient) {
+          // Cargo lock persists after all retries — transient infra issue, skip verdict
+          console.log(`      ⚠️  Cargo lock contention persists after ${CARGO_LOCK_MAX_RETRIES} retries — skipping verdict`);
+          results.push({ label: test.label, cmd: test.cmd, passed: true, skipped: true, transient: 'cargo-lock', output: retryOutput });
+          combinedOutput += `=== ${test.label} === SKIPPED (cargo lock contention) ===\n${retryOutput}\n`;
+          skipVerdict = true;
+          skipVerdictReason = `Cargo lock contention persisted for ${test.label} after ${CARGO_LOCK_MAX_RETRIES} retries`;
+        } else {
+          // Real failure surfaced during retry
+          results.push({ label: test.label, cmd: test.cmd, passed: false, timedOut: false, output: retryOutput });
+          combinedOutput += `=== ${test.label} === FAILED ===\n${retryOutput}\n`;
+          allPassed = false;
+          console.log(`      ❌ Failed`);
+        }
+        continue;
+      }
+
+      // TASK_2036: before recording a real regression, check whether this
+      // is full-suite order/shared-state flakiness — rerun the failing
+      // files alone. Timeouts are excluded (cargo retry path above is the
+      // only special-cased transient failure; a hung run isn't "flaky").
+      if (!timedOut) {
+        const flakyResult = attemptFlakyIsolationRecovery(test, output);
+        if (flakyResult && flakyResult.flaky) {
+          results.push({ label: test.label, cmd: test.cmd, passed: true, flaky: true, flakyFiles: flakyResult.flakyFiles, output });
+          combinedOutput += `=== ${test.label} === PASSED (flaky — passed in isolation: ${flakyResult.flakyFiles.join(', ')}) ===\n${output}\n`;
+          console.log(`      ⚠️  Flaky suite — ${flakyResult.flakyFiles.length} failing file(s) passed in isolation, no regression FIX card: ${flakyResult.flakyFiles.join(', ')}`);
+          continue;
+        }
+      }
+
+      results.push({ label: test.label, cmd: test.cmd, passed: false, timedOut, output });
+      combinedOutput += `=== ${test.label} === FAILED ===\n${output}\n`;
+      allPassed = false;
+      console.log(timedOut ? `      ❌ Timed out (${REGRESSION_TIMEOUT_MS / 1000}s)` : `      ❌ Failed`);
+    }
+  }
+
+  return { passed: allPassed, skipped: false, output: combinedOutput, results, skipVerdict, skipVerdictReason };
+}
+
+/**
+ * 檢查是否已存在未解決的 regression FIX 任務
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+function hasOpenRegressionFixTask(projectPath) {
+  const apiArgs = [];
+  if (projectPath) apiArgs.push('--project-path', projectPath);
+  apiArgs.push('list', '--tags', 'regression', '--format', 'json');
+
+  try {
+    const result = spawnSync('node', [COLLABORATION_API, ...apiArgs], {
+      encoding: 'utf8',
+      timeout: 10000,
+      cwd: ROOT, windowsHide: true
+    });
+    const data = JSON.parse(result.stdout || '{}');
+    const tasks = data.tasks || [];
+    // 有任何非 cancel/done 狀態的 regression 任務就算存在
+    return tasks.some(t =>
+      t.tags?.includes('regression') && !['cancel', 'done'].includes(t.status)
+    );
+  } catch {
+    return false; // 查詢失敗 → 不阻止建立
+  }
+}
+
+/**
+ * 測試失敗時建立 FIX 任務（閉環）
+ * @param {string} taskId - 原始任務 ID
+ * @param {string} testOutput - 測試失敗輸出
+ * @param {string} [projectPath]
+ * @returns {string|null} 建立的 FIX 任務 ID，或 'DUPLICATE' 表示已存在
+ */
+function createRegressionFixTask(taskId, testOutput, projectPath) {
+  // 防重複：如已有未解決的 regression FIX 任務，不再建立
+  if (hasOpenRegressionFixTask(projectPath)) {
+    console.log('   ℹ️  Regression FIX task already exists — skipping duplicate creation');
+    return 'DUPLICATE';
+  }
+
+  // 取失敗摘要（最後 30 行），去除 ANSI 顏色碼
+  const lines = testOutput.trim().split('\n');
+  const summary = stripAnsi(lines.slice(-30).join('\n'));
+
+  const title = `[FIX] ${taskId}: 回歸測試失敗 — 修復破壞的測試`;
+  const description = `任務 ${taskId} 完成後，回歸測試（PPL-113）偵測到既有測試失敗。需修復被破壞的功能。\n\n測試輸出摘要：\n${summary}`;
+
+  const apiArgs = [];
+  if (projectPath) apiArgs.push('--project-path', projectPath);
+  apiArgs.push(
+    'create',
+    '--title', title,
+    '--description', description,
+    '--priority', 'P1',
+    '--role', 'developer',
+    '--complexity', 'simple',
+    '--tags', 'fix,regression',
+    '--dependencies', taskId,
+    '--estimated-hours', '0.5',
+    '--requirements', `修復 ${taskId} 導致的回歸測試失敗`,
+    '--requirements', '確認所有既有測試通過（npm test）',
+    '--requirements', '不引入新的測試失敗',
+    '--acceptance-criteria', '回歸測試全數通過',
+    '--acceptance-criteria', '原任務功能不受影響',
+    '--acceptance-criteria', 'post-complete 流程可正常完成',
+    '--notes', `PPL-113 回歸測試失敗觸發\n失敗輸出：\n${summary.slice(0, 500)}`,
+    '--force',
+  );
+
+  try {
+    const result = spawnSync('node', [COLLABORATION_API, ...apiArgs], {
+      encoding: 'utf8',
+      timeout: 15000,
+      cwd: ROOT, windowsHide: true
+    });
+
+    const stdout = result.stdout || '';
+    const idMatch = stdout.match(/TASK_\d+/);
+    const fixTaskId = idMatch ? idMatch[0] : null;
+
+    // 寫入 FIX queue — dispatch/headless close handler 會讀取並自動 re-dispatch
+    if (fixTaskId) {
+      try {
+        const queueFile = path.join(ROOT, '.formation', '.fix-queue.json');
+        fs.writeFileSync(queueFile, JSON.stringify({
+          fixTaskId,
+          sourceTaskId: taskId,
+          createdAt: new Date().toISOString(),
+        }));
+      } catch { /* ignore */ }
+    }
+
+    return fixTaskId;
+  } catch (e) {
+    console.log(`   ⚠️  Failed to create fix task: ${e.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  initTesting,
+  detectAllTestCommands,
+  runRegressionTests,
+  hasOpenRegressionFixTask,
+  createRegressionFixTask,
+  // TASK_2036: exported for unit testing
+  parseFailingTestFiles,
+  detectJsRunner,
+  buildIsolationRerunCmd,
+  attemptFlakyIsolationRecovery,
+};

package/core/.formation/tools/post-complete/wish.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * AUTO_WISH — TASK_1997 R3
+ *
+ * When a task's derived outcome is `failed` or it ends up in `blocked/`,
+ * file a Wishing Well wish so the failure surfaces on the backlog instead
+ * of only living in git history. Fire-and-forget: never throws, never
+ * delays post-complete. Deduped by task_id (or a `${taskId} ` content
+ * prefix) so a task that fails a fix-cycle repeatedly doesn't spam the
+ * Wishing Well. Opt-out: KENAZ_NO_AUTO_WISH=1.
+ */
+
+const { postJson, getJson } = require('./bounded-http');
+
+const WISH_LIST_PATH = '/api/wishes/list';
+const WISH_CREATE_PATH = '/api/wishes/create';
+const DEFAULT_TIMEOUT_MS = 3000;
+const TITLE_MAX = 80;
+const REASON_MAX = 200;
+
+/**
+ * TASK_2040 — failure classes that are Kenaz's own machinery breaking
+ * (merge/branch/scope plumbing in git-merge.js / post-complete.js), as
+ * opposed to a task simply failing on its own merits (e.g. a failed
+ * verify/build/test in the sub-project's own work). Auto-wish must only
+ * fire for the former — the elixir mandate is "failed/blocked BECAUSE of
+ * the app", not "failed for any reason". Sourced from the actual
+ * failure_reason/blockedReason string literals set in git-merge.js and
+ * post-complete.js (grep for them there before changing this list).
+ */
+const KENAZ_MACHINERY_FAILURE_REASONS = [
+  'merge_conflict',
+  'worktree_missing',
+  'ambiguous_task_branch',
+  'unmerged_index',
+  'checkout_blocked',
+];
+
+/**
+ * True only when a post-complete gitResult reflects Kenaz's own
+ * merge/branch/scope machinery failing, not the task's own work failing.
+ * Best-effort / defensive — never throws.
+ * @param {object|null} gitResult
+ * @returns {boolean}
+ */
+function isKenazMachineryFailure(gitResult) {
+  if (!gitResult) return false;
+  if (gitResult.mergeConflict) return true;
+  if (gitResult.missingTaskBranch) return true;
+  if (gitResult.scopePathsMissing) return true;
+  if (gitResult.gitException) return true;
+  const reason = gitResult.failure_reason || gitResult.blockedReason;
+  return typeof reason === 'string' && KENAZ_MACHINERY_FAILURE_REASONS.includes(reason);
+}
+
+/**
+ * @param {object[]} wishes
+ * @param {string} taskId
+ * @returns {object|null} the first duplicate wish, or null
+ */
+function findDuplicateWish(wishes, taskId) {
+  if (!Array.isArray(wishes) || !taskId) return null;
+  const prefix = `${taskId} `;
+  return wishes.find((w) => w && (
+    w.task_id === taskId ||
+    (typeof w.content === 'string' && w.content.startsWith(prefix))
+  )) || null;
+}
+
+/**
+ * Derive a short human-readable failure reason from a post-complete
+ * gitResult, for the wish content. Best-effort — never throws.
+ * @param {object|null} gitResult
+ * @param {'failed'|'blocked'|'done'} taskOutcome
+ */
+function deriveWishReason(gitResult, taskOutcome) {
+  if (gitResult) {
+    if (gitResult.mergeConflict) return 'merge conflict';
+    if (gitResult.missingTaskBranch) return 'missing task branch';
+    if (gitResult.scopePathsMissing) return 'scope paths missing';
+    if (gitResult.failure_reason) return String(gitResult.failure_reason);
+    if (gitResult.gitException) return String(gitResult.gitException);
+  }
+  return taskOutcome === 'blocked' ? 'blocked' : 'task did not complete (verify/merge did not land)';
+}
+
+/**
+ * File an auto-wish for a failed/blocked task, deduped by task_id.
+ * Fire-and-forget: resolves to a status object, never rejects.
+ *
+ * @param {object} args
+ * @param {string} args.taskId
+ * @param {string} [args.title]
+ * @param {string} [args.reason]
+ * @param {string} [args.projectPath]
+ * @param {object} [args.gitResult] - TASK_2040: gates filing to Kenaz-machinery failures only
+ * @param {object} [deps] - injectable for tests
+ * @param {function} [deps.post] - defaults to bounded-http postJson
+ * @param {function} [deps.list] - defaults to bounded-http getJson
+ * @param {number} [deps.timeoutMs]
+ * @param {function} [deps.log] - defaults to console.log
+ */
+async function maybeFileAutoWish(args, deps = {}) {
+  const { taskId, title, reason, projectPath, gitResult } = args || {};
+  const {
+    post = postJson,
+    list = getJson,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    log = console.log,
+  } = deps;
+
+  if (!taskId) return { filed: false, reason: 'no_task_id' };
+
+  if (process.env.KENAZ_NO_AUTO_WISH === '1') {
+    log('   🪄 auto-wish skipped: KENAZ_NO_AUTO_WISH=1');
+    return { filed: false, reason: 'opted_out' };
+  }
+
+  // TASK_2040: only Kenaz's own machinery failing (merge/branch/scope
+  // plumbing) is worth an auto-wish. A task failing on its own merits
+  // (e.g. sub-project verify/build/test failure) is that project's own
+  // work, not a Kenaz complaint — skip it.
+  if (!isKenazMachineryFailure(gitResult)) {
+    log('   🪄 auto-wish skipped: not_kenaz_failure');
+    return { filed: false, reason: 'not_kenaz_failure' };
+  }
+
+  // Dedupe check — best-effort. A failed/unavailable list check does not
+  // block filing: if the backend is genuinely down the create call below
+  // will fail too, so there is no real duplicate-creation risk.
+  try {
+    const listResp = await list({ path: WISH_LIST_PATH }, { timeoutMs });
+    if (listResp && listResp.ok && listResp.data && Array.isArray(listResp.data.data)) {
+      const dup = findDuplicateWish(listResp.data.data, taskId);
+      if (dup) {
+        log(`   🪄 auto-wish skipped: duplicate (${dup.id || 'existing'})`);
+        return { filed: false, reason: 'duplicate', existingId: dup.id };
+      }
+    }
+  } catch { /* dedupe check is best-effort — proceed to create */ }
+
+  const safeTitle = String(title || '').slice(0, TITLE_MAX);
+  const safeReason = String(reason || '').slice(0, REASON_MAX);
+  const content = `${taskId} ${safeTitle} failed: ${safeReason}`;
+  const payload = {
+    content,
+    wish_type: 'bug',
+    priority: 'medium',
+    source: 'ansuz-auto',
+    task_id: taskId,
+    scope: 'kenaz',
+    ...(projectPath ? { project_path: projectPath } : {}),
+  };
+
+  try {
+    const resp = await post({ path: WISH_CREATE_PATH }, payload, { timeoutMs });
+    if (resp && resp.ok && resp.data && resp.data.success && resp.data.data && resp.data.data.id) {
+      log(`   🪄 auto-wish filed: ${resp.data.data.id}`);
+      return { filed: true, id: resp.data.data.id };
+    }
+    const failReason = (resp && resp.reason) || (resp && resp.data && resp.data.error) || 'unknown';
+    log(`   🪄 auto-wish skipped: ${failReason}`);
+    return { filed: false, reason: failReason };
+  } catch (e) {
+    log(`   🪄 auto-wish skipped: ${e.message}`);
+    return { filed: false, reason: 'exception' };
+  }
+}
+
+module.exports = {
+  maybeFileAutoWish,
+  findDuplicateWish,
+  deriveWishReason,
+  isKenazMachineryFailure,
+  KENAZ_MACHINERY_FAILURE_REASONS,
+};