karajan-code 2.34.0 → 3.1.0

package/src/review/git-stash-helper.js

@@ -0,0 +1,104 @@
+// Surgical stash helper for the TDD discipline gate (KJC-TSK-0398 PR2).
+// Stashes only the source files we want to hide for the "red" run and
+// restores them afterwards. Tracked files use `git stash push -- <paths>`;
+// untracked files (not yet known to git) are moved aside to a private
+// `.karajan/tmp/stash-<id>/` tree because `git stash` would ignore them.
+
+import { mkdir, rename, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+function defaultRunner(cmd, args, opts) {
+  return runCommand(cmd, args, opts);
+}
+
+async function isTracked(runner, projectDir, file) {
+  const res = await runner("git", ["ls-files", "--error-unmatch", "--", file], { cwd: projectDir });
+  return res.exitCode === 0;
+}
+
+async function stashRefForToken(runner, projectDir, marker) {
+  const res = await runner("git", ["stash", "list"], { cwd: projectDir });
+  if (res.exitCode !== 0) return null;
+  for (const line of String(res.stdout || "").split("\n")) {
+    if (line.includes(marker)) {
+      const m = line.match(/^(stash@\{\d+\})/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+// Move `files` aside so a test run sees them as missing. Returns a token to
+// pass to `restoreFiles()`. Throws on failure with the partial token attached.
+export async function stashFilesAside(files, { projectDir = process.cwd(), runner = defaultRunner, tmpRoot } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return { trackedStashRef: null, untrackedMoves: [], marker: null };
+  }
+  const tracked = [];
+  const untracked = [];
+  for (const f of files) {
+    if (await isTracked(runner, projectDir, f)) tracked.push(f);
+    else if (existsSync(resolve(projectDir, f))) untracked.push(f);
+  }
+
+  const marker = `kj-tdd-discipline-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const stashRoot = tmpRoot || join(projectDir, ".karajan", "tmp", marker);
+  const untrackedMoves = [];
+  let trackedStashRef = null;
+
+  if (tracked.length > 0) {
+    const args = ["stash", "push", "--keep-index", "-m", marker, "--", ...tracked];
+    const res = await runner("git", args, { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash push failed: ${res.stderr || res.stdout}`);
+    }
+    trackedStashRef = await stashRefForToken(runner, projectDir, marker);
+  }
+
+  for (const f of untracked) {
+    const src = resolve(projectDir, f);
+    const dst = join(stashRoot, f);
+    await mkdir(dirname(dst), { recursive: true });
+    await rename(src, dst);
+    untrackedMoves.push({ src, dst });
+  }
+
+  return { trackedStashRef, untrackedMoves, marker, stashRoot };
+}
+
+// Reverse a `stashFilesAside` token. Idempotent: a restored token becomes a no-op.
+export async function restoreFiles(token, { projectDir = process.cwd(), runner = defaultRunner } = {}) {
+  if (!token || (token.trackedStashRef == null && token.untrackedMoves.length === 0)) return;
+
+  for (const { src, dst } of token.untrackedMoves) {
+    if (existsSync(dst)) {
+      await mkdir(dirname(src), { recursive: true });
+      await rename(dst, src);
+    }
+  }
+  if (token.stashRoot && existsSync(token.stashRoot)) {
+    await rm(token.stashRoot, { recursive: true, force: true });
+  }
+
+  if (token.trackedStashRef) {
+    const res = await runner("git", ["stash", "pop", token.trackedStashRef], { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash pop failed: ${res.stderr || res.stdout}`);
+    }
+  }
+  token.trackedStashRef = null;
+  token.untrackedMoves = [];
+}
+
+// Run `body` with `files` stashed aside, always restoring them — even when
+// `body` throws. The TDD discipline stage wraps its "red" run with this.
+export async function withStashedFiles(files, body, opts = {}) {
+  const token = await stashFilesAside(files, opts);
+  try {
+    return await body(token);
+  } finally {
+    await restoreFiles(token, opts).catch(() => { /* swallow: surface body error */ });
+  }
+}

package/src/review/tdd-discipline.js

@@ -0,0 +1,90 @@
+// TDD discipline gate (KJC-TSK-0398 PR1).
+// PR1 ships the pure decision logic with injected runTests/stashFiles
+// helpers. PR2 ships the real surgical stash. PR3 wires the gate into
+// the pipeline behind `development.require_red_then_green`.
+
+const PARSERS = {
+  vitest: parseVitestFailures,
+  jest: parseVitestFailures,
+  pytest: parsePytestFailures,
+};
+
+function parseVitestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^\s*(?:FAIL|×|✖)\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function parsePytestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^FAILED\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function anyNewTestIn(failures, testFiles) {
+  return [...failures].some((f) => testFiles.some((t) => f.includes(t) || t.includes(f)));
+}
+
+export async function verifyTddDiscipline({
+  projectDir,
+  sourceFiles = [],
+  testFiles = [],
+  framework = null,
+  runTests,
+  stashFiles,
+  restoreFiles,
+} = {}) {
+  if (sourceFiles.length === 0) {
+    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
+  }
+  if (testFiles.length === 0) {
+    return { ok: true, reason: "no_test_changes", sourceFiles, testFiles };
+  }
+
+  const parser = framework ? PARSERS[framework] : null;
+  if (!parser) {
+    return {
+      ok: true,
+      reason: "framework_unsupported",
+      sourceFiles,
+      testFiles,
+      warning: `tdd-discipline: framework "${framework || "unknown"}" has no failure parser; gate skipped`,
+    };
+  }
+
+  let stashToken = null;
+  try {
+    stashToken = await stashFiles(sourceFiles);
+    const before = await runTests(projectDir);
+    if (!anyNewTestIn(parser(before.output), testFiles)) {
+      return {
+        ok: false,
+        reason: "tests_pass_without_impl",
+        sourceFiles,
+        testFiles,
+        message:
+          "TDD discipline violation: new tests pass without the implementation. Tests must fail first (red), then pass (green).",
+      };
+    }
+  } finally {
+    if (stashToken) await restoreFiles(stashToken);
+  }
+
+  const after = await runTests(projectDir);
+  if (anyNewTestIn(parser(after.output), testFiles)) {
+    return {
+      ok: false,
+      reason: "tests_fail_with_impl",
+      sourceFiles,
+      testFiles,
+      message: "TDD discipline violation: new tests still fail with the implementation present.",
+    };
+  }
+  return { ok: true, reason: "red_then_green_verified", sourceFiles, testFiles };
+}

package/src/roles/audit-role.js

@@ -8,6 +8,7 @@ import { collectOsvFindings } from "../audit/osv-findings.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
+import { collectInjectionFindings } from "../audit/injection-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -51,6 +52,7 @@ export class AuditRole extends AgentRole {
     const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
     const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
     const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
+    const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -61,6 +63,7 @@ export class AuditRole extends AgentRole {
     let semgrepFindings = null;
     let circularDeps = null;
     let deadExports = null;
+    let injectionFindings = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -108,7 +111,12 @@ export class AuditRole extends AgentRole {
         deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
       } catch { /* knip is best-effort */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports };
+    if (!noInjectionScan) {
+      try {
+        injectionFindings = await collectInjectionFindings(projectDir, this.logger);
+      } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings };
   }
 
   /**

package/src/roles/tool-correctness-judge-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0375 — ToolCorrectnessJudgeRole.
+// Post-iteration LLM judge scoring how well a coder picked its tool calls.
+// PR1 ships role + tests; wiring lives in PR3.
+
+import { AgentRole } from "./agent-role.js";
+import { buildToolCorrectnessJudgePrompt } from "../prompts/tool-correctness-judge.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const DEFAULT_THRESHOLD = 70;
+
+const clampScore = (n) => Number.isFinite(n) ? Math.max(0, Math.min(100, Math.round(n))) : null;
+
+const normalizeBreakdown = (b) => Array.isArray(b) ? b.map((x) => ({
+  tool: typeof x?.tool === "string" ? x.tool : "unknown",
+  args: x?.args && typeof x.args === "object" ? x.args : {},
+  correct: Boolean(x?.correct),
+  reason: typeof x?.reason === "string" ? x.reason.trim() : "",
+})) : [];
+
+export class ToolCorrectnessJudgeRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tool-correctness-judge" });
+    this.threshold = opts?.threshold ?? this.config?.pipeline?.tool_judge?.threshold ?? DEFAULT_THRESHOLD;
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.["tool-correctness-judge"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.roles?.coder?.provider
+      || "claude";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), toolCalls: Array.isArray(input?.toolCalls) ? input.toolCalls : [] };
+  }
+
+  async buildPrompt({ task, toolCalls }) {
+    return { prompt: buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const score = clampScore(parsed?.score);
+    return {
+      score,
+      summary: typeof parsed?.summary === "string" ? parsed.summary.trim() : "",
+      breakdown: normalizeBreakdown(parsed?.breakdown),
+      threshold: this.threshold,
+      lowQuality: score !== null && score < this.threshold,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const score = clampScore(parsed?.score);
+    if (score === null) return "Tool-judge: unparseable score";
+    return `Tool-judge: ${score}/100 (${score < this.threshold ? "LOW" : "OK"})`;
+  }
+
+  // Empty tool-call list = nothing to judge. Skip the LLM and report a
+  // neutral score so an absent transcript is never read as a failure.
+  async execute(input) {
+    const extracted = this.extractInput(input);
+    if (extracted.toolCalls.length === 0) {
+      return {
+        ok: true,
+        result: {
+          score: null, summary: "no tool calls captured (skipped)", breakdown: [],
+          threshold: this.threshold, lowQuality: false, provider: this.resolveProvider(), skipped: true,
+        },
+        summary: "Tool-judge: skipped (no calls)",
+        usage: null,
+      };
+    }
+    return super.execute(extracted);
+  }
+}

package/src/session/mutators.js

@@ -109,6 +109,10 @@ export function setSonarSummary(session, text) {
   session.last_sonar_summary = text;
 }
 
+export function setCoderTranscript(session, text) {
+  session.last_coder_transcript = text;
+}
+
 export function setSonarIssueSignature(session, sig) {
   session.last_sonar_issue_signature = sig;
 }

package/src/sonar/scanner.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
 import { runCommand } from "../utils/process.js";
 import { sonarUp } from "./manager.js";
 import { resolveSonarProjectKey } from "./project-key.js";
@@ -10,6 +11,32 @@ import {
   resolveSonarCredentials,
 } from "./config-resolver.js";
 
+export async function findNativeSonarScanner() {
+  const which = await runCommand("sh", ["-c", "command -v sonar-scanner"]);
+  if (which.exitCode === 0) {
+    const bin = String(which.stdout || "").trim();
+    if (bin) return bin;
+  }
+  return null;
+}
+
+export async function pickSonarScanner(scannerConfig = {}, deps = {}) {
+  const find = deps.findNativeSonarScanner || findNativeSonarScanner;
+  const arch = deps.arch || os.arch();
+  const forced = String(scannerConfig.command || "").trim().toLowerCase();
+  if (forced === "docker") return { type: "docker" };
+  if (forced === "native" || forced === "sonar-scanner" || forced.endsWith("/sonar-scanner")) {
+    const bin = (forced === "native" || forced === "sonar-scanner") ? await find() : forced;
+    if (bin) return { type: "native", bin };
+    return { type: "docker", reason: "native sonar-scanner not found on PATH" };
+  }
+  if (arch === "arm64") {
+    const bin = await find();
+    if (bin) return { type: "native", bin, reason: "ARM64 host — preferring native binary" };
+  }
+  return { type: "docker" };
+}
+
 export function buildScannerOpts(projectKey, scanner = {}) {
   const opts = [`-Dsonar.projectKey=${projectKey}`];
   if (scanner.sources) opts.push(`-Dsonar.sources=${scanner.sources}`);
@@ -236,31 +263,39 @@ export async function runSonarScan(config, projectKey = null) {
     ...coverage.scannerPatch
   });
 
-  const args = [
-    "run",
-    "--rm",
-    "-v",
-    `${process.cwd()}:/usr/src`,
-    ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
-    ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
-    "-e", "SONAR_HOST_URL",
-    "-e", "SONAR_TOKEN",
-    "-e", "SONAR_SCANNER_OPTS",
-    "sonarsource/sonar-scanner-cli"
-  ];
-
-  // Pass secrets via process env, not CLI args — invisible in `ps aux`
+  const pick = await pickSonarScanner(sonarConfig.scanner);
   const env = {
     ...process.env,
-    SONAR_HOST_URL: host,
+    SONAR_HOST_URL: pick.type === "native" ? rawHost : host,
     SONAR_TOKEN: token || "",
     SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig)
   };
 
-  const result = await runCommand("docker", args, { timeout: scannerTimeout, env });
+  let cmd, args;
+  if (pick.type === "native") {
+    cmd = pick.bin;
+    args = [];
+  } else {
+    cmd = "docker";
+    args = [
+      "run",
+      "--rm",
+      "-v",
+      `${process.cwd()}:/usr/src`,
+      ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
+      ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
+      "-e", "SONAR_HOST_URL",
+      "-e", "SONAR_TOKEN",
+      "-e", "SONAR_SCANNER_OPTS",
+      "sonarsource/sonar-scanner-cli"
+    ];
+  }
+
+  const result = await runCommand(cmd, args, { timeout: scannerTimeout, env });
   return {
     ok: result.exitCode === 0,
     projectKey: effectiveProjectKey,
+    scanner: pick.type,
     stdout: result.stdout,
     stderr: result.stderr,
     exitCode: result.exitCode

package/src/sync/apply-canvas-patch.js

@@ -0,0 +1,55 @@
+/**
+ * kj sync --apply — append a drift patch to the Canvas markdown.
+ *
+ * KJC-TSK-0348. Pure data + I/O: reads the Canvas at `canvasPath`, drops a
+ * `.bak` snapshot alongside it, appends an HTML-comment block describing
+ * untracked / missing / covered files, and atomically renames a `.tmp`
+ * over the target. Comments are inert for the Canvas parser, so the
+ * patched file stays structurally valid — the user converts the TODOs
+ * into Operations by hand.
+ */
+
+import { promises as fs } from "node:fs";
+
+function tempPath(target) {
+  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+}
+
+export function renderDriftComment(report) {
+  const lines = ["", `<!-- kj sync --apply (${new Date().toISOString()}) — review and convert into Operations as needed. -->`];
+  let mutations = 0;
+  if (report.untracked?.length) {
+    lines.push("<!-- Untracked files (modified, no Operation references them — add one): -->");
+    for (const u of report.untracked) { lines.push(`<!-- + ${u.path} -->`); mutations += 1; }
+  }
+  if (report.missing?.length) {
+    lines.push("<!-- Missing files (Operation file_hint points at a file that does not exist): -->");
+    for (const m of report.missing) { lines.push(`<!-- ! ${m.path}  [op #${(m.operationIndex ?? 0) + 1}] -->`); mutations += 1; }
+  }
+  if (report.covered?.length) {
+    lines.push("<!-- Covered (referenced and modified — consider extending the Approach): -->");
+    for (const c of report.covered) lines.push(`<!-- ~ ${c.path}  [op #${(c.operationIndex ?? 0) + 1}] -->`);
+  }
+  lines.push("<!-- /kj sync -->", "");
+  return { block: lines.join("\n"), mutations };
+}
+
+export async function applyCanvasPatch({ canvasPath, report }) {
+  if (!canvasPath || typeof canvasPath !== "string") throw new Error("applyCanvasPatch: canvasPath is required");
+  if (!report || typeof report !== "object") throw new Error("applyCanvasPatch: report is required");
+  const hasDrift = (report.untracked?.length || 0) + (report.missing?.length || 0) > 0;
+  if (!hasDrift) return { patchedPath: canvasPath, backupPath: null, mutations: 0, skipped: true };
+
+  let original;
+  try { original = await fs.readFile(canvasPath, "utf-8"); }
+  catch (err) { throw new Error(`applyCanvasPatch: cannot read canvas ${canvasPath}: ${err.message}`, { cause: err }); }
+
+  const backupPath = `${canvasPath}.bak`;
+  await fs.writeFile(backupPath, original, "utf-8");
+  const { block, mutations } = renderDriftComment(report);
+  const trimmed = original.endsWith("\n") ? original : `${original}\n`;
+  const tmp = tempPath(canvasPath);
+  await fs.writeFile(tmp, `${trimmed}${block}\n`, "utf-8");
+  await fs.rename(tmp, canvasPath);
+  return { patchedPath: canvasPath, backupPath, mutations };
+}

package/src/utils/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -12,6 +13,17 @@ function vitestRoot() {
     os.tmpdir(),
     `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
   );
+  // KJC-BUG-0075: clean up on clean exit so /tmp doesn't accumulate one
+  // dir per fork × run. `process.on('exit')` runs synchronously and only
+  // for graceful exits — SIGKILL leaks survive but are caught by the
+  // global-setup mtime purge at the start of the next run.
+  process.on("exit", () => {
+    try {
+      fs.rmSync(_vitestRoot, { recursive: true, force: true });
+    } catch {
+      // best-effort: never crash a test process on cleanup failure
+    }
+  });
   return _vitestRoot;
 }
 

package/src/utils/quota-simulator.js

@@ -0,0 +1,56 @@
+// KJ_SIMULATE_QUOTA — testing hook for the standby flow. See
+// docs/quota-simulation.md. KJC-TSK-0493.
+
+let _warned = false;
+
+export function parseQuotaSimulationConfig(env = process.env) {
+  const trigger = env.KJ_SIMULATE_QUOTA;
+  if (!trigger) return null;
+  const m = /^after-iter-(\d+)$/i.exec(String(trigger).trim());
+  if (!m) {
+    if (!_warned) {
+      // eslint-disable-next-line no-console
+      console.warn(`[KJ_SIMULATE_QUOTA] Ignoring malformed value "${trigger}". Expected "after-iter-<N>".`);
+      _warned = true;
+    }
+    return null;
+  }
+  return {
+    afterIter: Number.parseInt(m[1], 10),
+    resetIso: env.KJ_SIMULATE_QUOTA_RESET || new Date(Date.now() + 3600_000).toISOString(),
+    agent: String(env.KJ_SIMULATE_QUOTA_AGENT || "claude").toLowerCase(),
+  };
+}
+
+const SYNTHETIC_MSG = {
+  claude: (iso) => `[KJ_SIMULATE_QUOTA] Claude Pro usage limit reached. weekly limit. resets at ${iso}`,
+  codex: () => `[KJ_SIMULATE_QUOTA] You have exceeded your current quota. retry after 60 seconds`,
+  gemini: () => `[KJ_SIMULATE_QUOTA] Resource exhausted: quota exceeded. retry after 60 seconds`,
+};
+
+export function buildSyntheticQuotaMessage(agent, resetIso) {
+  return (SYNTHETIC_MSG[agent] || SYNTHETIC_MSG.claude)(resetIso);
+}
+
+export function shouldSimulateQuota({ iteration, agent }, env = process.env) {
+  const cfg = parseQuotaSimulationConfig(env);
+  if (!cfg) return null;
+  if (Number(iteration) < cfg.afterIter) return null;
+  const a = String(agent || "").toLowerCase();
+  if (cfg.agent !== "any" && cfg.agent !== a) return null;
+  return { resetIso: cfg.resetIso, agent: a || cfg.agent };
+}
+
+// Mutates execResult: forces ok=false and prepends the synthetic quota
+// line to result.error so the existing detectRateLimit branch fires.
+export function applyQuotaSimulation(execResult, { iteration, agent }, env = process.env) {
+  const fire = shouldSimulateQuota({ iteration, agent }, env);
+  if (!fire || !execResult || typeof execResult !== "object") return false;
+  if (!execResult.result || typeof execResult.result !== "object") execResult.result = {};
+  execResult.result.error = `${buildSyntheticQuotaMessage(fire.agent, fire.resetIso)}\n${execResult.result.error || ""}`;
+  execResult.ok = false;
+  return true;
+}
+
+// Test seam — reset the one-shot warning between unit tests.
+export function _resetSimulatorWarning() { _warned = false; }

package/src/utils/repo-cleaner.js

@@ -0,0 +1,79 @@
+/**
+ * Repo-level cleaner — KJC-TSK-0499 PR1. Read-only collector that
+ * surfaces stale local artifacts so the user can decide what to drop.
+ * Detects: branches merged into a base ref, branches with `[gone]`
+ * upstream, top-level `dist/` `coverage/` `logs/` older than N days,
+ * `*.tmp` / `*.bak` older than N days. Never spawns destructive ops.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execa } from "execa";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const STALE_DIRS = ["dist", "coverage", "logs"];
+const STALE_FILE_RX = /\.(tmp|bak)$/;
+
+async function safeGit(cwd, args) {
+  try {
+    const { stdout, exitCode } = await execa("git", args, { cwd, reject: false });
+    return exitCode === 0 ? stdout : "";
+  } catch { return ""; }
+}
+
+async function collectBranches(cwd, baseRef) {
+  const items = [];
+  const baseShort = baseRef.replace(/^origin\//, "");
+  const current = (await safeGit(cwd, ["symbolic-ref", "--short", "HEAD"])).trim();
+  const merged = await safeGit(cwd, ["branch", "--merged", baseRef, "--format=%(refname:short)"]);
+  for (const raw of merged.split("\n")) {
+    const name = raw.trim();
+    if (!name || name === current || name === baseShort) continue;
+    items.push({ kind: "branch", target: name, reason: `merged into ${baseRef}`, command: `git branch -d ${name}` });
+  }
+  for (const line of (await safeGit(cwd, ["branch", "-vv"])).split("\n")) {
+    const m = line.match(/^[\s*]+(\S+)\s+\S+\s+\[[^:]+: gone\]/);
+    if (m && m[1] !== current) items.push({ kind: "branch-gone", target: m[1], reason: "upstream gone", command: `git branch -D ${m[1]}` });
+  }
+  return items;
+}
+
+async function ageMs(p) {
+  try { return Date.now() - (await fs.stat(p)).mtimeMs; } catch { return -1; }
+}
+
+async function collectStale(cwd, maxAgeDays) {
+  const cutoff = maxAgeDays * DAY_MS;
+  const items = [];
+  for (const name of STALE_DIRS) {
+    const full = path.join(cwd, name);
+    if (await ageMs(full) > cutoff) {
+      items.push({ kind: "dir", target: full, reason: `${name}/ older than ${maxAgeDays}d`, command: `rm -rf ${full}` });
+    }
+  }
+  let entries = [];
+  try { entries = await fs.readdir(cwd, { withFileTypes: true }); } catch { /* cwd unreadable */ }
+  for (const e of entries) {
+    if (!e.isFile() || !STALE_FILE_RX.test(e.name)) continue;
+    const full = path.join(cwd, e.name);
+    if (await ageMs(full) > cutoff) {
+      items.push({ kind: "file", target: full, reason: `${path.extname(e.name)} older than ${maxAgeDays}d`, command: `rm -f ${full}` });
+    }
+  }
+  return items;
+}
+
+/**
+ * Discover repo-level cleanup candidates.
+ * @param {object} opts
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {number} [opts.maxAgeDays=7]
+ * @param {string} [opts.mergedTo="origin/main"]
+ * @returns {Promise<{candidates: Array, errors: Array}>}
+ */
+export async function collectRepoCandidates({ cwd = process.cwd(), maxAgeDays = 7, mergedTo = "origin/main" } = {}) {
+  const candidates = [];
+  const errors = [];
+  try { candidates.push(...await collectBranches(cwd, mergedTo)); } catch (e) { errors.push({ stage: "branches", error: String(e?.message ?? e) }); }
+  try { candidates.push(...await collectStale(cwd, maxAgeDays)); } catch (e) { errors.push({ stage: "stale", error: String(e?.message ?? e) }); }
+  return { candidates, errors };
+}