@karajan-family/code 4.21.0

package/src/utils/provider-env.js

@@ -0,0 +1,116 @@
+/**
+ * Mapping of AI provider → required environment variable(s), plus helpers to
+ * determine which ones are actually needed by the current active config.
+ *
+ * The Check subsystem uses this to validate tokens LAZILY: we only demand an
+ * API key when a role is configured to use the provider behind it. Providers
+ * that run fully locally (e.g. opencode via a self-hosted proxy) are marked
+ * `optional: true` and only warn if their key is missing.
+ */
+
+/**
+ * @typedef {Object} ProviderEnv
+ * @property {string} provider
+ * @property {string[]} envVars     - env var names that would satisfy the check (first match wins)
+ * @property {string} howToGetUrl   - user-facing URL to obtain a key
+ * @property {boolean} optional     - warn vs fail when missing
+ */
+
+/** @type {Record<string, ProviderEnv>} */
+export const PROVIDER_ENV = Object.freeze({
+  anthropic: {
+    provider: "anthropic",
+    envVars: ["ANTHROPIC_API_KEY"],
+    howToGetUrl: "https://console.anthropic.com/settings/keys",
+    optional: false,
+  },
+  openai: {
+    provider: "openai",
+    envVars: ["OPENAI_API_KEY"],
+    howToGetUrl: "https://platform.openai.com/api-keys",
+    optional: false,
+  },
+  google: {
+    provider: "google",
+    envVars: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    howToGetUrl: "https://aistudio.google.com/app/apikey",
+    optional: false,
+  },
+  opencode: {
+    provider: "opencode",
+    envVars: ["OPENCODE_API_KEY"],
+    howToGetUrl: "https://opencode.ai/docs",
+    optional: true, // local/self-hosted — may not need an API key
+  },
+  aider: {
+    provider: "aider",
+    envVars: ["AIDER_API_KEY"],
+    howToGetUrl: "https://aider.chat/docs/usage.html",
+    optional: true,
+  },
+});
+
+/**
+ * Returns true if any of the env vars for a provider is set non-empty.
+ * @param {ProviderEnv} entry
+ */
+export function hasEnvVar(entry) {
+  return entry.envVars.some((name) => {
+    const v = process.env[name];
+    return typeof v === "string" && v.trim().length > 0;
+  });
+}
+
+/**
+ * Walk the active config and collect the set of providers currently in use
+ * by at least one role.
+ *
+ * @param {Object} config - Karajan config (loaded)
+ * @returns {Set<string>} - set of provider slugs (e.g. "anthropic", "openai")
+ */
+export function collectActiveProviders(config) {
+  const providers = new Set();
+  const roles = config?.roles || {};
+  for (const [, roleCfg] of Object.entries(roles)) {
+    const provider = roleCfg?.provider;
+    if (typeof provider === "string" && provider.trim().length > 0) {
+      providers.add(provider);
+    }
+  }
+  // Also include top-level default coder/reviewer if set (legacy shape).
+  if (config?.coder) providers.add(config.coder);
+  if (config?.reviewer) providers.add(config.reviewer);
+  return providers;
+}
+
+/**
+ * Map active providers to the env vars we must validate.
+ *
+ * @param {Object} config
+ * @returns {ProviderEnv[]}
+ */
+export function getRequiredProviderEnvs(config) {
+  const active = collectActiveProviders(config);
+  const required = [];
+  for (const providerSlug of active) {
+    // Some configs store agent names (claude, codex, gemini) rather than
+    // canonical provider names. Map them.
+    const canonical = normalizeProvider(providerSlug);
+    const entry = PROVIDER_ENV[canonical];
+    if (entry) required.push(entry);
+  }
+  return required;
+}
+
+/**
+ * Normalize CLI/agent name to canonical provider slug.
+ */
+export function normalizeProvider(name) {
+  const lc = String(name || "").toLowerCase();
+  if (lc === "claude" || lc === "anthropic") return "anthropic";
+  if (lc === "codex" || lc === "openai") return "openai";
+  if (lc === "gemini" || lc === "google") return "google";
+  if (lc === "opencode") return "opencode";
+  if (lc === "aider") return "aider";
+  return lc;
+}

package/src/utils/qmd-collection.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { runCommand } from "./process.js";
+
+export const QMD_DEFAULT_PATHS = ["docs", ".reviews", ".karajan/plans"];
+
+export function projectSlug(projectDir) {
+  const base = path.basename(path.resolve(projectDir));
+  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+
+export function planQmdCollections(projectDir) {
+  const slug = projectSlug(projectDir);
+  const result = [];
+  for (const rel of QMD_DEFAULT_PATHS) {
+    const abs = path.join(projectDir, rel);
+    if (!existsSync(abs)) continue;
+    try { if (!statSync(abs).isDirectory()) continue; } catch { continue; }
+    const suffix = rel.replace(/^\./, "").replace(/[/\\]+/g, "-");
+    result.push({ name: `${slug}-${suffix}`, path: abs });
+  }
+  return result;
+}
+
+async function listExistingCollections() {
+  try {
+    const res = await runCommand("qmd", ["collection", "list"]);
+    if (res.exitCode !== 0) return new Set();
+    const names = new Set();
+    for (const line of (res.stdout || "").split("\n")) {
+      const m = line.match(/^([\w.-]+)\s+\(qmd:\/\//);
+      if (m) names.add(m[1]);
+    }
+    return names;
+  } catch { return new Set(); }
+}
+
+/**
+ * Register all default QMD collections for the project. Idempotent: skips
+ * collections already present in `qmd collection list`. qmd's CLI only
+ * accepts one path per `collection add`, so we register up to 3 sibling
+ * collections (`<slug>-docs`, `<slug>-reviews`, `<slug>-karajan-plans`).
+ */
+export async function registerQmdCollections(projectDir, logger) {
+  const planned = planQmdCollections(projectDir);
+  const result = { ok: true, added: [], skipped: [], errors: [] };
+  if (planned.length === 0) {
+    logger.info("QMD: no indexable folders yet (docs/, .reviews/, .karajan/plans/ all missing).");
+    return result;
+  }
+  const existing = await listExistingCollections();
+  for (const { name, path: abs } of planned) {
+    if (existing.has(name)) { result.skipped.push(name); continue; }
+    try {
+      const res = await runCommand("qmd", ["collection", "add", abs, "--name", name], { timeout: 60_000 });
+      if (res.exitCode === 0) {
+        result.added.push(name);
+      } else {
+        const err = (res.stderr || res.stdout || "").trim() || `exit code ${res.exitCode}`;
+        result.errors.push(`${name}: ${err}`);
+        result.ok = false;
+      }
+    } catch (err) {
+      result.errors.push(`${name}: ${err.message || String(err)}`);
+      result.ok = false;
+    }
+  }
+  if (result.added.length) logger.info(`QMD: registered ${result.added.length} collection(s): ${result.added.join(", ")}.`);
+  if (result.skipped.length) logger.info(`QMD: ${result.skipped.length} collection(s) already present, skipped.`);
+  for (const err of result.errors) logger.warn(`QMD: collection registration failed — ${err}`);
+  return result;
+}

package/src/utils/qmd-detect.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether QMD is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectQmd() {
+  try {
+    const result = await runCommand("qmd", ["--version"]);
+    if (result.exitCode === 0) {
+      const version = (result.stdout || "").trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch { /* qmd binary not found */
+    return { available: false, version: null };
+  }
+}

package/src/utils/qmd-install.js

@@ -0,0 +1,37 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectQmd } from "./qmd-detect.js";
+
+/**
+ * Install QMD using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installQmd(logger) {
+  const command = getInstallCommand("qmd");
+
+  logger.info("Installing QMD...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`QMD install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    const check = await detectQmd();
+    if (check.available) {
+      logger.info(`QMD ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("QMD install command succeeded but qmd binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`QMD install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

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/rate-limit-detector.js

@@ -0,0 +1,181 @@
+/**
+ * Detects rate limit / usage cap messages from CLI agent output.
+ * Returns { isRateLimit, agent, message, cooldownUntil, cooldownMs }
+ * where agent is the best guess of which CLI triggered it (or "unknown").
+ */
+
+/**
+ * Extracts cooldown timing from a rate limit message string.
+ * Returns { cooldownUntil, cooldownMs } where cooldownUntil is an ISO string
+ * and cooldownMs is milliseconds to wait, or both null if not found.
+ */
+export function parseCooldown(message) {
+  if (!message || typeof message !== "string") {
+    return { cooldownUntil: null, cooldownMs: null };
+  }
+
+  // 1. ISO timestamp: "try again after 2026-03-07T15:30:00Z"
+  //    Also: "resets at 2026-03-07T15:30:00Z"
+  const isoMatch = /(?:after|at)\s+(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)/i.exec(
+    message
+  );
+  if (isoMatch) {
+    const target = new Date(isoMatch[1]);
+    if (!Number.isNaN(target.getTime())) {
+      const ms = Math.max(0, target.getTime() - Date.now());
+      return { cooldownUntil: target.toISOString(), cooldownMs: ms };
+    }
+  }
+
+  // 4. Claude specific: "resets at 2026-03-07 15:30 UTC" (space-separated date/time)
+  const resetMatch = /resets?\s+at\s+(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\s*UTC/i.exec(
+    message
+  );
+  if (resetMatch) {
+    const target = new Date(`${resetMatch[1]}T${resetMatch[2]}:00Z`);
+    if (!Number.isNaN(target.getTime())) {
+      const ms = Math.max(0, target.getTime() - Date.now());
+      return { cooldownUntil: target.toISOString(), cooldownMs: ms };
+    }
+  }
+
+  // 5. Claude Code session / weekly limit: "resets 10:10pm (Europe/Madrid)" / "resets 4am"
+  //    KJC-BUG-0064: prefer the parenthesised IANA TZ when present so the
+  //    same stderr resolves to the same instant regardless of where kj runs
+  //    (CI in TZ=UTC was misclassifying Madrid 10:10pm as already past).
+  //    No TZ literal → fall back to the host's local TZ.
+  const ampmMatch = /reset(?:s|ting)?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b/i.exec(message);
+  if (ampmMatch) {
+    let hour = Number.parseInt(ampmMatch[1], 10) % 12;
+    if (/pm/i.test(ampmMatch[3])) hour += 12;
+    const minute = ampmMatch[2] ? Number.parseInt(ampmMatch[2], 10) : 0;
+    if (hour < 24 && minute < 60) {
+      const tzMatch = /\(([A-Za-z]+\/[A-Za-z_/+\-0-9]+)\)/.exec(message);
+      const tz = tzMatch ? tzMatch[1] : null;
+      const target = tz ? nextOccurrenceInTZ(hour, minute, tz) : nextOccurrenceLocal(hour, minute);
+      if (target) return { cooldownUntil: target.toISOString(), cooldownMs: Math.max(0, target.getTime() - Date.now()) };
+    }
+  }
+
+  // 2. Relative seconds: "retry after 120 seconds" / "retry in 120s" / "Retry-After: 120"
+  const secMatch = /(?:retry[\s-]*after|retry\s+in|wait)\s*:?\s*(\d+)\s*(?:seconds?|secs?|s\b)/i.exec(
+    message
+  ) || /Retry-After:\s*(\d+)/i.exec(message);
+  if (secMatch) {
+    const seconds = Number.parseInt(secMatch[1], 10);
+    const ms = seconds * 1000;
+    const target = new Date(Date.now() + ms);
+    return { cooldownUntil: target.toISOString(), cooldownMs: ms };
+  }
+
+  // 3. Relative minutes: "retry in 5 minutes" / "wait 5 min"
+  const minMatch = /(?:retry\s+in|wait|after)\s+(\d+)\s*(?:minutes?|mins?)/i.exec(
+    message
+  );
+  if (minMatch) {
+    const minutes = Number.parseInt(minMatch[1], 10);
+    const ms = minutes * 60 * 1000;
+    const target = new Date(Date.now() + ms);
+    return { cooldownUntil: target.toISOString(), cooldownMs: ms };
+  }
+
+  return { cooldownUntil: null, cooldownMs: null };
+}
+
+// KJC-BUG-0064 — TZ-aware "next occurrence of hour:minute" resolver.
+// Walks today + tomorrow in the given IANA TZ; returns the first instant
+// > now. Uses Intl.DateTimeFormat as the source of truth so it works on
+// any host TZ (CI runs UTC, dev runs Europe/Madrid, etc.).
+function nextOccurrenceInTZ(hour, minute, tz) {
+  try {
+    const now = new Date();
+    for (let dayOffset = 0; dayOffset <= 1; dayOffset++) {
+      const probe = new Date(now.getTime() + dayOffset * 86400000);
+      const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit",
+      }).formatToParts(probe).reduce((acc, p) => (p.type !== "literal" ? { ...acc, [p.type]: p.value } : acc), {});
+      if (!parts.year) return null;
+      const candidate = zonedTimeToUTC(Number(parts.year), Number(parts.month), Number(parts.day), hour, minute, tz);
+      if (candidate && candidate.getTime() > now.getTime()) return candidate;
+    }
+    return null;
+  } catch { return null; }
+}
+
+// Converts a wall-clock date + time in `tz` to a UTC Date.
+// Strategy: interpret year/month/day/hour/minute as naive UTC, see what
+// wall-clock that maps to in `tz`, derive the offset (tz - UTC at that
+// moment) and subtract it from the naive value to land on the true UTC.
+// One step suffices except at DST transitions (within ±1h, acceptable
+// for cooldown timing).
+function zonedTimeToUTC(year, month, day, hour, minute, tz) {
+  const naiveUTC = Date.UTC(year, month - 1, day, hour, minute);
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(naiveUTC)).reduce((acc, p) => (p.type !== "literal" ? { ...acc, [p.type]: p.value } : acc), {});
+  const wallInTZ = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour) % 24, Number(parts.minute));
+  const tzOffset = wallInTZ - naiveUTC; // positive when tz is ahead of UTC
+  return new Date(naiveUTC - tzOffset);
+}
+
+function nextOccurrenceLocal(hour, minute) {
+  const target = new Date();
+  target.setHours(hour, minute, 0, 0);
+  if (target.getTime() <= Date.now()) target.setDate(target.getDate() + 1);
+  return target;
+}
+
+const RATE_LIMIT_PATTERNS = [
+  // Claude CLI
+  { pattern: /usage limit/i, agent: "claude" },
+  { pattern: /plan's usage limit/i, agent: "claude" },
+  { pattern: /Claude Pro usage limit/i, agent: "claude" },
+  { pattern: /session limit/i, agent: "claude" },
+  { pattern: /weekly limit/i, agent: "claude" },
+
+  // OpenAI / Codex CLI
+  { pattern: /exceeded your current quota/i, agent: "codex" },
+
+  // Gemini CLI
+  { pattern: /resource exhausted/i, agent: "gemini" },
+  { pattern: /quota exceeded/i, agent: "gemini" },
+
+  // Generic rate limits (match any agent)
+  { pattern: /rate limit/i, agent: "unknown" },
+  { pattern: /token limit reached/i, agent: "unknown" },
+  { pattern: /\b429\b/, agent: "unknown" },
+  { pattern: /too many requests/i, agent: "unknown" },
+  { pattern: /throttl/i, agent: "unknown" },
+
+  // Provider outages / transient errors (treat like rate limits → retry)
+  { pattern: /\b500\b.*(?:internal server error|error)/i, agent: "unknown" },
+  { pattern: /\b502\b|bad gateway/i, agent: "unknown" },
+  { pattern: /\b503\b|service unavailable/i, agent: "unknown" },
+  { pattern: /\b504\b|gateway timeout/i, agent: "unknown" },
+  { pattern: /overloaded/i, agent: "unknown" },
+  { pattern: /ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket hang up/i, agent: "unknown" },
+  { pattern: /network error|fetch failed/i, agent: "unknown" },
+];
+
+export function detectRateLimit({ stderr = "", stdout = "" }) {
+  const combined = `${stderr}\n${stdout}`;
+
+  const PROVIDER_OUTAGE_PATTERNS = /\b50[0-4]\b|bad gateway|service unavailable|gateway timeout|overloaded|ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket hang up|network error|fetch failed/i;
+
+  for (const { pattern, agent } of RATE_LIMIT_PATTERNS) {
+    if (pattern.test(combined)) {
+      const matchedLine = combined.split("\n").find((l) => pattern.test(l)) || combined.trim();
+      const isProviderOutage = PROVIDER_OUTAGE_PATTERNS.test(matchedLine);
+      return {
+        isRateLimit: true,
+        isProviderOutage,
+        agent,
+        message: matchedLine.trim(),
+        ...parseCooldown(matchedLine)
+      };
+    }
+  }
+
+  return { isRateLimit: false, isProviderOutage: false, agent: "", message: "", cooldownUntil: null, cooldownMs: null };
+}

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 };
+}

package/src/utils/retry.js

@@ -0,0 +1,88 @@
+/**
+ * Generic retry utility with exponential backoff and jitter.
+ * Handles transient errors (429, 502, 503, timeouts) automatically.
+ */
+
+const TRANSIENT_HTTP_CODES = new Set([408, 429, 500, 502, 503, 504]);
+
+const TRANSIENT_ERROR_PATTERNS = [
+  "ETIMEDOUT", "ECONNREFUSED", "ECONNRESET", "EPIPE",
+  "ENETUNREACH", "EAI_AGAIN", "EHOSTUNREACH",
+  "socket hang up", "network error", "fetch failed"
+];
+
+const DEFAULT_OPTIONS = {
+  maxAttempts: 3,
+  initialBackoffMs: 1000,
+  maxBackoffMs: 30000,
+  backoffMultiplier: 2,
+  jitterFactor: 0.1,
+  onRetry: null
+};
+
+export function isTransientError(error) {
+  if (!error) return false;
+
+  if (error.httpStatus && TRANSIENT_HTTP_CODES.has(error.httpStatus)) return true;
+  if (error.status && TRANSIENT_HTTP_CODES.has(error.status)) return true;
+
+  const msg = (error.message || String(error)).toLowerCase();
+  return TRANSIENT_ERROR_PATTERNS.some((p) => msg.includes(p.toLowerCase()));
+}
+
+export function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1000;
+
+  const date = Date.parse(headerValue);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : null;
+  }
+  return null;
+}
+
+export function calculateBackoff(attempt, options = {}) {
+  const { initialBackoffMs = 1000, maxBackoffMs = 30000, backoffMultiplier = 2, jitterFactor = 0.1 } = options;
+
+  const base = initialBackoffMs * Math.pow(backoffMultiplier, attempt);
+  const capped = Math.min(base, maxBackoffMs);
+  const jitter = capped * jitterFactor * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= opts.maxAttempts - 1) break;
+      if (!isTransientError(error)) break;
+
+      let delayMs = calculateBackoff(attempt, opts);
+
+      const retryAfterMs = parseRetryAfter(error.retryAfter || error.headers?.get?.("retry-after"));
+      if (retryAfterMs) {
+        delayMs = Math.min(retryAfterMs, opts.maxBackoffMs);
+      }
+
+      if (opts.onRetry) {
+        opts.onRetry({ attempt, error, delayMs, maxAttempts: opts.maxAttempts });
+      }
+
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}