karajan-code 1.2.0

package/src/utils/agent-detect.js

@@ -0,0 +1,32 @@
+import { runCommand } from "./process.js";
+import { resolveBin } from "../agents/resolve-bin.js";
+
+const KNOWN_AGENTS = [
+  { name: "claude", install: "npm install -g @anthropic-ai/claude-code" },
+  { name: "codex", install: "npm install -g @openai/codex" },
+  { name: "gemini", install: "npm install -g @anthropic-ai/gemini-code (or check Gemini CLI docs)" },
+  { name: "aider", install: "pip install aider-chat" }
+];
+
+export async function checkBinary(name, versionArg = "--version") {
+  const resolved = resolveBin(name);
+  const res = await runCommand(resolved, [versionArg]);
+  const version = (res.stdout || res.stderr || "").split("\n")[0].trim();
+  return { ok: res.exitCode === 0, version, path: resolved };
+}
+
+export async function detectAvailableAgents() {
+  const results = [];
+  for (const agent of KNOWN_AGENTS) {
+    const check = await checkBinary(agent.name);
+    results.push({
+      name: agent.name,
+      available: check.ok,
+      version: check.ok ? check.version : null,
+      install: agent.install
+    });
+  }
+  return results;
+}
+
+export { KNOWN_AGENTS };

package/src/utils/budget.js

@@ -0,0 +1,123 @@
+import { calculateUsageCostUsd, DEFAULT_MODEL_PRICING, mergePricing } from "./pricing.js";
+
+function toSafeNumber(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+function roundUsd(value) {
+  return Number(toSafeNumber(value).toFixed(6));
+}
+
+function normalizeLimit(limit) {
+  if (limit === null || limit === undefined || limit === "") return null;
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return n;
+}
+
+function addToBreakdown(map, key, entry) {
+  const current = map[key] || { tokens_in: 0, tokens_out: 0, total_tokens: 0, total_cost_usd: 0, count: 0 };
+  current.tokens_in += entry.tokens_in;
+  current.tokens_out += entry.tokens_out;
+  current.total_tokens += entry.tokens_in + entry.tokens_out;
+  current.total_cost_usd = roundUsd(current.total_cost_usd + entry.cost_usd);
+  current.count += 1;
+  map[key] = current;
+}
+
+export class BudgetTracker {
+  constructor(options = {}) {
+    this.entries = [];
+    this.pricing = mergePricing(DEFAULT_MODEL_PRICING, options.pricing || {});
+  }
+
+  record({ role, provider, model, tokens_in, tokens_out, cost_usd, duration_ms, stage_index } = {}) {
+    const safeTokensIn = toSafeNumber(tokens_in);
+    const safeTokensOut = toSafeNumber(tokens_out);
+    const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
+    const modelName = model || provider || null;
+    const computedCost = calculateUsageCostUsd({
+      model: modelName,
+      tokens_in: safeTokensIn,
+      tokens_out: safeTokensOut,
+      pricing: this.pricing
+    });
+    const entry = {
+      role: role || "unknown",
+      provider: provider || "unknown",
+      model: modelName,
+      timestamp: new Date().toISOString(),
+      tokens_in: safeTokensIn,
+      tokens_out: safeTokensOut,
+      cost_usd: roundUsd(hasExplicitCost ? cost_usd : computedCost)
+    };
+    if (duration_ms !== undefined && duration_ms !== null) {
+      entry.duration_ms = toSafeNumber(duration_ms);
+    }
+    if (stage_index !== undefined && stage_index !== null) {
+      entry.stage_index = Number(stage_index);
+    }
+    this.entries.push(entry);
+    return entry;
+  }
+
+  total() {
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let totalCost = 0;
+    for (const entry of this.entries) {
+      tokensIn += entry.tokens_in;
+      tokensOut += entry.tokens_out;
+      totalCost = roundUsd(totalCost + entry.cost_usd);
+    }
+    return {
+      tokens_in: tokensIn,
+      tokens_out: tokensOut,
+      cost_usd: totalCost
+    };
+  }
+
+  remaining(limit) {
+    const n = normalizeLimit(limit);
+    if (n === null) return Infinity;
+    return roundUsd(n - this.total().cost_usd);
+  }
+
+  isOverBudget(limit) {
+    const n = normalizeLimit(limit);
+    if (n === null) return false;
+    return this.total().cost_usd > n;
+  }
+
+  summary() {
+    const totals = this.total();
+    const byRole = {};
+
+    for (const entry of this.entries) {
+      addToBreakdown(byRole, entry.role, entry);
+    }
+
+    return {
+      total_tokens: totals.tokens_in + totals.tokens_out,
+      total_cost_usd: totals.cost_usd,
+      breakdown_by_role: byRole,
+      entries: [...this.entries]
+    };
+  }
+
+  trace() {
+    return this.entries.map((entry, index) => ({
+      index: entry.stage_index ?? index,
+      role: entry.role,
+      provider: entry.provider,
+      model: entry.model,
+      timestamp: entry.timestamp,
+      duration_ms: entry.duration_ms ?? null,
+      tokens_in: entry.tokens_in,
+      tokens_out: entry.tokens_out,
+      cost_usd: entry.cost_usd
+    }));
+  }
+}

package/src/utils/display.js

@@ -0,0 +1,346 @@
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+  white: "\x1b[37m",
+  magenta: "\x1b[35m"
+};
+
+const ICONS = {
+  "session:start": "\u25b6",
+  "planner:start": "\ud83e\udde0",
+  "planner:end": "\ud83e\udde0",
+  "researcher:start": "\ud83d\udd2c",
+  "researcher:end": "\ud83d\udd2c",
+  "iteration:start": "\u25b6",
+  "coder:start": "\ud83d\udd28",
+  "coder:end": "\ud83d\udd28",
+  "refactorer:start": "\u267b\ufe0f",
+  "refactorer:end": "\u267b\ufe0f",
+  "tdd:result": "\ud83d\udccb",
+  "sonar:start": "\ud83d\udd0d",
+  "sonar:end": "\ud83d\udd0d",
+  "reviewer:start": "\ud83d\udc41\ufe0f",
+  "reviewer:end": "\ud83d\udc41\ufe0f",
+  "tester:start": "\ud83e\uddea",
+  "tester:end": "\ud83e\uddea",
+  "security:start": "\ud83d\udd12",
+  "security:end": "\ud83d\udd12",
+  "solomon:start": "\u2696\ufe0f",
+  "solomon:end": "\u2696\ufe0f",
+  "solomon:escalate": "\u26a0\ufe0f",
+  "budget:update": "\ud83d\udcb8",
+  "iteration:end": "\u23f1\ufe0f",
+  "session:end": "\ud83c\udfc1",
+  question: "\u2753"
+};
+
+const STATUS_ICON = {
+  ok: `${ANSI.green}\u2705${ANSI.reset}`,
+  fail: `${ANSI.red}\u274c${ANSI.reset}`,
+  paused: `${ANSI.yellow}\u23f8\ufe0f${ANSI.reset}`,
+  running: `${ANSI.cyan}\u25b6${ANSI.reset}`
+};
+
+export function formatElapsed(ms) {
+  const totalSec = Math.floor((ms || 0) / 1000);
+  const min = String(Math.floor(totalSec / 60)).padStart(2, "0");
+  const sec = String(totalSec % 60).padStart(2, "0");
+  return `${min}:${sec}`;
+}
+
+const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
+
+export function printHeader({ task, config }) {
+  const version = "0.1.0";
+  console.log(BAR);
+  console.log(`${ANSI.bold}${ANSI.cyan}\u25b6 Karajan Code v${version}${ANSI.reset}`);
+  console.log(BAR);
+  console.log(`${ANSI.bold}Task:${ANSI.reset} ${task}`);
+  console.log(
+    `${ANSI.bold}Coder:${ANSI.reset} ${config.roles?.coder?.provider || config.coder} ${ANSI.dim}|${ANSI.reset} ${ANSI.bold}Reviewer:${ANSI.reset} ${config.roles?.reviewer?.provider || config.reviewer}`
+  );
+  console.log(
+    `${ANSI.bold}Max iterations:${ANSI.reset} ${config.max_iterations} ${ANSI.dim}|${ANSI.reset} ${ANSI.bold}Timeout:${ANSI.reset} ${config.session.max_total_minutes}min`
+  );
+
+  const pipeline = config.pipeline || {};
+  const activeRoles = [];
+  if (pipeline.planner?.enabled) activeRoles.push(`Planner (${config.roles?.planner?.provider || "?"})`);
+  if (pipeline.researcher?.enabled) activeRoles.push(`Researcher (${config.roles?.researcher?.provider || "?"})`);
+  if (pipeline.tester?.enabled) activeRoles.push("Tester");
+  if (pipeline.security?.enabled) activeRoles.push("Security");
+  if (pipeline.solomon?.enabled) activeRoles.push(`Solomon (${config.roles?.solomon?.provider || "?"})`);
+  if (activeRoles.length > 0) {
+    console.log(`${ANSI.bold}Pipeline:${ANSI.reset} ${activeRoles.join(` ${ANSI.dim}|${ANSI.reset} `)}`);
+  }
+
+  console.log(BAR);
+  console.log();
+}
+
+export function printEvent(event) {
+  const icon = ICONS[event.type] || "\u2022";
+  const elapsed = event.elapsed !== undefined ? `${ANSI.dim}[${formatElapsed(event.elapsed)}]${ANSI.reset}` : "";
+  const status = event.status ? STATUS_ICON[event.status] || "" : "";
+
+  switch (event.type) {
+    case "session:start":
+      break;
+
+    case "iteration:start":
+      console.log(
+        `\n${ANSI.bold}${icon} Iteration ${event.detail?.iteration}/${event.detail?.maxIterations}${ANSI.reset}  ${elapsed}`
+      );
+      break;
+
+    case "planner:start":
+      console.log(`  \u251c\u2500 ${icon} Planner (${event.detail?.planner || "?"}) running...`);
+      break;
+
+    case "planner:end":
+      console.log(`  \u251c\u2500 ${status} Planner completed  ${elapsed}`);
+      break;
+
+    case "coder:start":
+      console.log(`  \u251c\u2500 ${icon} Coder (${event.detail?.coder || "?"}) running...`);
+      break;
+
+    case "coder:end":
+      console.log(`  \u251c\u2500 ${status} Coder completed  ${elapsed}`);
+      break;
+
+    case "refactorer:start":
+      console.log(`  \u251c\u2500 ${icon} Refactorer (${event.detail?.refactorer || "?"}) running...`);
+      break;
+
+    case "refactorer:end":
+      console.log(`  \u251c\u2500 ${status} Refactorer completed  ${elapsed}`);
+      break;
+
+    case "tdd:result": {
+      const tdd = event.detail || {};
+      const label = tdd.ok ? `${ANSI.green}PASS${ANSI.reset}` : `${ANSI.red}FAIL${ANSI.reset}`;
+      const files = tdd.sourceFiles !== undefined ? ` (${tdd.sourceFiles} src, ${tdd.testFiles} test)` : "";
+      console.log(`  \u251c\u2500 ${icon} TDD policy: ${label}${files}`);
+      break;
+    }
+
+    case "researcher:start":
+      console.log(`  \u251c\u2500 ${icon} Researcher (${event.detail?.researcher || "?"}) investigating...`);
+      break;
+
+    case "researcher:end":
+      console.log(`  \u251c\u2500 ${status} Researcher completed  ${elapsed}`);
+      break;
+
+    case "sonar:start":
+      console.log(`  \u251c\u2500 ${icon} SonarQube scanning...`);
+      break;
+
+    case "sonar:end": {
+      const gate = event.detail?.gateStatus || "?";
+      const gateColor = gate === "OK" ? ANSI.green : ANSI.red;
+      console.log(`  \u251c\u2500 ${status} Quality gate: ${gateColor}${gate}${ANSI.reset}  ${elapsed}`);
+      break;
+    }
+
+    case "reviewer:start":
+      console.log(`  \u251c\u2500 ${icon} Reviewer (${event.detail?.reviewer || "?"}) running...`);
+      break;
+
+    case "reviewer:end": {
+      const review = event.detail || {};
+      if (review.approved) {
+        console.log(`  \u251c\u2500 ${ANSI.green}\u2705 Review: APPROVED${ANSI.reset}  ${elapsed}`);
+      } else {
+        const count = review.blockingCount || 0;
+        console.log(`  \u251c\u2500 ${ANSI.red}\u274c Review: REJECTED (${count} blocking)${ANSI.reset}`);
+        if (review.issues) {
+          for (const issue of review.issues) {
+            console.log(`  \u2502   ${ANSI.dim}${issue}${ANSI.reset}`);
+          }
+        }
+      }
+      break;
+    }
+
+    case "tester:start":
+      console.log(`  \u251c\u2500 ${icon} Tester evaluating...`);
+      break;
+
+    case "tester:end": {
+      const testerOk = event.detail?.ok !== false;
+      if (testerOk) {
+        console.log(`  \u251c\u2500 ${ANSI.green}\u2705 Tester: passed${ANSI.reset}  ${elapsed}`);
+      } else {
+        const testerSummary = event.detail?.summary || "issues found";
+        console.log(`  \u251c\u2500 ${ANSI.red}\u274c Tester: ${testerSummary}${ANSI.reset}  ${elapsed}`);
+      }
+      break;
+    }
+
+    case "security:start":
+      console.log(`  \u251c\u2500 ${icon} Security auditing...`);
+      break;
+
+    case "security:end": {
+      const secOk = event.detail?.ok !== false;
+      if (secOk) {
+        console.log(`  \u251c\u2500 ${ANSI.green}\u2705 Security: passed${ANSI.reset}  ${elapsed}`);
+      } else {
+        const secSummary = event.detail?.summary || "vulnerabilities found";
+        console.log(`  \u251c\u2500 ${ANSI.red}\u274c Security: ${secSummary}${ANSI.reset}  ${elapsed}`);
+      }
+      break;
+    }
+
+    case "solomon:start":
+      console.log(`  \u251c\u2500 ${icon} Solomon arbitrating ${event.detail?.conflictStage || "?"} conflict...`);
+      break;
+
+    case "solomon:end": {
+      const ruling = event.detail?.ruling || "unknown";
+      const rulingUpper = ruling.toUpperCase().replace(/_/g, " ");
+      if (ruling === "approve") {
+        const dismissedCount = event.detail?.dismissed?.length || 0;
+        console.log(`  \u251c\u2500 ${ANSI.green}\u2696\ufe0f Solomon: APPROVE${dismissedCount > 0 ? ` (${dismissedCount} dismissed)` : ""}${ANSI.reset}  ${elapsed}`);
+      } else if (ruling === "approve_with_conditions") {
+        const condCount = event.detail?.conditions?.length || 0;
+        console.log(`  \u251c\u2500 ${ANSI.yellow}\u2696\ufe0f Solomon: ${condCount} condition${condCount !== 1 ? "s" : ""}${ANSI.reset}  ${elapsed}`);
+        if (event.detail?.conditions) {
+          for (const cond of event.detail.conditions) {
+            console.log(`  \u2502   ${ANSI.dim}${cond}${ANSI.reset}`);
+          }
+        }
+      } else if (ruling === "escalate_human") {
+        const reason = event.detail?.escalate_reason || "unknown reason";
+        console.log(`  \u251c\u2500 ${ANSI.red}\u2696\ufe0f Solomon: ESCALATE \u2014 ${reason}${ANSI.reset}  ${elapsed}`);
+      } else if (ruling === "create_subtask") {
+        const subtaskTitle = event.detail?.subtask?.title || "untitled";
+        console.log(`  \u251c\u2500 ${ANSI.magenta}\u2696\ufe0f Solomon: SUBTASK \u2014 ${subtaskTitle}${ANSI.reset}  ${elapsed}`);
+      } else {
+        console.log(`  \u251c\u2500 \u2696\ufe0f Solomon: ${rulingUpper}  ${elapsed}`);
+      }
+      break;
+    }
+
+    case "solomon:escalate": {
+      const subloop = event.detail?.subloop || "?";
+      const retryCount = event.detail?.retryCount || 0;
+      const limit = event.detail?.limit || "?";
+      console.log(`  \u251c\u2500 ${icon} ${subloop} sub-loop limit reached (${retryCount}/${limit}), invoking Solomon...`);
+      break;
+    }
+
+    case "iteration:end":
+      console.log(`  \u2514\u2500 ${icon} Duration: ${formatElapsed(event.detail?.duration)}  ${elapsed}`);
+      break;
+
+    case "budget:update": {
+      const total = Number(event.detail?.total_cost_usd || 0);
+      const max = Number(event.detail?.max_budget_usd);
+      const pct = Number(event.detail?.pct_used ?? 0);
+      const warn = Number(event.detail?.warn_threshold_pct ?? 80);
+      const color = max > 0 && pct >= 100 ? ANSI.red : max > 0 && pct >= warn ? ANSI.yellow : ANSI.green;
+      if (Number.isFinite(max) && max >= 0) {
+        console.log(`  \u251c\u2500 ${icon} Budget: ${color}$${total.toFixed(2)} / $${max.toFixed(2)} (${pct.toFixed(1)}%)${ANSI.reset}`);
+      }
+      break;
+    }
+
+    case "session:end": {
+      console.log();
+      const resultLabel = event.detail?.approved
+        ? `${ANSI.bold}${ANSI.green}APPROVED${ANSI.reset}`
+        : `${ANSI.bold}${ANSI.red}${event.detail?.reason || "FAILED"}${ANSI.reset}`;
+      console.log(`${icon} Result: ${resultLabel}  ${elapsed}`);
+
+      const stages = event.detail?.stages;
+      if (stages) {
+        if (stages.researcher?.summary) {
+          console.log(`  ${ANSI.dim}\ud83d\udd2c Research: ${stages.researcher.summary}${ANSI.reset}`);
+        }
+        if (stages.planner?.title || stages.planner?.approach || stages.planner?.completedSteps?.length) {
+          const planParts = [];
+          if (stages.planner.title) planParts.push(stages.planner.title);
+          if (stages.planner.approach) planParts.push(`approach: ${stages.planner.approach}`);
+          console.log(`  ${ANSI.dim}\ud83d\uddfa Plan: ${planParts.join(" | ")}${ANSI.reset}`);
+          for (const step of stages.planner.completedSteps || []) {
+            console.log(`  ${ANSI.dim}   \u2713 ${step}${ANSI.reset}`);
+          }
+        }
+        if (stages.tester?.summary) {
+          console.log(`  ${ANSI.dim}\ud83e\uddea Tester: ${stages.tester.summary}${ANSI.reset}`);
+        }
+        if (stages.security?.summary) {
+          console.log(`  ${ANSI.dim}\ud83d\udd12 Security: ${stages.security.summary}${ANSI.reset}`);
+        }
+        if (stages.sonar) {
+          const gateLabel = stages.sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
+          console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${stages.sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${stages.sonar.openIssues ?? 0} issues)${ANSI.reset}`);
+          if (typeof stages.sonar.issuesInitial === "number" || typeof stages.sonar.issuesResolved === "number") {
+            const issuesInitial = stages.sonar.issuesInitial ?? stages.sonar.openIssues ?? 0;
+            const issuesFinal = stages.sonar.issuesFinal ?? stages.sonar.openIssues ?? 0;
+            const issuesResolved = stages.sonar.issuesResolved ?? Math.max(issuesInitial - issuesFinal, 0);
+            console.log(`  ${ANSI.dim}\ud83d\udee0 Issues: ${issuesInitial} detected, ${issuesFinal} open, ${issuesResolved} resolved${ANSI.reset}`);
+          }
+        }
+      }
+
+      const git = event.detail?.git;
+      if (git?.branch) {
+        const parts = [`branch: ${git.branch}`];
+        if (git.committed) parts.push("committed");
+        if (git.pushed) parts.push("pushed");
+        if (git.pr || git.prUrl) parts.push(`PR: ${git.pr || git.prUrl}`);
+        console.log(`  ${ANSI.dim}\ud83d\udcce Git: ${parts.join(", ")}${ANSI.reset}`);
+        if (Array.isArray(git.commits) && git.commits.length > 0) {
+          console.log(`  ${ANSI.dim}\ud83e\uddfe Commits:${ANSI.reset}`);
+          for (const commit of git.commits) {
+            const shortHash = (commit.hash || "").slice(0, 7) || "unknown";
+            const message = commit.message || "";
+            console.log(`  ${ANSI.dim}   - ${shortHash} ${message}${ANSI.reset}`);
+          }
+        }
+      }
+
+      const budget = event.detail?.budget;
+      if (budget) {
+        console.log(`  ${ANSI.dim}\ud83d\udcb0 Total tokens: ${budget.total_tokens ?? 0}${ANSI.reset}`);
+        console.log(`  ${ANSI.dim}\ud83d\udcb0 Total cost: $${Number(budget.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`);
+        const byRole = budget.breakdown_by_role || {};
+        const roles = Object.entries(byRole);
+        if (roles.length > 0) {
+          for (const [role, metrics] of roles) {
+            console.log(
+              `  ${ANSI.dim}   - ${role}: ${metrics.total_tokens ?? 0} tokens, $${Number(metrics.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`
+            );
+          }
+        }
+      }
+
+      console.log(`${ANSI.dim}Session: ${event.sessionId}${ANSI.reset}`);
+      break;
+    }
+
+    case "question":
+      console.log();
+      console.log(`${ANSI.bold}${ANSI.yellow}${icon} Paused - question:${ANSI.reset}`);
+      console.log(`  ${event.detail?.question || event.message}`);
+      console.log(`${ANSI.dim}Resume with: kj resume ${event.sessionId} --answer "<response>"${ANSI.reset}`);
+      break;
+
+    case "agent:output":
+      console.log(`  \u2502 ${ANSI.dim}${event.message}${ANSI.reset}`);
+      break;
+
+    default:
+      console.log(`  \u251c\u2500 ${icon} ${event.message || event.type}  ${elapsed}`);
+  }
+}

package/src/utils/events.js

@@ -0,0 +1,23 @@
+/**
+ * Pipeline event helpers.
+ * Extracted from orchestrator.js for reuse across modules.
+ */
+
+export function emitProgress(emitter, data) {
+  if (!emitter) return;
+  emitter.emit("progress", data);
+}
+
+export function makeEvent(type, base, extra = {}) {
+  return {
+    type,
+    sessionId: base.sessionId,
+    iteration: base.iteration,
+    stage: base.stage,
+    status: extra.status || "ok",
+    message: extra.message || type,
+    detail: extra.detail || {},
+    elapsed: base.startedAt ? Date.now() - base.startedAt : 0,
+    timestamp: new Date().toISOString()
+  };
+}

package/src/utils/fs.js

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+export async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveFromCwd(...parts) {
+  return path.resolve(process.cwd(), ...parts);
+}

package/src/utils/git.js

@@ -0,0 +1,101 @@
+import { runCommand } from "./process.js";
+
+function slugifyTask(task) {
+  return String(task)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+async function runGit(args, options = {}) {
+  const res = await runCommand("git", args, options);
+  if (res.exitCode !== 0) {
+    throw new Error(`git ${args.join(" ")} failed: ${res.stderr || res.stdout}`);
+  }
+  return res.stdout.trim();
+}
+
+export async function ensureGitRepo() {
+  const res = await runCommand("git", ["rev-parse", "--is-inside-work-tree"]);
+  return res.exitCode === 0 && res.stdout.trim() === "true";
+}
+
+export async function currentBranch() {
+  return runGit(["rev-parse", "--abbrev-ref", "HEAD"]);
+}
+
+export async function fetchBase(baseBranch) {
+  await runGit(["fetch", "origin", baseBranch]);
+}
+
+export async function revParse(ref) {
+  return runGit(["rev-parse", ref]);
+}
+
+export async function syncBaseBranch({ baseBranch, autoRebase }) {
+  const local = await revParse(baseBranch);
+  const remote = await revParse(`origin/${baseBranch}`);
+  if (local === remote) return { synced: true, rebased: false };
+
+  if (!autoRebase) {
+    throw new Error(
+      `Base branch '${baseBranch}' is behind origin/${baseBranch}. Re-run with auto-rebase enabled or rebase manually.`
+    );
+  }
+
+  await runGit(["rebase", `origin/${baseBranch}`]);
+  return { synced: true, rebased: true };
+}
+
+export async function ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase }) {
+  const mergeBase = await runGit(["merge-base", branch, `origin/${baseBranch}`]);
+  const remoteBase = await revParse(`origin/${baseBranch}`);
+  if (mergeBase === remoteBase) return { upToDate: true, rebased: false };
+
+  if (!autoRebase) {
+    throw new Error(
+      `Base branch '${baseBranch}' advanced during run. Re-run with auto-rebase enabled or rebase '${branch}' manually.`
+    );
+  }
+
+  await runGit(["rebase", `origin/${baseBranch}`]);
+  return { upToDate: true, rebased: true };
+}
+
+export async function createBranch(branchName) {
+  await runGit(["checkout", "-b", branchName]);
+}
+
+export function buildBranchName(prefix, task) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 16);
+  return `${prefix}${slugifyTask(task) || "task"}-${stamp}`;
+}
+
+export async function hasChanges() {
+  const status = await runGit(["status", "--porcelain"]);
+  return status.length > 0;
+}
+
+export async function commitAll(message) {
+  await runGit(["add", "-A"]);
+  const changed = await hasChanges();
+  if (!changed) return { committed: false };
+  await runGit(["commit", "-m", message]);
+  const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"]);
+  const [hash, commitMessage] = raw.split("\x1f");
+  return { committed: true, commit: { hash, message: commitMessage } };
+}
+
+export async function pushBranch(branch) {
+  await runGit(["push", "-u", "origin", branch]);
+}
+
+export async function createPullRequest({ baseBranch, branch, title, body }) {
+  const args = ["pr", "create", "--base", baseBranch, "--head", branch, "--title", title, "--body", body];
+  const res = await runCommand("gh", args);
+  if (res.exitCode !== 0) {
+    throw new Error(`gh ${args.join(" ")} failed: ${res.stderr || res.stdout}`);
+  }
+  return res.stdout.trim();
+}